Rails Agent Skills

Rails Agent Skills turns AI coding assistants into reliable Rails engineers — not just autocomplete tools.

It is a curated library of production-grade agent skills that encode conventions, workflows, and strict quality gates (TDD-first), so assistants generate code that actually holds up in real projects.

Why this exists

Most AI-generated code fails in real Rails apps because it lacks:

• awareness of project conventions
• disciplined workflows (especially TDD)
• structured context across tasks

This library fixes that by giving agents explicit skills and workflows — from PRD → tasks → implementation → review — with tests acting as a hard gate before any code is written.

The goal is simple: make AI outputs predictable, testable, and production-ready.

• Repository / install path: rails-agent-skills (docs/implementation-guide.md)
• Bootstrap discovery skill: [rails-skills-orchestrator](skills/orchestration/rails-skills-orchestrator/) (session hook loads orchestrator)
• Documentation: docs/README.md — Complete guides and workflows
• Workflows: docs/workflows/ — Reference docs + callable workflow skills
• Skill Catalog: docs/reference/skill-catalog.md — All 38+ skills organized by category
• Integration Matrix: docs/reference/integration-matrix.md — Skill chaining and workflows
• Skill structure: docs/architecture.md
• Eval optimization: docs/skill-optimization-guide.md — baseline-vs-context targets and the per-skill loop used to lift scores

Quick Start — Which Skill to Use?

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 core principle of this project. Tests are not a phase that happens "after" development — they are a hard 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:

skills/testing/rails-tdd-slices → skills/testing/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]
    ↓
skills/patterns/yard-documentation → Update docs
    ↓
skills/code-quality/rails-code-review (self-review) → skills/code-quality/rails-review-response (on feedback)
    ↓
PR

See docs/workflows/ for the full TDD Feature Loop and all workflow diagrams by lifecycle stage.

Note: ticket-planning is an optional step. The assistant should not push for ticket generation unless the user asks explicitly (e.g. "turn this into tickets") or the context clearly indicates work should be mapped to a 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 Workflows Index.

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, test-driven, and meets production-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 Workflows Index.

MCP Server

The recommended way to use this library is via the included Ruby MCP server. It exposes every skill, doc, and workflow as a named MCP resource — allowing agents to load only what they need, reducing token usage while improving accuracy and relevance.

tools/call use_skill { "skill_name": "rails-graphql-best-practices" }
→ returns full SKILL.md instructions

Resources exposed:

Adding a new skill directory automatically makes it available — no server changes needed.

See mcp_server/README.md for setup instructions (Windsurf, Cursor, Claude Code, RubyMine, Docker).

Install via GitHub CLI

Requires GitHub CLI v2.90.0+.

# Install all skills interactively
gh skill install igmarin/rails-agent-skills

# Install a specific skill for the current project
gh skill install igmarin/rails-agent-skills rails-code-review --scope project

# Install a specific skill globally (available everywhere)
gh skill install igmarin/rails-agent-skills rails-code-review --scope user

# Install pinned to a release tag
gh skill install igmarin/rails-agent-skills rails-code-review --pin v3.1.3 --scope user

# Search this repository's skills
gh skill search rails --owner igmarin

The default scope is project; use --scope user for a global install in your home directory. Skills are installed to the correct directory for your selected agent host automatically. To target a specific agent:

gh skill install igmarin/rails-agent-skills rails-tdd-slices --agent claude-code --scope user
gh skill install igmarin/rails-agent-skills rails-tdd-slices --agent cursor --scope user
gh skill install igmarin/rails-agent-skills rails-tdd-slices --agent codex --scope user
gh skill install igmarin/rails-agent-skills rails-tdd-slices --agent gemini-cli --scope user
gh skill install igmarin/rails-agent-skills rails-tdd-slices --agent windsurf --scope user

Update installed skills:

# Check for updates without changing files
gh skill update --dry-run

# Update all unpinned skills without prompting
gh skill update --all

# Re-download all skills, overwriting local edits
gh skill update --force --all

# Unpin pinned skills and update them to the latest release
gh skill update --unpin

Supply chain note: Every release is tied to a git tag. Pinning to a tag or commit SHA (--pin) gives you reproducible, tamper-evident installs. Provenance metadata is written directly into each installed SKILL.md frontmatter so it travels with the skill.

Platforms & Quick Start

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

The guide covers both the MCP server (recommended — on-demand, saves tokens) and symlink approaches for each platform.

Skills Catalog

Planning & Tasks

Rails Code Quality

DDD & Domain Modeling

Ruby Patterns

Context & Setup

Testing

Rails Engines

Refactoring

Meta

Skill Relationships

graph TB
    subgraph Discovery [🔍 00: Discovery]
        direction TB
        A[rails-context-engineering] --> B{New project?}
        B -- Yes --> C[rails-project-onboarding]
        B -- No --> D[Start]
        C --> D
    end

    subgraph Planning [📝 10: Planning]
        direction TB
        D --> E[create-prd]
        E --> F{PRD approved?}
        F -- No --> E
        F -- Yes --> G[generate-tasks]
        G --> H{Need DDD?}
        H -- Yes --> I[ddd-ubiquitous-language]
        I --> J[ddd-boundaries-review]
        J --> K[ddd-rails-modeling]
        K --> G
    end

    subgraph Development [💻 30: Development]
        direction TB
        H -- No --> L[rails-tdd-slices]
        G --> L
        L --> M[rspec-best-practices]
        M --> N{Test OK?}
        N -- No --> M
        N -- Yes --> O{Proposal OK?}
        O -- No --> O
        O -- Yes --> P[Implement]
        P --> Q{Passes?}
        Q -- No --> P
        Q -- Yes --> R{More?}
        R -- Yes --> M
        R -- No --> S[Linters + Suite]
    end

    subgraph Quality [✅ 40-50: Quality & Review]
        direction TB
        S --> T[yard-documentation]
        T --> U[rails-code-review]
        U --> V{Findings?}
        V -- Critical --> W[rails-review-response]
        W --> X[Fix]
        X --> U
        V -- None/Minor --> Y((Merge))
    end

    subgraph Engines [🔧 60: Engines]
        direction TB
        Z[rails-engine-author] --> AA{Tests pass?}
        AA -- No --> AB[Fix]
        AB --> Z
        AA -- Yes --> AC[rails-engine-release]
        AC --> AD((Release))
    end

    %% Cross-connections
    U --> V1[rails-security-review]
    U --> V2[rails-architecture-review]
    V2 --> V3[refactor-safely]
    V3 --> V4[ruby-service-objects]

    BT[rails-bug-triage] --> L

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/workflows/ 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.

• ticket-planning: added assets/ticket-samples and ticket-schema.json to aid robust ticket generation across models
• rails-stack-conventions: added compact assets/snippets for few-shot examples to improve cross-model robustness