Skill Forge

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

## Quality Notes (if multi-step workflow)

- Take your time with each step
- Quality over speed
- Do not skip validation

## [Core Instructions]

### Step 1: ...
[Specific, actionable instructions with examples]

### Step 2: ...
[Clear expected output]

## 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; be ruthless
• No em dashes: use commas, colons, semicolons, or parentheses

Quality Notes

• Read each skill file thoroughly before scoring
• Compare against existing high-quality skills (rails, source-control, clickup)
• Propose concrete diffs, not vague suggestions