rails-agent-skills-marketplace

Rails Agent Skills

Rails Agent Skills is a curated library of AI agent skills for Ruby on Rails development. Skills encode specialized knowledge, conventions, and workflow patterns so assistants deliver higher-quality code.

• Repository / install path: rails-agent-skills (docs/implementation-guide.md)
• Bootstrap discovery skill: rails-agent-skills (session hook loads rails-agent-skills/SKILL.md where applicable)
• Workflows: docs/workflow-guide.md — Skill structure: docs/architecture.md
• How to invoke a skill or workflow: docs/workflow-guide.md#how-to-invoke

Methodology

This skill library is built on core principles that shape how every skill operates. For detailed guidance on skill design, read the official Skill Design Principles.

1. Tests Gate Implementation

The central methodology of this project. Tests are not a phase that happens "after" or "alongside" development — they are a gate that must be passed before any implementation code can be written.

PRD → Tasks → [GATE] → Implementation → YARD → Docs → Code review → PR
                 │
                 ├── 1. Test EXISTS (written and saved)
                 ├── 2. Test has been RUN
                 └── 3. Test FAILS for the correct reason
                        (feature missing, not a typo)

        Only after all 3 conditions are met
        can implementation code be written.

After tests pass: document public Ruby API (YARD), update README/diagrams/
related docs, then self-review (rails-code-review) before opening the PR.
Task lists from generate-tasks include these steps explicitly.

This applies to every skill that produces code: service objects, background jobs, API integrations, engine components, refactoring, and bug fixes. Every implementation skill in this library includes a HARD-GATE: Tests Gate Implementation section enforcing this discipline.

Why this matters:

• A test that passes immediately proves nothing — you don't know if it tests the right thing
• A test you never saw fail could be testing existing behavior, not the new feature
• Implementation code written before the test is biased by what you built, not what's required

Generated output: All generated artifacts (documentation, YARD comments, Postman collections, examples) must be in English unless the user explicitly requests another language. This is reflected in the skill template and in yard-documentation and api-rest-collection.

2. Workflow Chaining

Skills are designed to be used in sequence, not in isolation. Each skill's Integration table points to the next skill in the chain. The primary daily workflow is:

rails-tdd-slices → rspec-best-practices (write failing test)
    ↓
[CHECKPOINT: Test Design Review — confirm boundary, behavior, edge cases]
    ↓
[CHECKPOINT: Implementation Proposal — confirm approach before coding]
    ↓
Implement (minimal code to pass test) → Refactor
    ↓
[GATE: Linters + Full Test Suite]
    ↓
yard-documentation → Update docs
    ↓
rails-code-review (self-review) → rails-review-response (on feedback)
    ↓
PR

See docs/workflow-guide.md for the full TDD Feature Loop and all workflow diagrams.

Note: ticket-planning is an optional step. The assistant should not push for Jira ticket generation unless the user asks explicitly (e.g. "turn this into Jira tickets") or the context clearly indicates work should be mapped to a Jira board/sprint.

3. Rails-First Pattern Reuse

This library intentionally reuses proven patterns from broader agent-skill libraries, but translates them into a Rails-first workflow instead of copying generic frontend-oriented skills one-to-one.

Reused pattern	Rails-first destination in this repo
PRD interview + scope control	create-prd
Planning from requirements	generate-tasks
TDD loop and smallest safe slice	rspec-best-practices + rails-tdd-slices
Bug investigation to reproducible test	rails-bug-triage
Domain language and context design	ddd-ubiquitous-language + ddd-boundaries-review + ddd-rails-modeling
Skill authoring conventions	docs/skill-template.md

The rule of thumb is: reuse patterns, not names. If a broader skill maps cleanly to Rails/RSpec/YARD workflows, absorb the pattern into the existing chain. Create a new skill only when there is a real Rails-specific workflow gap.

How to Build a Feature (Your Daily Workflow)

For a practical guide on how to talk to the AI and effectively invoke these workflows, please see our How to Invoke a Workflow Guide.