ABOUTME: Skill creation and improvement based on Anthropic's skills guide

ABOUTME: Validates structure, descriptions, triggers, progressive disclosure, and conventions

Skill Forge

Create new skills or audit/improve existing ones. Encodes Anthropic's official guide + our conventions.

Modes

Create: /skill-forge create <name>

1. Gather context: ask what the skill does, when to use it, what tools it needs
2. Generate SKILL.md following the template below
3. Validate against the checklist
4. Present for approval before writing

Review: /skill-forge review <name> or /skill-forge review all

1. Read the skill's SKILL.md
2. Score against the checklist (0-100)
3. Report findings grouped by severity (critical, major, minor)
4. Propose fixes as diffs

Skill Template

---
name: kebab-case-name
description: "[What it does]. Use when [trigger conditions]. [Key capabilities]. Not for [negative triggers if overlapping skills exist]."
compatibility: "Only if external deps needed"
---

# ABOUTME: [One-line what]
# ABOUTME: [One-line key capabilities]

# Skill Title

## [Core Instructions]

[Outcomes, constraints with their reasons, and how to verify the result. Numbered steps only where order truly matters; exact commands only for fragile operations.]

## Common Issues

| Issue | Solution |
|-------|----------|

## References (if >150 lines needed)

For detailed patterns, consult `references/<topic>.md`

Validation Checklist

Structure (critical)

Description (critical)

Test: Ask yourself "When would you use the [name] skill?" If the description doesn't answer clearly, it needs work.

Content (major)

Optional Fields (minor)

Scoring

Start at 100, subtract per finding:

Our Conventions (beyond Anthropic's guide)

• ABOUTME headers: 2-line comment block after frontmatter (what + capabilities)
• Cross-references: link to _AST_GREP.md, _PATTERNS.md, source-control where relevant
• _INDEX.md: register new skills in the routing table
• CLAUDE.md: nothing to add. The harness injects every skill's name and description, so the file carries no skill catalog; discovery lives in your description: field, which is why it must state when to use the skill and when not to
• Token budget: every word in SKILL.md costs context on every trigger; cut what the model already knows, keep what only the author knows (reasons, environment facts, quality bar)
• No em dashes: use commas, colons, semicolons, or parentheses

Quality Notes

• Compare against existing high-quality skills (rails, source-control)
• Propose concrete diffs, not vague suggestions