rails-agent-skills

Use when the goal is to change code structure without changing behavior — this includes extracting a service object from a fat controller or model, splitting a large class, renaming abstractions, reducing duplication, or reorganizing modules. Covers characterization tests (write tests that document current behavior before touching the code), safe extraction in small steps, and verification after every step. Do NOT use for bug fixes or new features — those follow the TDD gate in rspec-best-practices. Do NOT mix structural changes with behavior changes in the same step.

Use before writing code, tests, or PRDs in a Rails project to load the minimum context needed to make correct decisions. Inspects `db/schema.rb`, `config/routes.rb`, neighboring models, factories, specs, engine boundaries, and `Gemfile.lock` to surface existing patterns, naming conventions, and gotchas. Produces a concise context summary before any code is proposed, and a confusion-management block when requirements are ambiguous or specs and code have drifted. Trigger words: load context, gather context, context engineering, read the code first, before I code, existing patterns, project conventions, where is this defined, ambiguous requirements, spec vs code drift, unclear spec, missing requirements, what does the codebase already use, match existing style.

Emit a generic Rails development-environment setup runbook for the user to execute locally. Covers Docker, environment variables, database, test suite, linters, and IDE. The agent does not read the user's repository or execute setup commands. Trigger words: onboarding, new dev, setup project, Docker, development environment, getting started.

Use when reviewing a Ruby on Rails app for Domain-Driven Design boundaries, bounded contexts, language leakage, cross-context orchestration, or unclear ownership. Identifies misplaced domain models, detects cross-context coupling, names ownership conflicts, and recommends the smallest credible boundary improvement. Covers context mapping and leakage detection.

Use when modeling Domain-Driven Design concepts in a Ruby on Rails codebase. Covers Rails-first mapping of entities, aggregates, value objects, domain services, application services, repositories, and domain events without over-engineering or fighting Rails conventions.

Use when a Ruby on Rails feature, bug, or architecture discussion has fuzzy business terminology and you need shared vocabulary. Identifies canonical terms, resolves naming conflicts, maps synonyms to one concept, and generates a glossary for Rails-first workflows. Trigger words: DDD, shared vocabulary, define terms, bounded context naming, what should we call this, terminology alignment, DDD glossary, naming inconsistency.

Use when creating, scaffolding, or refactoring a Rails engine. Covers engine types (Plain, Railtie, Engine, Mountable), namespace isolation, host-app contract definition, and recommended file structure.

Use when making a Rails engine stable across Rails and Ruby versions. Configures Zeitwerk autoloading, updates gemspec dependency bounds, replaces Rails.version branching with feature detection patterns, and sets up CI matrices for cross-version testing. Trigger words: Zeitwerk, autoloading, Rails upgrade, gemspec, dependency bounds, CI matrix, feature detection, reload safety, deprecated APIs, cross-version.

Use when writing or maintaining documentation for Rails engines. Generates README templates, writes installation and configuration guides, documents mount points, extension APIs, and migration notes for host-app adoption. Trigger words: engine README, installation guide, configuration docs, mount instructions, migration notes, extension points, host integration examples, setup documentation.

Use when extracting existing Rails app code into a reusable engine. Scaffolds the engine structure, moves POROs/services/controllers incrementally, creates adapter interfaces to decouple host dependencies, and verifies regression coverage throughout each extraction slice. Trigger words: extract to engine, move feature to engine, host coupling, adapters, extraction slices, preserve behavior, incremental extraction, bounded feature.

Use when creating install generators, copied migrations, or initializer installers for Rails engines. Covers idempotent setup tasks, host-app onboarding, and route mount setup. Trigger words: install generator, mountable engine setup, gem installation, engine onboarding, rails plugin installer, copy migrations, initializer generator, route mount setup, engine configuration generator.

Use when preparing a Rails engine gem release. Generates CHANGELOG.md entries, produces step-by-step upgrade notes for host apps, sets semantic version constants, verifies gemspec metadata, confirms test suite passes, and sequences gem build and publish commands. Trigger words: version bump, changelog, deprecation, gemspec, upgrade, migration guide, release, publish gem, ship gem, verify gemspec, test suite.

