rails-skills

Build the full-stack frontend of a Rails 8.1 app with Hotwire — Turbo Drive/Frames/Streams (including Turbo 8 morphing page refreshes), Stimulus controllers, the view layer (ERB partials, ViewComponent, or Phlex), forms, assets, and rich-text editing with Action Text (the bundled Trix editor) — plus real-time features via Action Cable and Turbo Stream broadcasting over Solid Cable or Redis. Menu-driven: presents the view-layer and Cable-adapter options as vetted menus with a Recommended default, detects the app's already-chosen CSS/JS stack (owned by rails-scaffold) and existing Hotwire wiring first, and verifies pages render and live updates broadcast. Apply when building interactive UI, wiring Turbo Frames/Streams, writing Stimulus controllers, choosing a view-component approach, adding a rich-text editor, adding live/broadcast updates, or making views accessible (WCAG/Section 508). Web apps only — not API-only.

Add background jobs to a Rails 8.1 app via Active Job — choose the backend (Solid Queue, the Rails 8 default, or Sidekiq / GoodJob), write jobs with retries/discards/idempotency, enqueue with perform_later, and schedule recurring tasks (Solid Queue recurring, sidekiq-cron, or whenever). Menu-driven with a Recommended default per menu; detects the installed backend (Solid Queue is preconfigured in Rails 8, or skipped via --skip-solid), applies equally to API-only and full-stack apps, and verifies a job actually enqueues and runs. Apply when moving work off the request thread, configuring a queue backend, adding retries/error handling to a job, or scheduling recurring/cron work.

Design and evolve the ActiveRecord domain layer of a Rails 8.1 app — models, associations, validations, scopes, enums, callbacks, concerns, and type modeling (plain / STI / delegated types / polymorphic) — plus the persistence layer beneath them: migrations, indexing, constraints, schema format, multiple databases, full-text search, and seeds. Menu-driven: presents type-modeling, schema-format, and search options as vetted menus with a Recommended default, detects the app's adapter and existing models first, and verifies every change against a booted schema. Apply when adding or changing a model, writing a migration, indexing a table, modeling inheritance/variants, wiring search, splitting databases, or seeding data.

Stand up a new Ruby on Rails 8.1 app (API-only, full-stack Hotwire, or API+frontend) through a guided, menu-driven interview. The agent asks about app type, database, asset pipeline, CSS/JS, test framework, auth, and the Rails 8 omakase backends (Solid Queue/Cache/Cable, Kamal, Thruster) — each as a vetted menu with a Recommended default — assembles the right `rails new` flags, runs the generator, verifies the app boots, then routes to sibling rails-* skills to wire each concern. Also detects an existing app and routes without re-scaffolding. Apply when creating a new Rails project, choosing `rails new` flags, or deciding how to bootstrap a Rails codebase.

Make a Rails 8.1 app discoverable and correctly indexed by search engines and link unfurlers — per-page title/description/canonical meta tags, Open Graph + Twitter/X cards, JSON-LD structured data (Schema.org), XML sitemaps, robots.txt, and human/SEO-friendly URLs (slugs). Menu-driven for the genuine choices (meta-tag approach, sitemap approach, slug strategy) with a Rails-idiomatic Recommended default; detects what's already installed first, branches on config.api_only (a JSON API has no HTML to index — the rendering frontend owns its SEO), and verifies every tag/sitemap/slug actually renders and is crawlable. Apply when adding meta tags, social-share previews, structured data, a sitemap or robots.txt, or pretty URLs. Page-speed/Core Web Vitals is rails-performance; routing mechanics is rails-controllers; the view layer is rails-hotwire.

Build the JSON API surface of a Rails 8.1 app — response serialization (Jbuilder, Alba, jsonapi-serializer, Blueprinter), API versioning, pagination (Pagy/Kaminari), consistent error envelopes, CORS, OpenAPI/Swagger docs, and the token-auth surface — for API-only apps and the JSON endpoints of full-stack apps. Covers both the REST path and GraphQL (graphql-ruby) as the alternative API style. Menu-driven: presents the API style (REST vs GraphQL) plus serializer, versioning, pagination, and docs options as vetted menus with a Recommended default, detects api_only and any installed serializer/pagination/graphql gem first, and verifies endpoints return well-shaped responses with correct status codes. Apply when shaping JSON responses, versioning an API, paginating a collection endpoint, standardizing error responses, enabling CORS, documenting an API, or building a GraphQL schema.

Build the request layer of a Rails 8.1 app — routing, RESTful resources, controllers, actions, strong parameters (Rails 8 params.expect and the require/permit fallback), filters/before_actions, controller concerns, rescue_from error handling, the session/flash/cookies surface, and per-request locale selection / i18n — for both API-only and full-stack apps. Branches on config.api_only (API skips flash/views, Web uses them), detects existing routes/controllers before generating, presents the params and routing idioms as menus with a Recommended default, and verifies routes resolve and actions respond. Apply when adding routes or controllers, shaping strong params, sharing controller behavior, handling request errors, wiring sessions/flash, or setting up internationalization/locale switching.

Send transactional email from a Rails 8.1 app with Action Mailer — mailer classes, multipart HTML+text templates, layouts, attachments, inline images, previews, and delivery via SMTP (the Rails default, pointed at any provider) or Postmark / SendGrid / SES — and receive inbound email with Action Mailbox (ingress config, mailbox routing, processing). Menu-driven delivery selection with a Recommended default; detects any configured delivery method and credentials first, sends asynchronously through Active Job (deliver_later), and verifies mail renders and delivers in development. Apply when adding a mailer, building email templates, configuring email delivery, attaching files to email, previewing/testing mail, or routing/processing incoming email.

