Rails Agent Skills

Rails Agent Skills is a curated library of AI agent skills for Ruby on Rails development. Skills encode specialized knowledge, conventions, and workflow patterns so assistants deliver higher-quality code.

• Repository / install path: rails-agent-skills (docs/implementation-guide.md)
• Bootstrap discovery skill: [rails-skills-orchestrator](rails-skills-orchestrator/) (session hook loads rails-skills-orchestrator/SKILL.md where applicable)
• Workflows: docs/workflow-guide.md — Skill structure: docs/architecture.md
• How to invoke a skill or workflow: docs/workflow-guide.md#how-to-invoke

Methodology

This skill library is built on core principles that shape how every skill operates. For detailed guidance on skill design, read the official Skill Design Principles.

1. Tests Gate Implementation

The central methodology of this project. Tests are not a phase that happens "after" or "alongside" development — they are a gate that must be passed before any implementation code can be written.

PRD → Tasks → [GATE] → Implementation → YARD → Docs → Code review → PR
                 │
                 ├── 1. Test EXISTS (written and saved)
                 ├── 2. Test has been RUN
                 └── 3. Test FAILS for the correct reason
                        (feature missing, not a typo)

        Only after all 3 conditions are met
        can implementation code be written.

After tests pass: document public Ruby API (YARD), update README/diagrams/
related docs, then self-review (rails-code-review) before opening the PR.
Task lists from generate-tasks include these steps explicitly.

This applies to every skill that produces code: service objects, background jobs, API integrations, engine components, refactoring, and bug fixes. Every implementation skill in this library includes a HARD-GATE: Tests Gate Implementation section enforcing this discipline.

Why this matters:

• A test that passes immediately proves nothing — you don't know if it tests the right thing
• A test you never saw fail could be testing existing behavior, not the new feature
• Implementation code written before the test is biased by what you built, not what's required

Generated output: All generated artifacts (documentation, YARD comments, Postman collections, examples) must be in English unless the user explicitly requests another language. This is reflected in the skill template and in yard-documentation and api-rest-collection.

2. Workflow Chaining

Skills are designed to be used in sequence, not in isolation. Each skill's Integration table points to the next skill in the chain. The primary daily workflow is:

rails-tdd-slices → rspec-best-practices (write failing test)
    ↓
[CHECKPOINT: Test Design Review — confirm boundary, behavior, edge cases]
    ↓
[CHECKPOINT: Implementation Proposal — confirm approach before coding]
    ↓
Implement (minimal code to pass test) → Refactor
    ↓
[GATE: Linters + Full Test Suite]
    ↓
yard-documentation → Update docs
    ↓
rails-code-review (self-review) → rails-review-response (on feedback)
    ↓
PR

See docs/workflow-guide.md for the full TDD Feature Loop and all workflow diagrams.

Note: ticket-planning is an optional step. The assistant should not push for Jira ticket generation unless the user asks explicitly (e.g. "turn this into Jira tickets") or the context clearly indicates work should be mapped to a Jira board/sprint.

3. Rails-First Pattern Reuse

This library intentionally reuses proven patterns from broader agent-skill libraries, but translates them into a Rails-first workflow instead of copying generic frontend-oriented skills one-to-one.

The rule of thumb is: reuse patterns, not names. If a broader skill maps cleanly to Rails/RSpec/YARD workflows, absorb the pattern into the existing chain. Create a new skill only when there is a real Rails-specific workflow gap.

How to Build a Feature (Your Daily Workflow)

For a practical guide on how to talk to the AI and effectively invoke these workflows, please see our How to Invoke a Workflow Guide.

Here is the recommended, step-by-step workflow for building a new feature from scratch using this skill library. This ensures every feature is well-planned, robustly tested, and adheres to project quality standards.

Goal: Build a new feature, e.g., "Feature A"

Step 1: Planning & Task Breakdown

• Action: Define the feature's requirements.
  • Use Skill: create-prd
• Then: Break the PRD into a detailed, TDD-ready checklist.
  • Use Skill: generate-tasks

Step 2: Start the TDD Cycle

• Action: Pick the first, highest-value "slice" of behavior from your task list.
• Action: Get guidance on choosing the right type of test to write first (e.g., a request spec).
  • Use Skill: rails-tdd-slices
• Action: Write the first failing test. Crucially, run it and watch it fail.
  • Use Skill: rspec-best-practices

Step 3: Implementation

