Instructions file
Instructions for sandeepmvl/rails-skills, covering rails-skills — project context for claude code, read these first, in order, what this repo is, the canonical skill.md format (don't deviate) and project principles (non-negotiable).
Skill Claude CodeCodex
Interview the developer about their Ruby on Rails project (app type, database, frontend stack, background jobs, deployment target, traffic profile, compliance, current Rails version) and then route to the right downstream rails-skills. Use at the start of any new Rails work session, when the user says they want to…
Skill Claude CodeCodex
Idiomatic ActiveRecord patterns for Ruby on Rails — associations (belongsto/hasmany/hasone/hasmany :through), countercache, polymorphic, STI vs delegatedtype, scopes vs class methods, callbacks vs aftercommit, find vs findby vs where.first, includes vs preload vs eagerload, pluck vs select, exists? vs any?, batch…
Skill Claude CodeCodex
Detect, diagnose, and eliminate N+1 queries in Ruby on Rails. Use when the user mentions slow Rails endpoints, slow queries, "N+1", Bullet, prosopite, includes/preload/eagerload, eager loading, query count is high, page is slow to render, or asks why a Rails controller is slow. Also use proactively when reviewing any…
Skill Claude CodeCodex
Decide when Rails logic stays in the model and when it earns a service object. Use when the user asks about service objects, fat models, "where does this logic go", refactoring a controller, extracting business logic, the Result pattern, interactor gem, dry-monads, command objects, or is about to write a class ending…
Skill Claude CodeCodex
RSpec testing for Ruby on Rails — pyramid shape (lots of model + request specs, fewer system specs), FactoryBot patterns, let vs let! vs before, shared examples, VCR for external HTTP, system specs with Capybara + Cuprite, transactional vs truncation strategy, parallel testing, SimpleCov coverage. Use when writing or…
Skill Claude CodeCodex
Write zero-downtime database migrations for Ruby on Rails — strongmigrations rules, the add-column / set-default / backfill / enforce-NOT-NULL multi-deploy split, disableddltransaction!, concurrent index creation on PostgreSQL, findeach batching, why changecolumn is dangerous, the deploy/migrate/deploy sequencing. Use…
Skill Claude CodeCodex
Design REST APIs in Ruby on Rails — URL versioning over Accept-header, jsonapi-serializer / alba / blueprinter, pagy pagination, JWT auth for stateless / session cookies for first-party SPAs, rack-attack rate limiting, structured error responses, OpenAPI/Swagger via rswag, CORS configuration. Use when building or…
Skill Claude CodeCodex
Background job design for Ruby on Rails — when to pick Solid Queue (Rails 8 default, no Redis) vs Sidekiq (existing investment, advanced features), idempotent job patterns, retry / backoff configuration, scheduled jobs via recurring.yml or sidekiq-cron, the decision matrix for "should this even be a background job at…
Skill Claude CodeCodex
Authentication and authorization for Ruby on Rails — Devise + Pundit as the default monolith combo, Rodauth when Devise hits its limits (MFA, WebAuthn, advanced password policies), devise-jwt for API-only apps, Rails 8's built-in bin/rails generate authentication for simple cases, secure defaults checklist…
Skill Claude CodeCodex
Production Docker and Kamal 2 deployment for Ruby on Rails 8 — multi-stage Dockerfile with build/runtime separation, ruby:3.x-slim over alpine (avoiding musl gotchas with nokogiri/pg/sassc), docker-compose for development with Postgres + Redis, Kamal 2 deploy.yml, zero-downtime via Kamal Proxy and the GET /up health…
Skill Claude CodeCodex
Security baseline for Ruby on Rails 8 apps — strong params (and their common bypass mistakes), CSRF for browser apps, CSRF for SPAs, Brakeman + bundler-audit + Dependabot, Rails credentials per environment, JWT best practices (short-lived + refresh rotation, never put secrets in payload), CORS without wildcards…
Skill Claude CodeCodex
Caching strategy for Ruby on Rails 8 — the cache layer hierarchy (HTTP/CDN → fragment cache → low-level cache → DB query cache), Solid Cache as the Rails 8 default, when Redis still wins (distributed pubsub + Sidekiq co-location), cache key design (versioned, content-addressed), Russian doll caching for nested views…
Skill Claude CodeCodex
Hotwire (Turbo + Stimulus) — the Rails 8 default UI stack. Turbo Drive for navigation, Turbo Frames for lazy HTML islands, Turbo Streams for server-pushed updates over WebSocket or response body, Stimulus controllers for the JS sprinkles layer, morph updates (idiomorph), Action Cable broadcasting from models and jobs.…
Skill Claude CodeCodex
File uploads in Ruby on Rails 8 with Active Storage — direct uploads to S3/GCS (skip the Rails server for the byte payload), variant configuration with imageprocessing + libvips, content-type and size validation, pre-signed URL safety (short TTLs, no public buckets by default), analyzer / previewer hooks, processing…
Skill Claude CodeCodex
ActionMailer baseline for Rails 8 — mailer setup, deliverlater by default (never delivernow in the request path), Mailer previews in dev, mailer specs with RSpec, Letter Opener for dev inspection, transactional delivery via Postmark / SendGrid / SES / Mailgun, bounce and complaint handling, idempotent transactional…
Skill Claude CodeCodex
Observability baseline for Rails 8 production apps — lograge for structured single-line logs, request tagging (requestid, userid), error tracking via Sentry / Honeybadger / Rollbar, Rails.error.report (Rails 7.1+) as the standard error-reporting API, PII scrubbing in logs and error reports, what to log vs not (no PII…
Skill Claude CodeCodex
Upgrade a Ruby on Rails app from Rails 7.x to Rails 8.0 — dual-boot via nextrails, the deprecation-fix loop, Solid Queue / Solid Cache / Solid Cable adoption choices, Propshaft over Sprockets, the new authentication generator vs existing Devise, Kamal 2 deployment cutover, gem compatibility matrix, the version hop…
Skill Claude CodeCodex
Upgrade a Ruby on Rails app from 6.x to 7.x — dual-boot via nextrails, the Zeitwerk autoloader transition (was already in 6.0 but became mandatory), Sprockets-to-importmap or jsbundling decision, Hotwire arriving, encrypted attributes via Active Record Encryption (7.0+), the version hop sequence. Use when the user is…
Skill Claude CodeCodex
Upgrade a Ruby on Rails app from 5.x to 6.x — dual-boot via nextrails, Zeitwerk autoloader transition from Classic, Webpacker becoming default, ActionMailbox + ActionText shipping, parallel testing, multi-database support, the version hop sequence. Use when upgrading from Rails 5 to 6, mentions Zeitwerk, autoload…
Skill Claude CodeCodex
Upgrade a Ruby on Rails app from 4.x to 5.x — dual-boot via nextrails, ApplicationRecord introduction, ActionCable arrival, strong parameters becoming mandatory, params no longer hash-like, the version hop sequence, the Rails 5.1 system tests and yarn arrival, the Rails 5.2 ActiveStorage + credentials. Use when…
Skill Claude CodeCodex
Upgrade a Ruby on Rails app from 3.x to 4.x — strong parameters replacing attraccessible / attrprotected, the asset pipeline overhaul, the Turbolinks arrival, Ruby 2.0+ requirement, Bundler-style routes file, the version hop sequence. Use when upgrading legacy Rails 3 apps, the user mentions attraccessible…
Skill Claude CodeCodex
Migrate a Ruby on Rails application's primary database from PostgreSQL to MySQL — schema differences (JSONB to JSON, ARRAY columns, partial indexes, CHECK constraints, sequences), data export/import via pgdump and mysqlimport or pgloader, the dual-write cutover pattern, the gem switch (pg to mysql2 or trilogy)…
Skill Claude CodeCodex
Migrate a Ruby on Rails application's primary database from MySQL to PostgreSQL — schema upgrades (JSON to JSONB for queryability, ENUMs to native types or check constraints, TINYINT to BOOLEAN, case-sensitivity changes), data export/import via pgloader, the dual-write cutover pattern, the gem switch (mysql2/trilogy…