Add authentication AND authorization to a Rails 8.1 app, unified in one skill. Authentication menu — Rails 8 built-in generator with has_secure_password (Recommended), Devise, Rodauth (rodauth-rails), or authentication-zero — plus social login via OmniAuth and API token strategies. Authorization menu — Pundit (Recommended), Action Policy, or CanCanCan. Menu-driven with a Recommended default per menu; detects any installed auth/authz gem and config.api_only first (token surface for APIs, session/cookie flow for Web), gives per-solution integration guidance (install → wire → routes/controllers → views or token surface → tests), and verifies a real login/authorize round-trip. Apply when adding login/logout, password reset, sign-up, social login, API tokens, or role/permission checks.

Ship a Rails 8.1 app to production and observe it in production — orchestration (Kamal 2, the Rails 8 default, or Docker Compose / a PaaS), the production Docker image with Thruster, asset precompile, CI/CD (GitHub Actions, which ships with Rails 8), the /up health check and zero-downtime cutover, secret injection, and database migration on deploy — PLUS observability (structured logs, error tracking via Sentry/Honeybadger/AppSignal, metrics, APM, uptime), which lives in references/ and stays distinctly invocable. Menu-driven for orchestration, CI, and error tracking with a Recommended default; detects the generated Dockerfile/deploy.yml/CI workflow first, and verifies a real deploy passes its health check. Apply when deploying, containerizing, setting up CI/CD, configuring zero-downtime/health checks, injecting secrets, or wiring logs/errors/metrics/APM.

Make a Rails 8.1 app fast — choose a cache store (Solid Cache, the Rails 8 default, or Redis / Memcached), detect and fix N+1 queries (Bullet in dev or built-in strict_loading), apply fragment / Russian-doll / collection / low-level / HTTP caching, and optimize queries with indexes, select/pluck, counter caches, and read replicas. Menu-driven for the genuine choices (cache store, N+1 detection) with a Recommended default; detects the configured cache store first, and verifies improvements by measuring (query counts, cache hits, timings) rather than guessing. Apply when an endpoint is slow, fixing N+1 queries, adding caching, tuning database queries, or setting up performance measurement.

Proactively harden a Rails 8.1 app at build time — rate limiting (Rails 8 built-in rate_limit or rack-attack), secrets/credentials management (encrypted credentials, ENV, external managers), Content Security Policy and security headers, CSRF protection, strong-parameters/mass-assignment as a security control, and dependency/static scanning (Brakeman, bundler-audit, importmap audit). Menu-driven for the genuine choices (rate limiting, secrets) with a Recommended default; detects what's already configured first, branches on config.api_only (CSRF/CSP differ for token APIs), and verifies each control actually blocks what it should. This is BUILD-secure; for a retrospective FIND-insecure audit, use the upstream rails-audit skill (its security checklist is the rubric this skill builds toward). Apply when adding rate limiting, handling secrets, setting CSP/headers, hardening forms/params, or wiring vulnerability scanning.

Handle file uploads and attachments in a Rails 8.1 app with Active Storage — attach files to models (has_one_attached / has_many_attached), generate image variants (via image_processing with libvips or MiniMagick), serve files, and upload directly from the browser to a storage service. Menu-driven service and image-processor selection with a Recommended default; detects the configured storage service and processor first, branches on config.api_only (direct-upload JS is a Web concern), and verifies an attachment round-trips and a variant generates. Apply when adding file/image uploads, configuring a storage backend (local/S3/GCS/Azure), creating image variants, or wiring direct uploads.

Set up and write the test suite for a Rails 8.1 app — choose the framework (Minitest, the Rails default, or RSpec), the test-data strategy (fixtures or FactoryBot), the system-test driver (Selenium/Chrome by default, or a CDP driver like Cuprite), and coverage (SimpleCov) — then write model, request/controller, and system tests across the pyramid. Menu-driven with a Recommended default per menu; detects the framework already chosen at scaffold time (honors the -T flag and any installed rspec-rails) and config.api_only (API skips system/browser tests), and verifies the suite actually runs green. Apply when adding tests, setting up the test stack, writing factories/fixtures, testing an endpoint or a UI flow, or wiring coverage/CI.

Upgrade an existing (brownfield) Rails app's framework version toward the latest Ruby 4.0.x / Rails 8.1.x. Detects the current Ruby/Rails, plans an incremental one-minor-version-at-a-time path, and drives the per-step loop — bump the Gemfile, bundle update, run bin/rails app:update, reconcile config/initializers/new_framework_defaults_X_Y.rb, flip config.load_defaults, triage deprecations, and keep the test suite green between each step. Then guides the omakase stack modernizations (classic→Zeitwerk, Sprockets→Propshaft, Webpacker→importmaps/jsbundling, Sidekiq+Redis→Solid Queue/Cache/Cable, secrets.yml→encrypted credentials) by routing to the sibling rails-* skills that own each destination state. This skill owns the JOURNEY; siblings own the destination. Apply when upgrading Rails/Ruby versions, running app:update, reconciling framework defaults, migrating the autoloader, or modernizing the omakase stack of an older app.