rails-skills

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 "start a new Rails app", "set up a Rails project", "scaffold Rails", "build a Rails API", "build a Rails monolith", "build a Rails 8 app", or anytime they reference rails-skills without specifying which skill they want. Also use when reviewing or auditing an existing Rails codebase to determine which skills apply. This is the entry point of the rails-skills pack — almost every Rails task should start here.

Generate project-specific Claude Skills for THIS Rails app — interview the codebase (domain models, workflows, multi-tenancy, auth, test + verification loop, branch rules, deploy) and emit starter SKILL.md files under the user's own .claude/skills/ that encode their product's conventions. Use when the user says "create skills for my app", "make project-specific skills", "scaffold local skills", "the generic rails-skills don't know my domain", "teach the agent my codebase conventions", "generate a skill for my <feature>", or wants the agent to learn their app's tenant rules / domain workflows / test gates rather than generic Rails advice.

Idiomatic ActiveRecord patterns for Ruby on Rails — associations (belongs_to/has_many/has_one/has_many :through), counter_cache, polymorphic, STI vs delegated_type, scopes vs class methods, callbacks vs after_commit, find vs find_by vs where.first, includes vs preload vs eager_load, pluck vs select, exists? vs any?, batch processing with find_each, and fat-models-with-concerns. Use whenever the user writes or reviews ActiveRecord models, asks why a Rails query is slow or wrong, mentions includes/preload/eager_load, says "callback", references scopes, or is generating model code. Also use proactively when reading any Rails model file (app/models/*.rb).

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/eager_load, 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 controller action that iterates a collection and accesses associations, or any view that loops and calls `.author`, `.comments.count`, etc. Bundles a Bullet config script and an EXPLAIN ANALYZE reference for Rails devs.

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 in Service / Manager / Handler / Processor. Also use proactively when reviewing any controller action with more than ~10 lines of business logic, or any model file exceeding ~200 lines.

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 reviewing Rails tests, the user mentions RSpec, FactoryBot, Capybara, Cuprite, VCR, system specs, request specs, model specs, fixtures, factories, flaky tests, slow test suite, parallel_rspec, or asks for help with rails_helper / spec_helper. Bundles drop-in spec_helper.rb + rails_helper.rb + .rspec templates.

Write zero-downtime database migrations for Ruby on Rails — strong_migrations rules, the add-column / set-default / backfill / enforce-NOT-NULL multi-deploy split, disable_ddl_transaction!, concurrent index creation on PostgreSQL, find_each batching, why change_column is dangerous, the deploy/migrate/deploy sequencing. Use when writing or reviewing Rails migrations, adding a column to a large table, removing or renaming columns, adding NOT NULL or foreign keys, adding indexes on big tables, when the user mentions strong_migrations, zero downtime, migration locks, deploy ordering, or asks how to backfill a column safely.

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 reviewing a Rails::API app, adding JSON endpoints to a monolith, the user mentions API versioning, serializers, JSON serialization, JWT, rack-attack, rate limits, pagination, OpenAPI, Swagger, rswag, REST API design, CORS, or asks how to structure /api/v1 routes.

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 all", concurrency controls, dead-set handling, monitoring. Use when writing or reviewing ActiveJob, Sidekiq, Solid Queue jobs, the user mentions perform_later, perform_async, retry, deliver_later, recurring jobs, dead jobs, queue_adapter, or asks whether work should be sync or async.

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 (confirmable, lockable, password complexity), Pundit policy structure, the scope pattern for index actions, common authorization smells. Use when adding sign-in / sign-up, the user mentions Devise, Pundit, Rodauth, JWT auth, authorization, policies, can-can, CanCanCan, role-based access, MFA, WebAuthn, or asks "how do I auth in Rails".

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 check, secrets via Kamal envs + Rails credentials, log shipping. Use when writing or reviewing a Dockerfile for Rails, setting up Kamal, debugging deploy failures, the user mentions Dockerfile, docker-compose, Kamal, Kamal Proxy, Thruster, multi-stage builds, alpine vs slim, native gem compilation, kamal deploy, zero-downtime, or asks how to ship a Rails 8 app to production.

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, Rack::Attack for rate limiting and brute-force, OWASP Top 10 mapped to Rails. Use when reviewing or writing any controller, when the user mentions security, CSRF, params, mass assignment, secrets, credentials, JWT, CORS, Brakeman, bundler-audit, OWASP, secure headers, content security policy, or asks "is this safe to ship". Use proactively before any commit that touches auth, params, or external input.

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, Rails.cache.fetch patterns, cache stampede prevention via race_condition_ttl, HTTP caching with stale? / fresh_when, when caching is the wrong answer (fix the query first). Use when the user mentions caching, Rails.cache, Solid Cache, Redis, Memcached, fragment cache, low-level cache, cache_key, cache_version, race_condition_ttl, ETag, Last-Modified, stale?, fresh_when, or asks how to speed up a slow endpoint and the fix isn't a query change.

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. Use when building or reviewing Rails 8 UI, the user mentions Turbo, Stimulus, Hotwire, turbo_frame_tag, turbo_stream, broadcasts_to, turbo-frame, data-controller, morphdom, idiomorph, or asks how to add reactivity without React/Vue. Use proactively whenever the AI is about to suggest a React component for something Hotwire can do.

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 image_processing + libvips, content-type and size validation, pre-signed URL safety (short TTLs, no public buckets by default), analyzer / previewer hooks, processing variants in background jobs (not the request thread), the service config for dev/test/prod. Use when the user mentions Active Storage, file uploads, attach, has_one_attached, has_many_attached, direct uploads, image variants, S3, GCS, image_processing, libvips, signed URLs, or asks how to handle avatars / attachments / photo uploads in Rails.

ActionMailer baseline for Rails 8 — mailer setup, deliver_later by default (never deliver_now 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 sends, attachments and inline images, i18n for subject lines and bodies. Use when the user mentions ActionMailer, mailers, deliver_later, deliver_now, mailer previews, transactional email, Postmark, SendGrid, SES, Mailgun, bounces, mailer specs, Letter Opener, or asks how to send email from Rails.

Observability baseline for Rails 8 production apps — lograge for structured single-line logs, request tagging (request_id, user_id), 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, no card data, no JWT contents), structured fields over message concatenation. Deeper observability (APM tracing, distributed tracing, custom metrics) lives in observability-rails-advanced (v0.3). Use when the user mentions logging, lograge, structured logs, Sentry, Honeybadger, Rollbar, error tracking, Rails.error.report, PII, request_id, log tagging, log levels, what to log, or asks "how do I know if my Rails app is healthy in production".

Upgrade a Ruby on Rails app from Rails 7.x to Rails 8.0 — dual-boot via next_rails, 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 sequence. Use when the user is upgrading Rails to 8, asks about Rails 8 migration, mentions next_rails, dual booting, Gemfile.next, Solid Queue migration, Sprockets to Propshaft, or asks "what changes in Rails 8".

Upgrade a Ruby on Rails app from 6.x to 7.x — dual-boot via next_rails, 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 upgrading from Rails 6 to 7, mentions Zeitwerk, Webpacker removal, importmap-rails, Hotwire migration, encrypted attributes, or asks how to get off Rails 6.

Upgrade a Ruby on Rails app from 5.x to 6.x — dual-boot via next_rails, 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 paths, Classic to Zeitwerk migration, Webpacker, or asks how to leave Rails 5.

Upgrade a Ruby on Rails app from 4.x to 5.x — dual-boot via next_rails, 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 upgrading from Rails 4 to 5, the user mentions ApplicationRecord, strong parameters, params.permit, ActionCable, the params HashWithIndifferentAccess change, or asks how to leave Rails 4.

Upgrade a Ruby on Rails app from 3.x to 4.x — strong parameters replacing attr_accessible / attr_protected, 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 attr_accessible, Turbolinks, protected_attributes gem, asset pipeline, or asks how to escape Rails 3.

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 pg_dump and mysqlimport or pgloader, the dual-write cutover pattern, the gem switch (pg to mysql2 or trilogy), Rails-side caveats. Use when migrating a Rails app from Postgres to MySQL, the user mentions pgloader, mysql2, trilogy, schema conversion, JSONB to JSON, ARRAY columns, partial indexes, or asks how to move a Rails app off Postgres.

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 to pg), Rails-side caveats. Use when migrating from MySQL to Postgres, the user mentions pgloader, JSONB upgrade, ENUM migration, TINYINT to BOOLEAN, or asks how to move a Rails app to Postgres.

Migrate a Ruby on Rails application from Oracle Database to PostgreSQL — schema differences (NUMBER to BIGINT/DECIMAL, VARCHAR2 to VARCHAR, CLOB/BLOB to TEXT/BYTEA, sequences, ROWID, hierarchical queries, PL/SQL packages), Oracle Enhanced adapter to pg gem, data migration via ora2pg, the dual-write cutover. Use when leaving Oracle for Postgres, the user mentions ora2pg, Oracle Enhanced adapter, NUMBER columns, VARCHAR2, sequences, ROWNUM, CONNECT BY, or asks how to escape Oracle.

Integrate React with a Ruby on Rails app — Inertia.js as the default (server-rendered routing, no separate API), classical API + SPA when Inertia doesn't fit, jsbundling-rails with esbuild, vite_ruby as a faster alternative, hydration vs full SPA, when React earns the integration cost. Use when integrating React into Rails, the user mentions Inertia, React Router, SPA, jsbundling-rails, vite_ruby, hydration, server-side rendering, or asks "should I use React with Rails".

Integrate Vue with a Ruby on Rails app — Inertia.js as the default (server-rendered routing), classical API + SPA when Inertia doesn't fit, vite_ruby with @vitejs/plugin-vue, Vue 3 Composition API, hydration patterns, when Vue earns the integration cost. Use when integrating Vue into Rails, the user mentions Inertia Vue adapter, Vue Router, Pinia, vite_ruby + Vue, or asks "should I use Vue with Rails".

Integrate Angular with a Ruby on Rails app — classical API + SPA as the default (Angular's full-framework model doesn't fit Inertia well), standalone-components Angular 17+, NgRx vs signals, JWT auth flow, CORS configuration, deploying Angular separately from Rails. Use when integrating Angular into Rails, the user mentions Angular CLI, NgRx, standalone components, Angular signals, or asks "how do I use Angular with Rails".

Tune Puma for production Rails 8 — worker process count (CPUs × 1.5), thread count per worker (3-5 default), memory budget per worker, jemalloc, preload_app + fork-safe initializers, the Ruby 3+ YJIT enable, GIL implications for thread count, signal handling, restart strategies, MALLOC_ARENA_MAX. Use when the user mentions Puma config, workers, threads, jemalloc, memory bloat, copy-on-write, WEB_CONCURRENCY, RAILS_MAX_THREADS, MALLOC_ARENA_MAX, or asks how many workers / threads to run.

Asset pipeline for Rails 8 — Propshaft as the new default (replacing Sprockets), Importmap-rails for JS without bundling, jsbundling-rails for esbuild/rollup/webpack, cssbundling-rails for Tailwind/Sass/PostCSS, the Sprockets-to-Propshaft migration, asset host for CDN, digest stamping, far-future expiry headers. Use when the user mentions Propshaft, Sprockets migration, importmap, jsbundling, cssbundling, asset_host, asset pipeline, .css.erb, manifest.js, or asks about Rails 8 assets.

Multi-database Rails 8 — primary + replica for read scaling, separate databases per concern (auth DB, analytics DB), automatic role switching via connected_to + connects_to, replica lag detection, sticky writes (writes-followed-by-reads on primary), GHA-style horizontal sharding, the trilogy/pg per-connection-pool config. Use when the user mentions read replicas, replica lag, primary/replica, connected_to, connects_to, sharding, multi-database, role-switching, or asks how to scale reads.

Receive webhooks in Ruby on Rails 8 — signature verification, idempotency via event-ID storage, async processing in jobs (never sync), retry semantics, the raw-body capture for HMAC, replay protection. Use when the user mentions webhooks, webhook signature, HMAC verification, replay protection, idempotency keys, webhook retries, or asks how to receive Stripe / GitHub / Slack / Twilio / Shopify webhooks.

Stripe webhook integration in Rails 8 — Stripe::Webhook.construct_event for signature + timestamp verification, idempotency via event.id, the canonical event types to handle (payment_intent.succeeded / payment_intent.payment_failed / charge.refunded / customer.subscription.*), test-mode vs live-mode secrets, webhook endpoint testing via Stripe CLI, async processing in jobs. Use when the user mentions Stripe webhooks, payment_intent events, subscription events, Stripe::Webhook, webhook_secret, Stripe CLI, or builds payment infrastructure.

Integrate Ruby on Rails apps with external HTTP APIs — Faraday as the canonical client, retries with exponential backoff, circuit breaker (Stoplight), VCR for tests, timeout discipline (open + read), structured logging of API calls, idempotency keys on writes, rate limit handling, the wrap-in-a-service-object pattern. Use when the user mentions Faraday, HTTP client, API integration, retries, circuit breaker, Stoplight, VCR cassettes, HTTPX, Net::HTTP, or asks how to call a third-party API safely.

Feature flags in Ruby on Rails 8 — Flipper as the canonical gem, percentage-rollout and group-based flags, the per-request and per-user evaluation patterns, integration with admin UI and CI, deprecating flags safely, the "every feature behind a flag" anti-pattern. Use when the user mentions Flipper, feature flags, percentage rollout, A/B testing infrastructure, dark launch, gradual rollout, kill switch, or asks how to ship features safely.

Architectural patterns beyond fat models — form objects for multi-model form binding, query objects for complex AR querying, presenters / decorators for view logic. When each earns its keep, naming, testing, common smells. Use when models bloat, forms span multiple models, queries get hard to read, views accumulate helpers, or the user mentions Reform, ActiveModel::Model, decorators, Draper, presenters, query objects.

Action Text (rich text) in Rails 8 — Trix editor integration, has_rich_text on models, Active Storage for embedded attachments, the safe-list of HTML tags, custom embeds via attachable mixin, server-side sanitization, XSS prevention, search indexing of plain text. Use when the user mentions Action Text, Trix, rich text editor, has_rich_text, WYSIWYG, formatted text content, embedded images, or asks how to add a rich text editor to Rails.

Internationalization and time zones in Rails 8 — I18n keys for translations, locale fallbacks, lazy lookup in views, locale switching per-request, the rails-i18n gem, time zone storage strategy (UTC in DB, display in user's zone), Time.zone vs Time.current vs Time.now, time_in_zone, daylight saving traps. Use when the user mentions I18n, locales, translations, t() helper, Time.zone, Time.current, time zone, DST, multi-language, or asks how to localize a Rails app.

Search in Rails 8 — pg_search as the default (Postgres full-text + tsvector + trigram), Meilisearch when relevance / typo tolerance / autocomplete matter, Elasticsearch / OpenSearch only when you actually need cluster-scale, Searchkick as a friendly wrapper. Multi-search across models. Indexing strategies (sync, async, on-demand). Ranking. Highlighting. Use when the user mentions search, full-text, pg_search, Meilisearch, Elasticsearch, OpenSearch, Searchkick, typo tolerance, autocomplete, indexing, tsvector, trigram, "find users by name", or asks how to add search to a Rails app.

Multi-tenant architecture in Rails 8 — scoped-row vs schema-per-tenant vs database-per-tenant trade-offs, the acts_as_tenant gem, subdomain / path / header-based tenant resolution, query scoping that survives raw SQL, background job tenancy, file storage isolation, signup flows, plan-based feature gating. Use when the user mentions multi-tenant, SaaS, account, organization, workspace, acts_as_tenant, apartment, subdomain, tenant isolation, tenant_id, "each customer gets their own data", or asks how to build a B2B SaaS in Rails.