Rails Agent Skills

A catalog of 28 Rails skills and 9 personas that teach agents how to test, implement, and review Rails work. Process skills (TDD gates, YARD, DDD, service objects) live in ruby-core-skills. Install both.

Write the test → run it → confirm it fails for the right reason → implement → confirm it passes

flowchart TB
  subgraph thisRepo[rails-agent-skills]
    atomics[28 atomics]
    personas[9 personas]
  end
  core[ruby-core-skills]
  thisRepo --> core

Also in the same ecosystem: hanakai-yaku, agnostic-planning-skills, agent-mcp-runtime, ruby-skill-bench.

Daily loop

flowchart LR
  A[Task] --> B[load-context]
  B --> C[plan-tests]
  C --> D[write-tests RED]
  D --> E[implement GREEN]
  E --> F[docs + review]
  F --> G[PR]

Name the persona when you want the whole chain: tdd, bug-fix, graphql, migration, background-job, engine, review, quality, setup.

See docs/persona-guide.md and docs/personas/.

Catalog

Area	Skills
Testing	`plan-tests`, `write-tests`, `test-service`
Quality	`code-review`, `security-check`, `review-architecture`, `apply-code-conventions`, `apply-stack-conventions`, `implement-authorization`, `refactor-code`
Engines	`create-engine`, `test-engine`, `document-engine`, `review-engine`, `release-engine`, `create-engine-installer`, `extract-engine`, `upgrade-engine`
Infrastructure	`review-migration`, `implement-background-job`, `seed-database`, `optimize-performance`, `version-api`, `implement-hotwire`
API	`generate-api-collection`, `implement-graphql`
Context	`load-context`, `setup-environment`

Core skills (install separately): triage-bug, respond-to-review, write-yard-docs, create-service-object, integrate-api-client, define-domain-language, model-domain, skill-router, and the process skills.

Full list: docs/reference/skill-catalog.md. Gaps: docs/reference/gaps.md.

Install

There is no root SKILL.md. Each folder under skills/ is its own skill, so the CLI can prompt for all or one.

# picker: all skills, or a subset
npx skills add igmarin/ruby-core-skills
npx skills add igmarin/rails-agent-skills

# all skills, skip prompts
npx skills add igmarin/ruby-core-skills --skill '*'
npx skills add igmarin/rails-agent-skills --skill '*'

# one skill
npx skills add igmarin/rails-agent-skills --skill load-context

Or with GitHub CLI v2.90.0+ (gh skill):

gh skill install igmarin/ruby-core-skills
gh skill install igmarin/rails-agent-skills
gh skill install igmarin/rails-agent-skills code-review --scope project

A PromptScript global-install warning from skills.sh is harmless. The skills still install for other hosts.

Docs

Need	Document
Host context	AGENTS.md
How to invoke a persona	docs/persona-guide.md
Skill layout	docs/architecture.md
Eval ownership	docs/eval-provenance.md

Contributing

Artifacts in English unless the user asks otherwise.
Keep the tests-gate rule on every code-producing skill.
description is when + triggers (≤ 600 chars). Procedure stays in the body.
Keep public docs in sync with directory.json.

Thanks to Mumo Carlos (@mumoc).