Use when reviewing a Rails engine, mountable engine, or Railtie. Covers namespace boundaries, host-app integration, safe initialization, migrations, generators, and dummy app test coverage. Prioritizes architectural risks.

Use when creating or improving RSpec test coverage for Rails engines. Covers dummy app setup, request, routing, generator, and configuration specs for proving engine behavior within a host application.

Implements REST API versioning strategies in Rails, covering URL path versioning, header-based versioning, deprecation policies, and maintaining backward compatibility across versions. Use when adding a new API version (v1, v2), planning API evolution, setting deprecation or sunset policies, or ensuring backward compatibility for existing consumers.

Use when adding or reviewing background jobs in Rails. Configures Active Job workers, implements idempotency checks, sets up retry/discard strategies, selects Solid Queue (Rails 8+) or Sidekiq based on scale, and defines recurring jobs via recurring.yml or sidekiq-cron. Trigger words: background job, Active Job, Solid Queue, Sidekiq, idempotency, retry, discard, recurring job, queue.

Manage development and test data in Rails. Covers fixtures vs seeds, seeding strategies for different environments, test data factories, and production-like data generation. Trigger words: seeds, fixtures, seeding, database seed, test data, development data, db:seed.

Creates Stimulus controllers, configures Turbo Frame lazy loading, sets up Turbo Stream broadcasts, and converts traditional Rails views to Hotwire patterns for interactive, real-time UIs. Use when the user asks about adding real-time updates, replacing full page reloads with Turbo, building interactive Rails UIs without heavy JavaScript frameworks, or wiring up Stimulus behavior to existing HTML. Trigger words: Hotwire, Turbo, Stimulus, Turbo Frames, Turbo Streams, progressive enhancement, SPA without JS.

Use when planning or reviewing production database migrations, adding columns, indexes, constraints, backfills, renames, table rewrites, or concurrent operations. Covers phased rollouts, lock behavior, rollback strategy, strong_migrations compliance, and deployment ordering for schema changes.

Optimizes Rails application performance. Use when investigating slow endpoints, eliminating N+1 queries, implementing caching strategies, profiling with Bullet or rack-mini-profiler, or optimizing database queries with EXPLAIN ANALYZE. Trigger words: performance, optimize, N+1, slow query, caching, Bullet, profiling.

Triages and decomposes complex Ruby on Rails requests into ordered sub-tasks, then delegates to specialized skills for testing, code review, engines, DDD, and patterns. Enforces TDD discipline across all code-producing work. Use when scope is unclear, the best approach is uncertain, or a request spans multiple Rails concerns. Trigger: where do I start, help me plan a Rails feature, break this down, what's the best approach for this Rails work, not sure how to approach this, multi-step Rails task, complex Rails task, what should I do first.

Use when creating or refactoring Ruby service classes in Rails. Covers the .call pattern, module namespacing, YARD on self.call AND every public method, module README requirement, standardized {success:, response:} response contract, orchestrator delegation, transaction wrapping, and error handling conventions. Trigger words: service object, .call pattern, app/services, service module, service README, response hash, success/response shape, YARD on self.call.

Use when building variant-based calculators with a single entry point that picks the right implementation (Strategy + Factory), or when adding a no-op fallback (Null Object). Generates variant-based calculator classes, implements SERVICE_MAP routing, and scaffolds RSpec tests per variant. Trigger words: design pattern, Ruby, dispatch table, polymorphism, no-op default, variant calculator, strategy pattern, factory pattern, null object pattern.

Use when writing or reviewing inline documentation for Ruby code. Every public method MUST include param, return, and raise tags. For self.call methods, the return tag MUST specify the return type and structure (e.g., return [Hash] with :success and :response keys). List each exception separately with its own raise tag. Trigger words: YARD, inline docs, method documentation, API docs, public interface, rdoc, return tag, raise tag.

