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
markdown
--- 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-controlwhere relevant - •_INDEX.md: register new skills in the routing table
- •CLAUDE.md.example: add to skills table if user-invocable
- •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