Orchestrates ALL skill development — MANDATORY gate BEFORE writing or editing any SKILL.md file. Invoke FIRST when building, validating, improving, or refactoring skills. Supersedes skill-creator. Unified 6-step workflow with automated validation, CSO scoring, and subagent testing. Triggers on 'create skill', 'new skill', 'validate skill', 'check skill quality', 'improve skill discovery', 'check this skill', 'write SKILL.md', 'edit SKILL.md', 'update skill description', 'can I share this', 'scan for sharing'. (user)
Orchestrates ALL skill development — MANDATORY gate BEFORE writing or editing any SKILL.md file. Invoke FIRST when building, validating, improving, or refactoring skills. Supersedes skill-creator. Unified 6-step workflow with automated validation, CSO scoring, and subagent testing. Triggers on 'create skill', 'new skill', 'validate skill', 'check skill quality', 'improve skill discovery', 'check this skill', 'write SKILL.md', 'edit SKILL.md', 'update skill description', 'can I share this', 'scan for sharing'. (user)
Skill Forge
Unified skill development toolkit. Supersedes skill-creator — combines its creation process with quality validation, description optimization, and testing.
Iron Law: Skills must be discovered to be useful. The description is everything.
When to Use
BEFORE writing any SKILL.md file
When creating a new skill from scratch
When improving an existing skill's discovery rate
When validating skill quality before deployment
When scanning a skill/repo before sharing publicly
When NOT to Use
One-off instructions (put in CLAUDE.md instead)
Simple tool usage Claude already knows
Tasks that don't repeat across sessions
Rationalizations to Block
Claude frequently skips this skill by reasoning:
"I already know how to create skills" — You know the generic pattern. This skill adds CSO scoring, lint, and project-specific conventions you don't have in training.
"skill-creator covers this" — skill-forge supersedes skill-creator. Use forge, not creator.
"I'll validate later" — Validation after writing is expensive rework. Forge-first, always.
"This is just a small edit to an existing skill" — Small edits to descriptions are exactly where CSO scoring matters most.
Quick Start
# 1. Initialize new skill
scripts/init_skill.py my-skill --path ~/.claude/skills
# 2. Edit SKILL.md (see Workflow below)# 3. Lint for structure issues
scripts/lint_skill.py ~/.claude/skills/my-skill
# 4. Score description quality (CSO)
scripts/score_description.py ~/.claude/skills/my-skill
# 5. Test with subagent (optional but recommended)
scripts/test_skill.py ~/.claude/skills/my-skill
# 6. Package for distribution (optional)
scripts/package_skill.py ~/.claude/skills/my-skill
Workflow: 6-Step Process
Step 1: Understand with Concrete Examples
Goal: Know exactly how the skill will be used before building.
Questions to answer:
"What would a user say that should trigger this skill?"
"Can you give examples of how this skill would be used?"
"What should happen after the skill triggers?"
Exit criterion: Clear list of trigger phrases and expected behaviors.
Step 2: Plan Reusable Contents
Analyze each example to identify:
Content Type
When to Include
Example
scripts/
Same code rewritten repeatedly
rotate_pdf.py
references/
Documentation Claude should reference
schema.md
assets/
Files used in output (not loaded)
template.pptx
Exit criterion: List of scripts/references/assets to create.
---
name: kebab-case-name
description: [TIMING] + [TRIGGER] + [METHOD/VALUE]. Triggers on 'phrase1', 'phrase2'. (user)
---# Skill Title
[Core principle]
## When to Use
[Specific triggers with examples]
## When NOT to Use
[Clear boundaries]
## Workflow
[Steps with success criteria]
## Anti-Patterns
[What to avoid with fixes]
Files to Include
File
Purpose
When Required
SKILL.md
Core instructions
Always
references/*.md
Detailed guides
When SKILL.md > 500 lines
scripts/*.py
Utility scripts
When deterministic code needed
assets/*
Output templates
When Claude uses files in output
Before Sharing
Run the sharing scanner:
scripts/scan.py <skill-path>
scripts/scan.py --risk high <skill-path> # High-risk only
Detects: emails, paths with usernames, secrets, company terms.
See references/sharing-scan.md for triage guidelines.
Integration
Anthropic scripts (symlinked from skill-creator):
init_skill.py — generate template
package_skill.py — create .skill file
Forge scripts:
lint_skill.py — automated structure validation
score_description.py — CSO quality scoring
test_skill.py — subagent pressure testing
scan.py — PII/secrets scanner for sharing
render_graphs.py — DOT workflow diagrams to SVG
References
references/cso-guide.md — Claude Search Optimization principles