Generates a clear, actionable Product Requirements Document (PRD) in Markdown from a feature description and saves it to /tasks/prd-FEATURE-SLUG.md following PRD_TEMPLATE.md. Use when a user asks to plan a feature, define requirements, create a PRD, or write a product spec. Covers goals, user stories, functional requirements, non-goals, design and technical considerations, implementation surface, success metrics, and open questions for Rails-oriented workflows. Trigger words: PRD, product requirements, plan a feature, write a spec, requirements document, /tasks/ folder.

Use when breaking down a feature or generating an implementation task list from a PRD. Output MUST follow this exact structure: (1) Task 0.0: Create feature branch with git checkout command, (2) Relevant Files section listing all files with concrete paths, (3) At least 3 TDD task groups with four sub-tasks each: X.Xa Write spec, X.Xb Run spec and verify it FAILS, X.Xc Implement, X.Xd Run spec and verify it PASSES, (4) YARD documentation task, (5) Documentation update task for README/diagrams, (6) Code review gate, (7) Save as tasks-[name].md in /tasks/ folder. Trigger words: task list, implementation plan, feature breakdown, todo list, project tasks, work plan, break down this PRD, generate tasks, feature branch, TDD, write spec, run spec fail, run spec pass.

Drafts, classifies, and optionally creates tickets from an initiative plan. Use when the user provides a plan and wants ticket drafts, wants help shaping a plan into tickets, wants sprint-placement guidance, or wants tickets created in an issue tracker after the plan is approved.

Use when investigating a bug, error, or regression in a Ruby on Rails codebase. Creates a failing RSpec reproduction test, isolates the broken code path, and produces a minimal fix plan. Trigger words: debug, broken, error, regression, stack trace, failing test, RSpec, bug report, Rails app.

Use when choosing the best first failing RSpec spec or vertical slice for a Ruby on Rails change. Covers request vs model vs service vs job vs engine spec selection, system spec escalation, smallest safe slice planning, and Rails-first TDD sequencing. Trigger words: where to start testing, what test to write first, RSpec, test-driven development, TDD, first failing test.

Use when writing, reviewing, or cleaning up RSpec tests for Ruby and Rails codebases. Covers spec type selection, factory design, flaky test fixes, shared examples, deterministic assertions, test-driven development discipline, and choosing the best first failing spec for Rails changes. Also applies when choosing between model, request, system, and job specs.

Use when writing RSpec tests for service objects, API clients, orchestrators, or business logic in spec/services/. Covers instance_double, FactoryBot hash factories, shared_examples, subject/let blocks, context/describe structure, aggregate_failures, change matchers, travel_to, and error scenario testing.

Orchestrates the full Rails test-driven development cycle: generates a failing spec first, implements minimal code to pass, refactors, then produces YARD documentation and a self-reviewed PR. Use when practicing test-driven development, red-green-refactor, TDD workflow, writing tests before code, adding tests first, or building a Rails feature where specs must gate implementation.

Multi-pass Rails code review workflow that identifies bugs, security vulnerabilities, and architectural issues; assigns severity levels (Critical, Suggestion, Nice-to-have); and generates actionable review comments with a mandatory re-review loop for Critical findings. Use for full PR review workflows, multi-pass security or architecture audits, or implementing and verifying responses to review feedback. Trigger: review this PR, full code review, multi-pass review, audit security vulnerabilities, review architecture, respond to review feedback, implement review fixes.

Complete Rails project setup workflow. Installs dependencies via Bundler, configures database connections, generates Rails app scaffold, validates the dev environment, and generates GitHub Actions or GitLab CI pipelines with linting, testing, and security scanning. Use when starting a new Rails project, running `rails new`, configuring a Gemfile or .ruby-version, setting up a development environment, or wiring up CI/CD for a Ruby on Rails app. Trigger: setup project, new Rails app, configure CI/CD, dev environment setup, rails new, Gemfile setup, .ruby-version, Ruby on Rails project bootstrap.