• Action: Write the minimum amount of application code required to make your failing test pass.
  • Use Skills: ruby-service-objects for business logic, rails-code-conventions for general code quality.

Step 4: Verification

• Action: Run the test again and watch it pass.
• Action: Run linters and the full test suite to ensure no regressions. Refactor your new code if needed.

Step 5: Documentation & Self-Review

• Action: Add inline documentation to any new public classes or methods.
  • Use Skill: yard-documentation
• Action: Perform a self-review of your changes.
  • Use Skill: rails-code-review

Step 6: Responding to Peer Review

• Action: When you receive feedback from teammates, evaluate and implement their suggestions systematically.
  • Use Skill: rails-review-response

For more detailed diagrams of these flows, see the Workflow Guide.

Platforms & Quick Start

To integrate these skills with your preferred AI development environment (such as Gemini CLI, Cursor, Windsurf, Claude Code, Codex, or RubyMine), please refer to the Implementation Guide.

This guide provides detailed, step-by-step instructions for both the symlink-based and the recommended Model Context Protocol (MCP) server approaches for each platform.

Skills Catalog

Planning & Tasks

Rails Code Quality

DDD & Domain Modeling

Ruby Patterns

Testing

Rails Engines

Refactoring

Meta

Skill Relationships

flowchart TD
    createPRD[create-prd] --> generateTasks[generate-tasks]
    createPRD --> dddLanguage[ddd-ubiquitous-language]
    dddLanguage --> dddBoundaries[ddd-boundaries-review]
    dddBoundaries --> dddModeling[ddd-rails-modeling]
    dddBoundaries --> archReview
    dddModeling --> generateTasks
    dddModeling --> railsConventions

    generateTasks --> jiraPlanning[ticket-planning]
    generateTasks --> tddSlices[rails-tdd-slices]

    tddSlices --> rspecBest[rspec-best-practices]
    rspecBest --> testFeedback["CHECKPOINT: Test Feedback"]
    testFeedback --> implProposal["CHECKPOINT: Implementation Proposal"]
    implProposal --> implement["Implement"]
    implement --> lintersGate["GATE: Linters + Full Suite"]

    lintersGate --> railsConventions[rails-code-conventions]
    railsConventions --> stackConventions[rails-stack-conventions]
    lintersGate --> yardDoc[yard-documentation]
    yardDoc --> docUpdates[README diagrams docs]
    docUpdates --> codeReview[rails-code-review]

    codeReview --> reviewResponse[rails-review-response]
    reviewResponse --> codeReview

    codeReview --> archReview[rails-architecture-review]
    codeReview --> secReview[rails-security-review]
    codeReview --> migrationSafety[rails-migration-safety]

    archReview --> refactorSafely[refactor-safely]
    refactorSafely --> serviceObjects[ruby-service-objects]

    serviceObjects --> apiClient[ruby-api-client-integration]
    serviceObjects --> strategyFactory[strategy-factory-null-calculator]
    serviceObjects --> yardDoc
    apiClient --> yardDoc

    graphql[rails-graphql-best-practices] --> tddSlices
    graphql --> secReview
    graphql --> yardDoc

    engineAuthor --> postman[api-rest-collection]
    engineDocs[rails-engine-docs] --> postman

    bugTriage[rails-bug-triage] --> tddSlices
    rspecService[rspec-service-testing] --> rspecBest

    engineAuthor[rails-engine-author] --> engineTestGate["GATE: Write engine specs, verify failure"]
    engineTestGate --> engineTesting[rails-engine-testing]
    engineAuthor --> engineDocs
    engineAuthor --> engineInstallers[rails-engine-installers]
    engineTesting --> engineReviewer[rails-engine-reviewer]
    engineReviewer --> engineRelease[rails-engine-release]
    engineRelease --> engineCompat[rails-engine-compatibility]
    engineExtraction[rails-engine-extraction] --> engineAuthor

How Skills Work

Each skill is a SKILL.md file in its own directory. For detailed conventions and structure, refer to the Skill Design Principles.

Typical Workflows

Tests are a gate between planning and implementation. See docs/workflow-guide.md for full diagrams.

Creating New Skills

For guidance on skill authoring, refer to the Skill Design Principles and the Skill Template.

Acknowledgments

Huge thanks to Mumo Carlos (@mumoc). His mentorship has shaped my growth as a developer and influenced many of the habits and practices reflected in this library — not only the ticket-planning workflow he shared, but the broader discipline around quality, clarity, and thoughtful use of tools. This repo and the learning behind it would not be what they are without him.