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:
text
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:
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:
bash
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
Reader
What you get
Rails developers
Agent instructions for common Rails work: tests, services, APIs, GraphQL, migrations, jobs, Hotwire, engines, security, and review.
Team leads
A repeatable workflow that makes AI-assisted work easier to review because tests, docs, and self-review are part of the process.
Junior developers
Step-by-step Rails workflow guidance that explains what to do next instead of dumping generic code.
Senior developers
Opinionated guardrails for TDD, architecture, review, DDD, engines, performance, and production-safe changes.
Recruiters and evaluators
A concrete example of AI tooling designed around engineering discipline, validation, and distribution.
What Is In The Repository
Area
Purpose
skills/
28 public atomic skills for Rails-specific development. Each skill has a SKILL.md entry point with task-specific instructions.
skills/personas/
9 callable personas that chain skills into full development loops (tdd, quality, review, setup, engine, bug-fix, graphql, migration, background-job).
docs/
Public documentation, architecture, persona guides, skill catalog, and evaluation policy.
personal-evals/
Open examples for the upcoming ruby-skill-bench full-context evaluator.
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 library contains 28 public Rails-specific skills organized by development concern, plus 15 core Ruby skills available from the dependency igmarin/ruby-core-skills.
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.
# 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:
bash
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
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.
