Rails Agent Skills

Recipes That Teach AI
How to Build Rails

A curated library of 28 executable skill files that turn AI coding assistants into disciplined Rails developers who follow conventions, write tests first, and ship production-quality code.

28

atomic skills

9

orchestrating agents

6

skill categories

15

shared core skills

The Problem With
Asking AI for Rails Help

A vanilla AI assistant gives you generic, context-free answers. It doesn't know your project conventions. It doesn't enforce TDD. It doesn't know whether you're using Solid Queue or Sidekiq, Pundit or CanCanCan, Hotwire or a JS framework.

The result: plausible-looking code that doesn't fit your stack, inconsistent patterns across sessions, and no discipline around testing.

What vanilla AI gives you

✗ Generic advice that ignores your Rails version

✗ No TDD discipline — implementation before tests

✗ Inconsistent patterns across sessions

✗ No knowledge of your project's conventions

✓ With skills: executable instructions that enforce workflow

Skills Are Recipes.
Agents Are Chefs.

A skill (SKILL.md) is a detailed recipe that tells an AI how to perform one specific task — review a migration, write a service spec, create a Rails engine. It includes hard rules, step-by-step instructions, and a checklist for output quality.

An agent is a higher-level orchestrator that chains multiple skills into a complete development loop. The TDD agent, for example, calls load-context → plan-tests → write-tests → implement → code-review → PR.

Skills are building blocks; agents are the unit of value.

Skills Organized by
What They Do

Each skill lives in skills/<category>/<name>/SKILL.md. Supporting files (examples, patterns, checklists) load on demand — you read only what you need.

🔀 Testing

write-tests · test-service · plan-tests

✨ Code Quality

code-review · review-architecture · security-check · apply-conventions · implement-authorization · refactor-code

🌍 Engines

create · test · review · release · document · install · extract · upgrade

⚙️ Infrastructure

review-migration · implement-background-job · seed-database · optimize-performance · version-api · implement-hotwire

📡 API

generate-api-collection · implement-graphql

📖 Context

load-context (read before coding) · setup-environment

Plus 15 shared skills from ruby-core-skills for YARD docs, DDD, service objects, process discipline, and more.

The Non-Negotiable
TDD Gate

Every skill that produces code enforces a HARD-GATE: you cannot write implementation until a failing test proves the feature is missing. This is not a suggestion — it is encoded in every skill file.

1

Write Test

Start with the spec

2

Run It

Execute the test suite

3

Verify Failure

Fails for the right reason

4

Implement

Make it pass

      # The rule from AGENTS.md:

      Write test # spec exists

      → Run test     # spec has been executed

      → Verify FAILS  # fails because feature is missing, not a syntax error

      → Implement     # only now can you write application code

      → Verify PASSES # green bar

If you wrote implementation code before the test, delete it and start over.

Agents That
Orchestrate the Work

Agents live in agents/<name>/SKILL.md. Each one sequences multiple atomic skills into a complete development loop. You invoke the agent; it chains the skills.

TDD

load-context → plan-tests → write-tests → implement → docs → review → PR

Review

code-review → deep dive (security/architecture) → respond

Quality

conventions → refactor → YARD docs

Engine

create → test → document → review → release

Bug Fix

triage → reproduce test → fix → verify → regression check

GraphQL

domain model → implement-graphql → TDD loop → security

Migration

plan → test → staging deploy → production

Background Job

design → TDD impl → retry config → monitoring

Setup

load-context → setup-environment → CI/CD

Example: The
TDD Feature Loop

This is the recommended daily workflow. Starting from an idea, the TDD agent walks through every step — no shortcuts.

        # Daily workflow from AGENTS.md:

        skills/context/load-context

        → agents/tdd # orchestrates the loop below

        → skills/testing/plan-tests

        → skills/testing/write-tests

        → [GATE: test fails for right reason]

        → implement

        → [GATE: linters + suite pass]

        → write-yard-docs

        → skills/code-quality/code-review

        → PR

What a Skill File
Looks Like

Every skill follows the same template. The structure makes rules impossible to ignore and instructions easy to follow.

      # SKILL.md — every skill follows this structure

      ## YAML frontmatter

      name: write-tests

      description: Write RSpec tests for Ruby on Rails...

      metadata.version: 1.0.0

      ## Quick Reference

      Compact rules table in 5-7 rows

      ## HARD-GATE

      Non-negotiable rules # Tests gate implementation

      ## Core Process

      Step-by-step instructions

      ## Output Quality

      Graded checklist of requirements

      ## Extended Resources (progressive)

      Examples, pitfalls, heuristics — load on demand

      ## Integration

      Which skill to chain next

📝 YAML frontmatter with name + description

⚠️ HARD-GATE in a code block

📋 Graded output checklist

🔗 Integration table for chaining

Context Engineering
With lean-ctx

This repository uses lean-ctx, a context engineering layer that replaces file reads with compressed, cached alternatives. The goal: deliver the information an AI needs while using 50-80% fewer tokens.

PREFER ctx_read(path, mode)

10 compression modes (map, signatures, aggressive, entropy…). Cached re-reads ~13 tokens.

PREFER ctx_search(pattern)

Compact regex search results. Token-efficient over grep.

PREFER ctx_shell(command)

Pattern compression for git, npm, and common output.

AVOID ctx_read(full)

Never use full for files you won't edit. Use map or signatures.

Part of a
Six-Repo Ecosystem

This repo is one piece of a composable skill ecosystem. Skills resolve dependencies automatically across repos via the agent-mcp-runtime.

What To Do
Next

Whether you are an AI assistant or a developer reading this repository, the workflow is the same.

1. Load skills/context/load-context

→

2. Load agents/tdd

→

3. Follow the TDD gate

→

4. Ship your PR

Install via npx skills add igmarin/rails-agent-skills or gh skill install igmarin/rails-agent-skills

Recipes That Teach AI How to Build Rails

The Problem With Asking AI for Rails Help

Skills Are Recipes. Agents Are Chefs.

Skills Organized by What They Do

The Non-Negotiable TDD Gate

Agents That Orchestrate the Work

Example: The TDD Feature Loop

What a Skill File Looks Like

Context Engineering With lean-ctx

Part of a Six-Repo Ecosystem

What To Do Next