Rails Agent Skills

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

It is a curated library of 42 public Rails agent skills and 5 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

The recommended way to use this library is through the MCP server. MCP keeps the agent context small: docs and workflows are exposed as resources, 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.

Daily Workflow

Most Rails work should start with the 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:

triage-bug -> plan-tests -> failing reproduction spec -> minimal fix -> code-review

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.

Skill Catalog

The library contains 42 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.

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.