Complete code quality workflow for Rails projects. Enforces naming conventions, reduces duplication, extracts methods and service objects, reduces complexity, and generates YARD docstrings and inline comments across the full codebase. Use this composite end-to-end workflow instead of individual refactoring or documentation skills when the full three-phase production-readiness review is needed together in one pass. Use when: code review prep, before PR, full Rails quality sweep, quality audit, production-ready review, end-to-end quality check.

Complete Rails engine development workflow. Orchestrates scaffolding engine structure and generating mountable namespaces → testing → code review and dependency auditing → release. Use when creating, extracting, or maintaining Rails engines. Trigger: create engine, extract engine, engine release, engine testing, mountable engine, gem extraction.

Use when creating or modifying REST API endpoints (Rails controllers, engine routes, API actions). Requires generating or updating an API Collection file (e.g., Postman Collection v2.1) so the new or changed endpoints can be tested. Trigger words: endpoint, API route, controller action, API collection, request collection.

Use when building or reviewing GraphQL APIs in Rails with the graphql-ruby gem. Covers schema design, N+1 prevention with dataloaders, field-level auth, query limits, error handling, and testing resolvers/mutations with RSpec.

Use when integrating with external APIs in Ruby, creating HTTP clients, or building data pipelines in the user's Rails repo. This skill defines a code pattern (not live agent browsing): layered Auth, Client, Fetcher, Builder, and Domain Entity with token caching, retry logic, and FactoryBot hash factories for test data.

Use when reviewing Rails application structure, identifying fat models or controllers, auditing callbacks, concerns, service extraction, domain boundaries, or general Rails architecture decisions. Recommends service object extractions, simplifies callback chains, identifies abstraction quality issues, and produces severity-classified findings with the smallest credible improvement for each.

Implement and test authorization in Rails applications using Pundit or CanCanCan. Covers policy objects, role-based access control, permission checks, and testing strategies. Use when the user needs to implement or troubleshoot authorization in a Rails app, set up user roles and permissions, or mentions Pundit, CanCanCan, policy objects, access control, roles, or permissions.

A daily checklist for writing clean Rails code, covering design principles (DRY, YAGNI, PORO, CoC, KISS), per-path rules (models, services, workers, controllers), structured logging, and comment discipline. Defers style and formatting to the project's configured linter(s). Use when writing, reviewing, or refactoring Ruby on Rails code, or when asked about Rails best practices, clean code, or code quality. Trigger words: code review, refactor, RoR, clean code, best practices, Ruby on Rails conventions.

Reviews Rails pull requests, focusing on controller/model conventions, migration safety, query performance, and Rails Way compliance. Covers routing, ActiveRecord, security, caching, and background jobs. Use when reviewing existing Rails code for quality, conducting a PR review, or doing a code review on Ruby on Rails (RoR) code.

Applies when a developer has received code review feedback on Rails code and needs to decide what to implement, how to respond, and in what order. Use when addressing PR comments, pull request feedback, or review comments on Rails code. Covers evaluating reviewer suggestions, pushing back with technical reasoning, avoiding performative agreement, implementing feedback safely one item at a time, and triggering a re-review when needed. Trigger scenarios: respond to reviewer, address review comments, handle pull request feedback.

Performs security audits and vulnerability assessments on Ruby on Rails application code. Use when reviewing Rails code for security risks, assessing authentication or authorization, auditing parameter handling, redirects, file uploads, secrets management, or checking for XSS, CSRF, SSRF, SQL injection, and other common vulnerabilities.

Use when writing new Rails code for a project using the PostgreSQL + Hotwire + Tailwind CSS stack. Covers stack-specific patterns only: MVC structure, ActiveRecord query conventions, Turbo Frames/Streams wiring, Stimulus controllers, and Tailwind component patterns. Not for general Rails design principles — this skill is scoped to what changes based on this specific technology stack.

Implements a single, focused code change by writing or modifying source code, adding unit and integration tests, and running the project's test suite to verify correctness. Use when the user asks to implement a feature, fix a bug, make a code change, add tests to existing code, or deliver any scoped behavioral change. Handles one task at a time rather than large refactors or multi-file architectural overhauls.

1 hook across 1 event