GitHub - sandeepmvl/rails-skills

Production-grade Claude Skills for Ruby on Rails. Stop fighting your AI coding agent on Rails conventions — drop in rails-skills and Claude Code, Cursor, Codex, Gemini CLI, Antigravity, and Windsurf will write Rails code the way senior Rails developers actually write it.

The problem

You ask Claude Code or Cursor to "add a draft status with scheduled publishing to Post." It generates a migration, a callback, a controller update. It looks fine. Then you notice:

• It added a before_save callback instead of using your existing PublishPostJob
• It used a string column for status instead of the enum already on the model
• It didn't add the partial index PostgreSQL needs for the new status
• The test it wrote doesn't use your existing Post factory
• It hardcoded the timezone

Every Rails dev using an AI agent has had this morning. The agent isn't dumb — it just doesn't know your Rails conventions. rails-skills teaches it.

What this is

A pack of independent Claude Skills (open standard, released by Anthropic in December 2025) covering the patterns, performance traps, security baselines, and deployment conventions that senior Rails developers care about. Each skill is portable across:

• Claude Code
• Claude.ai
• the Claude API
• OpenAI Codex
• Cursor
• Gemini CLI
• Antigravity
• Windsurf

Quick install

Work across many projects? Install once, globally instead of per-repo. The Rails skills are description-gated — they stay dormant on non-Rails projects (React, Go, Python…) and wake up only for Rails work. See Two install modes.

Claude Code

Per-project:

cd <your-rails-app>
git clone https://github.com/sandeepmvl/rails-skills .claude/skills

Global — all projects (recommended for multi-project devs):

git clone https://github.com/sandeepmvl/rails-skills ~/.claude/skills/rails-skills

Then start Claude Code. The orchestrator skill (rails-project-discovery) interviews you and routes to the right downstream skills automatically — and only triggers when you're actually working on Rails.

Cursor

cd <your-rails-app>
git clone https://github.com/sandeepmvl/rails-skills .cursor/skills

Other tools

See docs/install.md for OpenAI Codex, Gemini CLI, Antigravity, and Windsurf instructions.

The skills

v0.1 — Foundation (16 skills)

v0.2 — Expansion (24 skills)

v0.3 — Specialization (18 skills)

Tooling & project-fit (2 skills)

See PLAN.md for the full roadmap and rationale.

Before / after

Same prompt — "list the 20 most recent posts with their authors" — to the same agent. Without the pack, then with it.

Without rails-skills (AI-typical — a hidden N+1 that only bites in production):

# app/controllers/posts_controller.rb
def index
  @posts = Post.order(created_at: :desc).limit(20)
end

<% @posts.each do |post| %>
  <%= post.title %> — <%= post.author.name %>   <%# 1 + 20 queries %>
<% end %>

With rails-skills (the n-plus-one-killer + activerecord-patterns skills trigger):

# app/controllers/posts_controller.rb
def index
  # includes(:author) → 2 queries total, regardless of row count.
  @posts = Post.includes(:author).order(created_at: :desc).limit(20)
end

The agent also adds a Bullet config to catch the next N+1 in development before it ships, and explains why includes beats a manual join here. That's the difference: not just correct code, but conventional code with the reasoning a senior Rails dev would give.

A 30-second screencast of this exact flow lands here before the public launch. Until then, the worked example above is the demo.

What this is NOT

• Not magic. A rails-upgrade-4-to-8 skill will guide and accelerate the upgrade. It will not do it autonomously. Rails upgrades require human judgment on gem replacements and test fixes.
• Not a replacement for the Rails Guides. These skills target the gaps where AI agents go wrong, not the basics.
• Not a gem. Nothing here gets required into your Rails app. Skills are markdown files consumed by AI coding agents.

Using this alongside your project-specific skills

rails-skills is a baseline, not a replacement for skills that know your product.

If your app already has local skills encoding its own rules — tenant isolation, domain workflows, payment/booking logic, your test + verification gates, branch discipline — those should stay the source of truth. A general Rails pack can't know what matters for your launch, and you don't want a broad skill layer competing with sharper local instructions.

The recommended pattern:

• Greenfield / no local skills yet → install the whole pack; it's a strong default.
• Mature app with its own skills → keep your local skills authoritative. Cherry-pick from this pack only where you have a genuine gap (migration safety, security-review checklists, Hotwire conventions, bug→regression discipline are common ones to lift).
• Conflicts? Your project conventions win. If you're on Minitest + system/E2E verification rather than RSpec + strict test-first, follow your own loop — the patterns here transfer, the ceremony is optional.

Think of it as a senior Rails dev's default instincts, not a process you must adopt wholesale.

Philosophy

These skills lean DHH: Majestic Monolith, fat models, Hotwire by default, Solid Queue/Cache/Cable on Rails 8. Where the Rails community legitimately disagrees, we state our position with rationale and acknowledge the alternative. We don't both-sides every decision.

Contributing

We need skills for everything in PLAN.md under v0.2 and v0.3. Pick one, copy skills/_TEMPLATE/, follow the conventions in CLAUDE.md, and open a PR.

Skills under v0.1 are the maintainer's responsibility — they set the quality bar. PRs welcome on v0.2+.

License

MIT — use it anywhere. If it saves your team time, a star is the only thanks needed.