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.

Step 3: Initialize

scripts/init_skill.py <skill-name> --path <directory>

Creates SKILL.md template, example scripts/references/assets. Delete unneeded files.

Step 4: Edit

Order matters:

1. Create scripts/references/assets first
2. Test scripts actually work
3. Write SKILL.md last (it references the resources)

SKILL.md Structure

---
name: kebab-case-name
description: [See CSO Patterns below]
---

Body sections:

• Core principle / Iron Law
• When to Use / When NOT to Use
• Workflow with success criteria
• Anti-patterns
• Quick reference
• Integration with other skills

Naming

• Lowercase letters, numbers, hyphens only. Max 64 chars.
• Must match directory name exactly.
• Gerund or capability form preferred.

Good	Bad	Why
systematic-debugging	debug	Verb, not capability
workspace-fluency	utils	Generic, no information
test-driven-development	pdf-helper	"helper" is meaningless
desired-outcomes	my-skill	Doesn't describe purpose

CSO Patterns (Critical)

The description determines discovery. Pattern: [ACTION TYPE] + [SPECIFIC TRIGGER] + [METHOD/VALUE PREVIEW]

Best: MANDATORY gate with BEFORE condition

description: MANDATORY gate before writing any SKILL.md file. Invoke FIRST when building new skills - provides structure, naming, and quality checklist that MUST be validated before deployment.

Why: "MANDATORY gate" not optional, "before writing" timing, "FIRST" positioning, "MUST" imperative.

Good: Specific trigger with method preview

description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes - four-phase framework (root cause, pattern analysis, hypothesis testing, implementation) ensures understanding before solutions.

Why: specific trigger + timing gate + method preview + value statement.

Good: Natural phrase triggers

description: Coach on outcome quality. Triggers on 'check my outcomes', 'is this a good outcome', 'review my Todoist' when discussing strategic work.

Why: explicit phrases in quotes, context qualifier.

Good: Negative triggers to prevent over-triggering

description: Advanced data analysis for CSV files — statistical modelling, regression, clustering. Do NOT use for simple data exploration (use data-viz skill instead).

Why: "Do NOT use for..." in the description itself steers Claude away at trigger-decision time, before the body loads. Anti-patterns in the body come too late — by then, the skill is already loaded and consuming tokens.

When to add negative triggers:

• Skill overlaps with another skill's domain
• Skill triggers on common words that appear in unrelated requests
• Users report the skill loading when it shouldn't

Bad patterns to avoid:

Pattern	Problem	Fix
"Helps with..."	Vague, no trigger	Specific phrases in quotes
"Use when creating..."	Too generic	"MANDATORY gate before..."
No timing condition	Optional invocation	Add BEFORE/FIRST/MANDATORY
Generic actions	Claude "knows" without loading	Domain-specific phrases
Command doesn't name skill	Not discoverable	"Invoke the name skill"
Over-triggers on related topics	Loads when it shouldn't	Add "Do NOT use for..." in description

Run scripts/score_description.py to validate. See references/cso-guide.md for full guidance.

Step 5: Validate

# Automated lint (structure, naming, frontmatter)
scripts/lint_skill.py <skill-path>

# CSO score (description quality)
scripts/score_description.py <skill-path>

# Subagent test (discovery + workflow)
scripts/test_skill.py <skill-path>

All checks must pass before Step 6.

Step 6: Package (Optional)

scripts/package_skill.py <skill-path> [output-dir]

Creates .skill file (zip format) for distribution.

Quality Checklist

Structure

• SKILL.md under 500 lines
• Name matches directory exactly (kebab-case)
• Name is gerund/capability form
• Description is third-person ("Orchestrates", not "Use")
• Description includes trigger AND method AND timing
• Description ends with (user) tag for user-defined skills
• References one level deep from SKILL.md
• YAML frontmatter has name and description only

Content

• No time-sensitive information
• Consistent terminology throughout
• Concrete examples, not abstract rules
• Configuration values justified
• Error handling documented
• Dependencies explicitly listed
• Anti-patterns section present

Workflow

• Clear phases/steps with success criteria
• When to Use AND When NOT to Use sections
• Integration points with other skills explicit
• Verification/validation included
• Quick reference for common operations

Discovery

• BEFORE/MANDATORY/FIRST patterns used appropriately
• Trigger phrases are natural language in quotes
• Context qualifiers included (when appropriate)
• Method preview gives Claude enough to decide relevance
• If paired with command, command names the skill explicitly
• Negative triggers ("Do NOT use for...") added if skill overlaps with others

Skill Patterns

See references/skill-patterns.md for full taxonomy. Summary:

Type	Key Feature	Description Pattern
Process	Phases with gates	BEFORE condition
Fluency	Tool best practices	Specific trigger phrases
Coaching	Quality criteria	Natural language triggers
Gate	Checklist validation	MANDATORY language
Skill+CLI	Orchestrates CLI tool	BEFORE any cli command

Skill+CLI Pattern (Most Powerful)

When skill orchestrates a CLI tool. See references/skill-cli-pattern.md for full template.

# {skill-name}
Orchestrates {domain} using `{cli}` command.
## CLI Reference
## Workflows
## When Skill Extends CLI (coaching, quality criteria)
## Error Recovery

What High-Invocation Skills Share

1. BEFORE conditions in description
2. Specific trigger phrases in quotes
3. Method preview that's actionable
4. Clear anti-patterns that catch mistakes
5. Integration points that compose with other skills

What Low-Invocation Skills Suffer From

1. Generic "Use when..." descriptions
2. Vague propositions ("helps with", "guides", "assists")
3. Missing timing gates
4. Documenting what Claude already knows

Anti-Patterns

Discovery Failures

Anti-Pattern	Symptom	Fix
"Use when creating..."	Claude bypasses skill	"MANDATORY gate before..."
"Helps with..."	Never invoked	Specific trigger phrases
No timing gate	Optional invocation	Add BEFORE/FIRST
Generic actions	Claude "knows" without loading	Domain-specific phrases

Structure Failures

Anti-Pattern	Symptom	Fix
SKILL.md > 500 lines	Token bloat	Split into references/
Name doesn't match dir	Skill not found	Keep synchronized
Deeply nested refs	Discovery fails	One level deep max

Content Failures

Anti-Pattern	Symptom	Fix
Explaining known things	Wastes tokens	Domain-specific only
Magic constants	Unclear reasoning	Justify all values
Many options, no default	Analysis paralysis	Recommend one path

Quick Reference

Minimum Viable Skill

---
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
• references/skill-cli-pattern.md — Skill+CLI template
• references/skill-patterns.md — Pattern taxonomy with examples
• references/rationalization-table.md — Common excuses to block
• references/sharing-scan.md — Sharing triage guidelines
• references/dot-graphs.md — DOT graph syntax for workflow diagrams