Rails Agent Skills — Documentation

This is not just documentation — it is the operating system behind AI-driven Rails development.

Rails Agent Skills defines how AI agents should think, plan, and execute across the entire software lifecycle — from discovery to PR — with strict workflows and TDD as a non-negotiable quality gate.

Master index for all project documentation.

What this gives you

• A complete, structured workflow system (Discovery → PR)
• 39 production-grade skills with clear triggers and responsibilities
• Enforced TDD workflows (tests as a hard gate, not a suggestion)
• Context-aware orchestration across tasks and agents
• A repeatable way to turn AI into a reliable engineering system

This documentation is your entry point to understanding and applying that system.

🚀 Start Here

Think of this as a decision map — not just docs. Pick your current stage and follow the workflow.

Quick Start

If you're using AI agents in Rails, start here. This gives you the fastest path to the right workflow without guessing.

30 Seconds: Which Skill to Use

New to project?          → rails-context-engineering
Plan a feature?          → create-prd → generate-tasks
Start coding?            → rails-tdd-slices → rspec-best-practices
Fix a bug?               → rails-bug-triage
Refactor?                → refactor-safely
Code review?             → rails-code-review
Not sure?                → rails-skills-orchestrator

Master Flow Diagram

flowchart TD
    START([What do you need?]) --> DECISION{What stage?}

    DECISION -->|Discovery| D00[discovery]
    DECISION -->|Planning| D10[planning]
    DECISION -->|Setup| D20[setup]
    DECISION -->|Develop| D30[development]
    DECISION -->|Quality| D40[quality]
    DECISION -->|Review| D50[review]
    DECISION -->|Engines| D60[engines]

    D00 --> NEXT
    D10 --> NEXT
    D20 --> D30
    D30 --> D40
    D40 --> D50
    D60 --> D50

    NEXT{What next?} -->|Implement| D30
    NEXT -->|Done| END([PR / Merge])

    D50 -->|Feedback| RESPOND[rails-review-response]
    RESPOND --> D30
    D50 -->|OK| END

Workflows by Stage

Each workflow is designed to be executed by an AI agent (or human + AI) with clear steps, inputs, and expected outputs.

Step-by-step workflows for each development phase:

Complete index: workflows/README.md

Reference

Skill Catalog

Complete catalog of 39 skills organized by category:

• skill-catalog.md — List with descriptions and triggers
• integration-matrix.md — Which skill connects to which

Principles & Architecture

Guides

In-depth guides by specific topic:

Tests Gate Implementation

Non-negotiable principle across all workflows:

Write test → Run test → Verify it FAILS → Implement → Verify it PASSES

See details in each specific workflow.

External Links

• Repository: github.com/igmarin/rails-agent-skills
• Tessl Registry: tessl.io

File Structure

docs/
├── README.md                    # This file — master index
├── skill-design-principles.md   # Design principles
├── skill-template.md            # Template for skills
├── architecture.md            # SKILL.md conventions
├── implementation-guide.md    # IDE installation
├── plugin-validation.md       # Plugin validation
├── vs-code-setup.md          # VS Code specific
│
├── workflows/                 # Workflows by stage
│   ├── README.md
│   ├── discovery.md
│   ├── planning.md
│   ├── setup.md
│   ├── development.md
│   ├── quality.md
│   ├── review.md
│   └── engines.md
│
├── reference/                 # Quick reference (new)
│   ├── skill-catalog.md
│   └── integration-matrix.md
│
└── guides/                    # Deep guides (future)

Documentation Roadmap

• Reorganize workflows into separate files
• Create skill-catalog.md
• Create integration-matrix.md
• Migrate legacy content from workflow-guide.md
• Create specific guides (authorization, performance, etc.)

Note: This documentation is constantly evolving. If you find something confusing or missing, please open an issue in the repository.