Rails Agent Skills

Rails Agent Skills turns AI coding assistants into disciplined Rails collaborators.

It is a curated library of 41 public Rails agent skills and 9 callable workflows that teach AI tools how to plan, test, implement, document, and review Rails work using production-minded conventions.

The project is built around one non-negotiable rule:

Write test -> run test -> verify it fails for the right reason -> implement -> verify it passes

That TDD gate is encoded directly into the skills and workflows, so agents do not just produce plausible Rails code. They follow a repeatable engineering process.

Supported agent environments

Official distribution

Who This Is For

What Is In The Repository

The skills are not long-form tutorials. They are executable instructions for AI agents: when to gather context, when to stop for a checkpoint, how to write the first failing test, what Rails conventions to apply, and how to review the result.

Start Here

Rails Agent Skills can be invoked in three distinct ways depending on your environment and desired level of autonomy:

1. MCP (use_skill): Autonomous tool calls by the agent (e.g., Claude Desktop, Cursor).
2. Chat Commands: Explicitly forcing the agent to use a skill via @skill-name or /skill-name.
3. CLI (gh skill / tessl): Manual installation or evaluations in the terminal.

Read the complete guide on Calling Skills and Workflows for syntax examples and when to use each method.

The recommended way for autonomous usage is through the MCP server. MCP keeps the agent context small: docs and workflows are exposed as resources, available skills are discoverable through list_skills, and individual skills are loaded on demand. The use_skill tool returns a specific skill's SKILL.md only when the agent needs it.

MCP Quick Start

For hosted MCP clients and registries that support Streamable HTTP, use the Cloudflare Worker endpoint:

https://rails-agent-skills-mcp.ismael-marin.workers.dev/mcp

Useful public checks:

Health: https://rails-agent-skills-mcp.ismael-marin.workers.dev/health
Server card: https://rails-agent-skills-mcp.ismael-marin.workers.dev/.well-known/mcp/server-card.json

For repeatable team installs, prefer the versioned Docker image published from a Git release tag:

{
  "mcpServers": {
    "rails-agent-skills": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "--rm", "-i", "igmarin/rails-agent-skills-mcp:5.1.5"]
    }
  }
}

For local development, clone the repo and run the Ruby server:

git clone https://github.com/igmarin/rails-agent-skills.git ~/rails-agent-skills
cd ~/rails-agent-skills/mcp_server
bundle install
bundle exec ruby server.rb

See mcp_server/README.md for host-specific MCP configuration for Claude Code, Cursor, Windsurf, RubyMine, OpenCode, and other stdio MCP clients.

When configuring MCP in external tools, use absolute paths for cwd and BUNDLE_GEMFILE. Relative paths and ~ are a common cause of gem-loading and timeout failures.

Using Workflows via MCP

Workflows are the primary way to orchestrate multi-step Rails development tasks. When connected via MCP, agents can automatically discover and execute workflows using two tools:

1. Discover available workflows:

Agent calls: list_workflows
Returns: 9 workflows with metadata (tdd, quality, review, setup, engine, bug-fix, graphql, migration, background-job)

2. Load and execute a specific workflow:

Agent calls: use_workflow(workflow_name: "tdd")
Returns: Full workflow instructions with phases, gates, and skill chaining

Example usage in MCP:

• User: "I need to implement a new feature with TDD"
• Agent: Calls list_workflows → discovers tdd workflow → calls use_workflow("tdd") → executes full TDD cycle

Available workflows:

• tdd: Full TDD feature cycle (test → implement → review → PR)
• quality: Code quality sweep (conventions → refactor → docs)
• review: Systematic PR review (review → deep dive → response)
• setup: Project setup and CI/CD configuration
• engine: Rails engine development lifecycle
• bug-fix: Bug triage and resolution with TDD
• graphql: GraphQL API development with domain modeling
• migration: Safe database migration deployment
• background-job: Robust background job implementation

Workflows enforce hard gates (like "tests must pass before implementation") and include TDD enforcement, making them more reliable than ad-hoc skill chaining.

Daily Workflow

Depending on your environment (MCP vs. Chat Commands), you can orchestrate your daily Rails work using these common loops. For explicit control in Cursor or Windsurf, prepend these with @ (e.g., @load-context). In MCP, simply describe the goal and the agent will load them automatically.

The core TDD feature loop:

load-context
  -> plan-tests
  -> write-tests
  -> [verify failing test]
  -> [implement]
  -> [verify passing test]
  -> write-yard-docs
  -> code-review

For a new feature from scratch:

create-prd -> generate-tasks -> TDD feature loop

For a bug:

bug-fix (triage -> reproduce test -> fix -> verify)

For a GraphQL API:

graphql (domain modeling -> schema design -> TDD -> security review)

For a database migration:

migration (plan -> test -> staging -> production deployment)

For a background job:

background-job (design -> TDD -> retry config -> monitoring)

For a Rails engine:

create-engine -> test-engine -> document-engine -> review-engine -> release-engine

See docs/workflow-guide.md and docs/workflows/ for the full workflow guide containing detailed Mermaid diagrams of each phase.

Skill Catalog

The library contains 41 public skills organized by Rails development concern.

Use docs/reference/skill-catalog.md for the complete catalog and docs/reference/integration-matrix.md for skill chaining.

Quality And Evaluation

This repo uses two complementary evaluation layers.

Root evals/ is generated Tessl staging output and must stay untracked. tessl-evals/ is the tracked Tessl source. personal-evals/ is the tracked source for open custom-evaluator examples.

See docs/eval-provenance.md for the canonical eval ownership policy and docs/skill-optimization-guide.md for the baseline-vs-context optimization loop.

Install Selected Skills With GitHub CLI

Requires GitHub CLI v2.90.0+ with gh skill.

# 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
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 v5.1.5 --scope user

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

To target a specific agent host:

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:

gh skill update --dry-run
gh skill update --all
gh skill update --force --all
gh skill update --unpin

Pinning to a tag or commit SHA gives you reproducible installs. Provenance metadata is written into each installed SKILL.md frontmatter.

Documentation Map

Contributing

When contributing skills, workflows, docs, or MCP behavior:

• Keep generated artifacts in English unless a user explicitly asks for another language.
• Preserve the tests-gate-implementation rule for every code-producing skill.
• Do not add tickets unless the user asks for ticket generation.
• Do not commit generated root evals/ output.
• Keep public docs consistent with tile.json, server.json, and the latest release tag.

Install With skills.sh

Requires skills.sh CLI.

# Add the library to your workspace
npx skills add igmarin/rails-agent-skills

Acknowledgments

Huge thanks to Mumo Carlos (@mumoc). His mentorship shaped many of the habits reflected here, especially the discipline around quality, clarity, and thoughtful use of tools.