Rails AI Skills

These skills teach an AI assistant Rails good practices, not one project's specific stack. Rails already has strong, well-known conventions — most models already know them. What models don't know is your project's gem choices (Devise vs. a custom JWT layer, CanCanCan vs. Pundit, AMS vs. Jbuilder, Sidekiq vs. Solid Queue). Baking one project's specific choices into a "generic Rails" skill is what causes an assistant to hallucinate gems into a project that doesn't use them and degrade code quality — so this repo keeps the two apart.

Two Kinds of Skill

ruby_on_rails/
└── skills/
    ├── controller-conventions/    ─┐
    ├── service-concern-helper/     │
    ├── model-conventions/          │  core — gem-agnostic, use in every Rails project
    ├── query-efficiency/           │
    ├── security/                   │
    ├── views-assets/               │
    ├── routing/                    │
    ├── error-handling/             │
    ├── migrations/                 │
    ├── testing-conventions/        │
    ├── scaffold-resource/         ─┘  (orchestrator — routes to the others)
    └── gems/
        ├── devise/       ─┐
        ├── cancancan/      │  opt-in — only load the ones matching the project's actual Gemfile
        └── sidekiq/       ─┘

Core skills cover the parts of a Rails app that are true almost everywhere: keep controllers thin, decide where logic belongs (service vs. concern vs. helper), keep models focused on data, avoid N+1s, write safe migrations, handle errors consistently. They deliberately avoid naming a specific auth gem, serialization library, or job processor — where a choice matters, they say "check what the project already uses" instead of prescribing one.

Gem skills (under skills/gems/) are opt-in. Each one only applies if that gem is actually in the project's Gemfile. Load only the ones that match — don't pull in gems/devise for a project using has_secure_password, and don't pull in gems/sidekiq for a project on Solid Queue.

Using These Skills in a Project

1. Copy skills/ (or the subset you need) into the target project's .claude/skills/ (or wherever your tool loads skills from).
2. Delete or skip any gems/* skill that doesn't match the project's actual dependencies.
3. Edit anything that doesn't match the project's real conventions — these are a starting point, not a contract. If the project's error-response shape, primary-key strategy, or test framework differs from a skill's examples, update the skill to match rather than fighting it in every conversation.
4. If the project uses a gem not covered here yet (Pundit, AASM, JWT libraries, Jbuilder, Blueprinter, pg_search, ransack, etc.), write a new skills/gems/<name>/SKILL.md following the shape of the existing ones — see Contributing below.

Skill Index

Skill	Covers
controller-conventions	Thin controllers, before_action/around_action, strong params, no serialization logic inline
service-concern-helper	Deciding between a service object, a concern, or a helper
model-conventions	Associations, attribute accessors, validations, scopes, modularity via concerns
query-efficiency	N+1 prevention, joins vs. subqueries, batching, where complex queries should live
security	SQL injection, mass assignment, CORS, error leakage, auth/session hygiene
views-assets	Views/partials, helpers vs. presenters, JS/CSS/asset pipeline organization
routing	RESTful resources, member/collection routes, nesting, namespacing
error-handling	One consistent error shape, rescue_from centralization, status-code mapping
migrations	Reversibility, explicit indexes/defaults, safe migrations on large tables
testing-conventions	Test pyramid, factories/fixtures, request-spec coverage for auth boundaries
scaffold-resource	Orchestrates the above (+ gem skills) when building a full new resource
gems/devise	Devise modules, controller/view customization, token-based API auth on top of Devise
gems/cancancan	Ability class structure, load_and_authorize_resource vs. authorize!, accessible_by
gems/sidekiq	Job class conventions, queueing, retry strategy, idempotency

Contributing a New Gem Skill

PRs adding a skills/gems/<gem-name>/SKILL.md for another commonly-used gem (Pundit, AASM, Jbuilder, Blueprinter, pg_search, ransack, paper_trail, etc.) are welcome. To keep new skills useful and not just a copy of the gem's own README:

• Start from a real project's usage of the gem, not just the gem's docs — capture the decisions a team actually made (which modules/options to enable, where the config lives, how it's tested), not a restatement of the API.
• State plainly at the top that the skill only applies if the project has this gem in its Gemfile.
• Cross-reference the relevant core skill instead of repeating it (e.g. an authorization gem skill should point to security for the general "every action needs a check" rule, not restate it).
• Include a short checklist at the end, matching the style of the existing skills.
• Keep it scoped to the gem's actual surface area — don't reach into unrelated concerns (a background-job gem skill shouldn't also cover authorization).