| 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>
- Gather context: ask what the skill does, when to use it, what tools it needs
- Generate SKILL.md following the template below
- Validate against the checklist
- Present for approval before writing
Review: /skill-forge review <name> or /skill-forge review all
- Read the skill's SKILL.md
- Score against the checklist (0-100)
- Report findings grouped by severity (critical, major, minor)
- 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
