Skill Forge

Unified skill development toolkit. Combines Anthropic's creation process (skill-creator) 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

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:

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 (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.

Bad patterns to avoid:

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

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. •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

Structure Failures

Content Failures

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

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