Skill Template

rails-agent-skills/
└── your-skill-name/
    ├── SKILL.md          # Required: main skill file
    ├── reference.md      # Optional: supplementary reference material
    └── examples.md       # Optional: example outputs or edge cases

---
name: your-skill-name
description: >
  [Concise paragraph (1-3 sentences). First sentence states primary purpose.
  Focus on trigger words and outcomes for LLM discovery].
---

# Your Skill Title

Use this skill when [brief one-line trigger].

**Core principle:** [One sentence that captures the skill's philosophy]

## Quick Reference

| Aspect | Rule |
|--------|------|
| Key concept 1 | Brief rule |
| Key concept 2 | Brief rule |
| Key concept 3 | Brief rule |

## HARD-GATE

<!-- Only include if the skill has non-negotiable rules -->

\```
DO NOT [forbidden action that must never be skipped].
ALWAYS [required action that must always happen].
\```

## Checkpoints

<!-- Only include if the skill introduces a pause-and-confirm step (not a hard blocker).
     Checkpoints differ from HARD-GATEs: they pause for collaboration, not to enforce a rule. -->

### [Checkpoint Name]

1. Present: [what to show the user]
2. Ask: [specific questions to confirm before proceeding]
3. Confirm: [what approval looks like — only proceed once confirmed]

## When to Use

- Trigger condition 1
- Trigger condition 2
- **Next step:** [What to suggest after this skill completes]

## Process

1. **Step name:** Description of what to do.
2. **Step name:** Description of what to do.
3. **Step name:** Description of what to do.
4. **Verify:** Run verification and confirm results with evidence.

## Examples

**Good:**

\```ruby
# Good example with explanation
\```

**Bad:**

\```ruby
# Bad example with explanation of why it's bad
\```

## Common Mistakes

| Mistake | Reality |
|---------|---------|
| "Common excuse or bad practice" | Why it's wrong and what to do instead |
| "Another common mistake" | The correct approach |

## Red Flags

- Signal that the skill is being violated
- Another warning sign
- Pattern that indicates a problem

## Integration

| Skill | When to chain |
|-------|---------------|
| **related-skill-1** | When [condition triggers the related skill] |
| **related-skill-2** | When [condition triggers the related skill] |