skill-forge

name	skill-forge
description	Create new skills or review and improve existing ones. Use when user says create skill, new skill, improve skill, review skill, audit skills, or skill quality.

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)

Check	Rule
Folder name	kebab-case, no spaces/capitals/underscores
File name	Exactly SKILL.md (case-sensitive)
Frontmatter	--- delimiters, name + description required
ABOUTME	Two lines after frontmatter: what + capabilities
No README.md	All docs in SKILL.md or references/

Description (critical)

Check	Rule
Formula	[What] + [When/triggers] + [Capabilities]
Trigger phrases	Include words users actually say
Negative triggers	"Not for X" if overlapping skills exist
Length	Under 1024 characters
No XML tags	No < or > in description
Quotes	Wrapped in double quotes

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

Content (major)

Check	Rule
Specific	Actionable commands, not "validate the data"
Examples	Concrete code/commands, not abstract descriptions
Error handling	Common issues table for workflow skills
Progressive disclosure	SKILL.md <150 lines core; detailed content in references/
Quality notes	Multi-step workflows get anti-laziness section

Optional Fields (minor)

Field	When to use
compatibility	External deps (app, CLI, API key, MCP server)
allowed-tools	Restrict to specific tools
tools	Simpler tool restriction
metadata	Distribution (author, version, mcp-server)

---

Scoring

Start at 100, subtract per finding:

Severity	Deduction	Examples
Critical	-25	No frontmatter, no description, wrong file name
Major	-10	No trigger phrases, vague instructions, no ABOUTME
Minor	-3	Missing compatibility, no error handling, no examples

Score	Verdict
90+	Ship it
70-89	Needs fixes
<70	Rewrite

---

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