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 or editing 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

Boundaries

• One-off instructions belong in CLAUDE.md, not a skill
• Simple tool usage Claude already knows
• Tasks that don't repeat across sessions

Why This Skill Exists

Even when the task seems simple, forge adds value you can't get from training alone:

• CSO scoring catches description patterns that look fine but won't trigger discovery
• Register checks ensure skills create a calm, productive emotional baseline
• Lint validation catches structural issues (naming, frontmatter, section depth) before they cause silent failures
• Small description edits are exactly where CSO scoring matters most — a word change can shift discovery rates

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
${CLAUDE_SKILL_DIR}/scripts/lint_skill.py /path/to/skill

# 4. Score description quality (CSO)
${CLAUDE_SKILL_DIR}/scripts/score_description.py /path/to/skill

# 5. Test with subagent (optional but recommended)
${CLAUDE_SKILL_DIR}/scripts/test_skill.py /path/to/skill

# 6. Package for distribution (optional)
${CLAUDE_SKILL_DIR}/scripts/package_skill.py /path/to/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:

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.

CSO Patterns

The description determines discovery. Pattern: [ACTION VERB] + [LIFECYCLE CONTEXT] + [METHOD/VALUE PREVIEW]

Best: Clear lifecycle positioning with specific context

description: Orchestrates skill development — required before writing or editing any SKILL.md file. Unified 6-step workflow with automated validation, CSO scoring, and subagent testing.

Why: third-person verb, "required before" positioning, specific context ("any SKILL.md file"), method preview.

Good: Specific trigger with method preview

description: Guides systematic debugging before proposing fixes. 4-phase framework (root cause, pattern analysis, hypothesis testing, implementation) ensures understanding before solutions. Triggers on 'test failing', 'unexpected behavior', 'debug this'.

Why: specific trigger + lifecycle positioning + method preview + value statement.

Good: Natural phrase triggers

description: Coaches 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: Scope boundaries to prevent over-triggering

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

Why: clear scope boundary in description steers Claude before body loads.

When to add scope boundaries:

• 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

Patterns to improve:

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 should 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
• Rules carry their why — mechanism prose transfers where the rule's letter runs out: far-transfer 15/15 with whys vs 8/15 bare rules, p=0.003 (banc guidance A/B, 2026-08-03)
• Reference skills end with a non-exhaustiveness license ("covers the common cases, not every case; reason from the whys above") — a partial spec anchored flagship models to its letter, 0/5 on an uncovered case; that one sentence restored 5/5 with zero over-extension (banc fiat A/B, 2026-08-04)
• Claims about a pinned environment carry per-claim provenance — verification state plus the exact command to re-check, [not smoke-tested at 0.19.0] style, so a reader knows which claims to re-verify before relying on them (DAAF svy audit, 2026-08-12)
• Content curates the pinned environment and the data, never a famous library — training weights already carry the library (a ~25k-token polars skill measured ~95% already in Gen-5 weights, while a survey skill documenting live-verified installed-version behaviour supplied what no training run can — DAAF audit, 2026-08-12)

Both rows measured on private estate evals: banc guidance/results.md + fiat/results.md; narrative write-up in model-minds experiment-guidance-style-ab.md.

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
• Recipes don't silently narrow attention — enumerated read-lists are marked as floors ("sweep everything; these are where the gold usually sits") or preceded by an explicit sweep step; a skill's map becomes the model's blind spots (skilled runs read 0% of an unlisted inbox that bare runs read 100% — accomplis coaching eval, 2026-08-05; register-principles P9)

Discovery

• Lifecycle positioning (before/first/required) 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
• Scope boundaries added if skill overlaps with others

Register

• Opens with what good work looks like, not what to avoid
• ALL CAPS used sparingly (abbreviations fine, emphatic caps minimal)
• Prohibitions balanced with positive specifications
• Constraints framed as craft standards, not threats

Skill Patterns

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

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. Clear lifecycle positioning — "before", "first", "required"
2. Specific trigger phrases in quotes
3. Method preview that's actionable
4. Clear pitfall documentation that catches mistakes
5. Integration points that compose with other skills
6. Calm, craft-oriented register — constraints as quality standards

What Low-Invocation Skills Suffer From

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

Common Mistakes

Discovery

Structure

Content

Quick Reference

Minimum Viable Skill

---
name: kebab-case-name
description: [ACTION VERB] + [LIFECYCLE CONTEXT] + [METHOD/VALUE]. Triggers on 'phrase1', 'phrase2'. (user)
---

# Skill Title

[What good work looks like — the core principle]

## When to Use
[Specific triggers with examples]

## Boundaries
[What this skill is not for]

## Workflow
[Steps with success criteria]

## Common Mistakes
[Pitfalls and better alternatives]

Files to Include

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. The username/company/name categories need your terms: they load from ~/.claude/sharing-scan.json (automatic when present) or --config — without one those categories are inert, and the scanner says so on stderr. 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 — Why this skill exists even when the task seems simple
• references/register-principles.md — Emotional register guidelines for instructional text
• references/sharing-scan.md — Sharing triage guidelines
• references/dot-graphs.md — DOT graph syntax for workflow diagrams
• references/cowork-environment.md — Desktop Cowork environment, for skills that must run there
• references/cowork-cloud.md — cloud (remote) Cowork environment — different surface again: no hooks, no plugin CLIs