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.

The Proof: Baseline vs Context

We measure the effectiveness of our skills by comparing a "Baseline" agent (raw LLM) against an agent using our Skill Context. The difference in scores (the Lift) is the mathematical proof of the value this library provides.

Scores based on evaluation runs using Claude 3.5 Sonnet. A skill that only beats baseline marginally is considered under-specified; our goal is a significant lift on every non-generic convention.

• Repository / install path: rails-agent-skills (docs/implementation-guide.md)
• Bootstrap discovery skill: [skill-router](skills/orchestration/skill-router/) (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 (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 write-yard-docs and generate-api-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/plan-tests → skills/testing/write-tests (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/write-yard-docs → Update docs
    ↓
skills/code-quality/code-review (self-review) → skills/code-quality/respond-to-review (on feedback)
    ↓
PR

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

Note: plan-tickets 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: plan-tests
• Action: Write the first failing test. Crucially, run it and watch it fail.
  • Use Skill: write-tests

Step 3: Implementation

• Action: Write the minimum amount of application code required to make your failing test pass.
  • Use Skills: create-service-object for business logic, apply-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: write-yard-docs
• Action: Perform a self-review of your changes.
  • Use Skill: code-review

Step 6: Responding to Peer Review

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

For more detailed diagrams of these flows, see the Workflows Index.

MCP Server

The recommended way to use this library is via the embedded Ruby MCP server. The primary setup is local Ruby/Bundler; Docker is supported as a fallback for environments that do not want a local Ruby toolchain.

The use_skill tool loads individual skills on demand, while docs and workflows remain available as MCP resources. That keeps the runtime contract small while still making the full skill library available.

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

Published MCP surface:

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

See mcp_server/README.md for the canonical MCP setup instructions and Docker fallback. Use docs/implementation-guide.md for the broader platform overview and non-MCP alternatives.

Important: When configuring MCP in external tools (like Cursor, Windsurf, OpenCode, etc.), always use absolute paths for cwd and BUNDLE_GEMFILE to avoid environment and timeout errors.

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 code-review --scope project

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

# Install pinned to a release tag
gh skill install igmarin/rails-agent-skills 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 plan-tests --agent claude-code --scope user
gh skill install igmarin/rails-agent-skills plan-tests --agent cursor --scope user
gh skill install igmarin/rails-agent-skills plan-tests --agent codex --scope user
gh skill install igmarin/rails-agent-skills plan-tests --agent gemini-cli --scope user
gh skill install igmarin/rails-agent-skills plan-tests --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, refer to the Implementation Guide.

Platform Integration Overview

The guide covers the MCP server (recommended — on-demand, saves tokens), the Docker fallback, and the 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[load-context] --> B{New project?}
        B -- Yes --> C[setup-environment]
        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[define-domain-language]
        I --> J[review-domain-boundaries]
        J --> K[model-domain]
        K --> G
    end

    subgraph Development [💻 30: Development]
        direction TB
        H -- No --> L[plan-tests]
        G --> L
        L --> M[write-tests]
        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[write-yard-docs]
        T --> U[code-review]
        U --> V{Findings?}
        V -- Critical --> W[respond-to-review]
        W --> X[Fix]
        X --> U
        V -- None/Minor --> Y((Merge))
    end

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

    %% Cross-connections
    U --> V1[security-check]
    U --> V2[review-architecture]
    V2 --> V3[refactor-code]
    V3 --> V4[create-service-object]

    BT[triage-bug] --> 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.

Skills vs. Workflows

This library differentiates between two types of agent capabilities:

• Skills (skills/): Atomic, specialized modules (e.g., code-review, write-yard-docs). These are optimized for static analysis and "one-shot" tasks.
• Workflows (workflows/): Higher-level orchestrators (e.g., tdd-workflow) that chain multiple skills together.
  • Important: Workflows require an agent with ReAct capabilities (like the Gemini CLI, Claude Code, or Cursor with workspace context). They are designed to read multiple files, execute shell commands, and manage state across several turns.
  • Note on Scoring: While platform static analysis might score workflows lower due to their dependency on external files, their actual performance is validated dynamically using our custom ReAct evaluation tool.

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 plan-tickets 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.

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