Rails Agent Skills

It is a curated library of public Rails agent skills and callable personas that teach AI tools how to test, implement, document, and review Rails work using production-minded conventions. This repository acts as a pure Domain Knowledge Registry and asset catalog of specialized Rails & Ruby AI Skills/Personas, consumable by external MCP or CLI runtimes.

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 personas, so agents do not just produce plausible Rails code. They follow a repeatable engineering process.

Part of the AI Skill Ecosystem

This repo is one of 6 in a composable AI skill ecosystem:

See the Ecosystem Overview for the full architecture.

This repo depends on ruby-core-skills. See Migration Guide.

Supported agent environments

Official distribution

What are Agent Skills?

Agent Skills are a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows. At its core, a skill is a folder containing a SKILL.md file. This file includes metadata (name and description, at minimum) and instructions that tell an agent how to perform a specific task.

This repository follows the Agent Skills standard, meaning you can install the entire catalog of Rails skills atomically into any compatible agent (e.g., Cursor, Claude Code, Goose, OpenCode, Gemini CLI) using:

npx skills add igmarin/rails-agent-skills

Note: You may see a harmless warning at the end of the install: ✗ rails-agent-skills → PromptScript: PromptScript does not support global skill installation This is a known bug in the skills.sh CLI where the PromptScript agent is incorrectly included in the global install target list despite not supporting it. All 37 skills install successfully to every other supported agent — the warning can be safely ignored.

Who This Is For

What Is In The Repository

Core Dependency: This repository depends on igmarin/ruby-core-skills for 15 foundational Ruby skills (DDD, Ruby patterns, process skills, code quality, orchestration). Install both repositories for the complete skill set.

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.

Daily Workflow

Depending on your environment, 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).

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 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/persona-guide.md and docs/personas/ for the full process guide containing detailed Mermaid diagrams of each phase.

Skill Catalog

The library contains 28 public Rails-specific skills organized by development concern, plus 15 core Ruby skills available from the dependency igmarin/ruby-core-skills.

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

Quality And Evaluation

Skill quality is validated through full-context scenarios in personal-evals/, intended for the upcoming ruby-skill-bench gem. Those examples load SKILL.md plus companion resources (bundled as XML) so skills and personas can be scored with realistic context.

See docs/eval-provenance.md for the canonical eval ownership policy.

Install Selected Skills With GitHub CLI

Requires GitHub CLI v2.90.0+ with gh skill.

# Install the core dependency first for complete functionality
gh skill install igmarin/ruby-core-skills

# 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 v6.0.0 --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, personas, or docs:

• 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.
• Keep public docs consistent with directory.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.