diff --git a/.claude/skills/rails-docs/SKILL.md b/.claude/skills/rails-docs/SKILL.md index c6beafb4..a90447f1 100644 --- a/.claude/skills/rails-docs/SKILL.md +++ b/.claude/skills/rails-docs/SKILL.md @@ -1,29 +1,46 @@ --- name: rails-docs -description: Use when asked about any Rails-specific topic — ActiveRecord, routing, controllers, views, mailers, jobs, Action Cable, Action Text, Active Storage, migrations, validations, callbacks, associations, caching, security, or Rails internals — including "how do I do X in Rails", debugging Rails behavior, or checking whether an API/option still exists or changed in Rails 8. Always consult the official guides and API docs rather than answering from memory alone, since trained knowledge can be stale or wrong about version-specific details, and this project pins Rails 8.0. +description: Use when asked about any Rails-specific topic — ActiveRecord, routing, controllers, views, mailers, jobs, Action Cable, Action Text, Active Storage, migrations, validations, callbacks, associations, caching, security, or Rails internals — including "how do I do X in Rails", debugging Rails behavior, or checking whether an API/option still exists or changed in a given Rails version. Always consult the official guides and API docs rather than answering from memory alone, since trained knowledge can be stale or wrong about version-specific details. --- # Rails official documentation lookup -This project (HostedGPT) runs Rails 8.0, per the project's `CLAUDE.md`. Trained knowledge about -Rails APIs can be outdated, mixed across versions, or simply wrong on specifics (option names, -defaults, deprecations, callback ordering, etc.). Before answering a Rails-specific question or -relying on a Rails API's exact behavior, check the official docs rather than guessing. +Trained knowledge about Rails APIs can be outdated, mixed across versions, or simply wrong on +specifics (option names, defaults, deprecations, callback ordering, etc.). Before answering a +Rails-specific question or relying on a Rails API's exact behavior, check the official docs +rather than guessing — pinned to the version this project actually runs, not whatever version +training data assumed. + +## Determine the version first + +Don't assume the Rails version from memory or from prose in `CLAUDE.md` — that can go stale the +moment someone bumps the gem without updating the docs. Check the source of truth instead: + +```bash +grep -m1 '^ rails (' Gemfile.lock +``` + +That gives you the exact installed version (e.g. `rails (8.0.2.1)`). Use its `.` +for the pinned doc URLs below. ## Sources - **Guides** (concepts, how-tos, conventions): https://guides.rubyonrails.org - - Version-pinned guides are available at `https://guides.rubyonrails.org/v8.0/.html` - if you need to confirm you're reading the Rails 8.0 version rather than edge/main. + - Version-pinned: `https://guides.rubyonrails.org/v./.html` - **API reference** (exact method signatures, options, source): https://api.rubyonrails.org - - Version-pinned API docs: `https://api.rubyonrails.org/v8.0/` + - Version-pinned: `https://api.rubyonrails.org/v./` + +If a pinned URL 404s (e.g. docs for a brand-new version aren't published at that path yet), fall +back to the unpinned root and flag to the user that you're reading possibly-newer docs than the +installed version. ## When to look things up Use `WebFetch` against the sources above when: - The question is about a specific Rails API's options, defaults, or behavior (e.g. "does `has_many` support `:strict_loading`?", "what does `config.active_record.encryption` need?"). -- You're unsure whether something changed between Rails versions (deprecated, renamed, new in 8.0). +- You're unsure whether something changed between Rails versions (deprecated, renamed, new + behavior in the installed version). - You're about to write code that depends on exact method signatures, callback ordering, or routing/DSL syntax you're not fully certain of. - The user asks a "how do I do X in Rails" question that isn't already answered by this project's @@ -35,11 +52,12 @@ very basic Ruby/Rails knowledge you're confident hasn't changed across versions. ## How to look things up -1. Identify the right guide or API page (e.g. Active Record Associations, Action Mailer Basics). -2. Fetch it with `WebFetch`, preferring the `/v8.0/` pinned URL when version accuracy matters. -3. If the guide doesn't have the exact method signature, cross-check `api.rubyonrails.org` for the +1. Determine the installed Rails version from `Gemfile.lock` (see above). +2. Identify the right guide or API page (e.g. Active Record Associations, Action Mailer Basics). +3. Fetch it with `WebFetch`, using the version-pinned URL. +4. If the guide doesn't have the exact method signature, cross-check `api.rubyonrails.org` for the precise method/class documentation. -4. Prefer the official source over Stack Overflow, blog posts, or other secondary sources when they +5. Prefer the official source over Stack Overflow, blog posts, or other secondary sources when they conflict. ## Applying this project's conventions diff --git a/.claude/skills/tailwind-docs/SKILL.md b/.claude/skills/tailwind-docs/SKILL.md index 358c1ab0..fdcdc38c 100644 --- a/.claude/skills/tailwind-docs/SKILL.md +++ b/.claude/skills/tailwind-docs/SKILL.md @@ -1,37 +1,53 @@ --- name: tailwind-docs -description: Use when asked about Tailwind CSS — utility classes, responsive/state variants, `tailwind.config.js` theme customization, `@apply`, dark mode, or "how do I style X with Tailwind". Always consult the official Tailwind docs rather than answering from memory alone, since utility class names and config syntax have changed between Tailwind v3 and v4, and this project pins Tailwind v3 (via `tailwindcss-rails` gem, config in `config/tailwind.config.js`). +description: Use when asked about Tailwind CSS — utility classes, responsive/state variants, config/theme customization, `@apply`, dark mode, or "how do I style X with Tailwind". Always consult the official Tailwind docs rather than answering from memory alone, since utility class names and config syntax changed substantially between Tailwind v3 and v4 — check which one this project is actually on before trusting either. --- # Tailwind CSS documentation lookup This project (HostedGPT) styles its Hotwire-rendered views with Tailwind CSS via the -`tailwindcss-rails` gem (`~> 2.7`, see `Gemfile`), which bundles **Tailwind CSS v3** — it still -uses a JS config file at `config/tailwind.config.js`, not Tailwind v4's CSS-first `@theme` -config. This matters because Tailwind v4 renamed/changed a number of utilities and the config -approach entirely, so answers pulled from memory can silently mix v3 and v4 syntax. +`tailwindcss-rails` gem. Tailwind v3 and v4 differ substantially — v3 uses a JS config file +(`tailwind.config.js`, `module.exports = { theme: {...} }`), v4 uses CSS-first config +(`@import "tailwindcss"` + `@theme` blocks in the stylesheet, often no JS config file at all) and +renamed/changed a number of utilities. Trained knowledge can silently mix the two, so confirm +which version this project is on before trusting either. + +## Determine the version first + +Check the repo structure rather than assuming: + +```bash +ls config/tailwind.config.js 2>/dev/null # present + module.exports = v3-style config +grep -rn '@theme' app/assets/stylesheets/ 2>/dev/null # present = v4-style CSS config +grep -m1 'tailwindcss-rails (' Gemfile.lock +``` + +A present `config/tailwind.config.js` using `module.exports` (no `@theme` blocks in the CSS) +means this project is on Tailwind v3. If that ever flips — `tailwind.config.js` disappears and +`@theme` shows up in the stylesheet instead — the project has moved to v4, and this skill's +default assumption below no longer holds. ## Sources - **Docs**: https://tailwindcss.com/docs - - The current site defaults to the latest major version's docs. If a page's syntax looks like - v4 (e.g. CSS `@import "tailwindcss"` / `@theme` blocks, no `tailwind.config.js`), that's a - mismatch with this project — look for the v3 equivalent or verify against the - `config/tailwind.config.js` file already in this repo, which follows v3 conventions. - - The docs site also has a version switcher; prefer the v3 docs when available/linked from a - page (URLs are sometimes of the form `https://v3.tailwindcss.com/docs/...`). + - The current site defaults to the latest major version's docs, which won't match a v3 project. + - If you determined this project is still on v3, prefer the v3-pinned docs at + `https://v3.tailwindcss.com/docs/...` instead of the default (v4-or-later) docs site. + - If a page's syntax looks like v4 (CSS `@import "tailwindcss"` / `@theme` blocks, no + `tailwind.config.js` in examples) but the project is on v3, that's a mismatch — look for the + v3-equivalent page instead. ## When to look things up Use `WebFetch` when: - You need the exact utility class name/values for something (spacing scale, color palette, arbitrary value syntax) rather than guessing. -- You're customizing `config/tailwind.config.js` (theme extension, plugins, safelist) and need - the v3 config shape. -- You're unsure whether a utility/variant exists in v3 (e.g. some newer utilities and variants - were only added in v4). +- You're customizing the theme/config and need the config shape for the version this project + actually uses (JS config for v3, CSS `@theme` for v4). +- You're unsure whether a utility/variant exists in the installed major version (some utilities + and variants only exist in v4, or were renamed from their v3 equivalents). Skip the lookup for basic, version-stable utilities you're confident about (e.g. `flex`, `items-center`, `p-4`), or when the existing codebase already shows the exact class/pattern to -follow — check `app/views/` and `config/tailwind.config.js` for this project's own conventions +follow — check `app/views/` and the project's Tailwind config for this project's own conventions first.