Skill Forge

IRON LAW: Every line in a skill must justify its token cost. If it doesn't make the model's output better, more consistent, or more reliable — cut it.

What is a Skill

A skill is an "onboarding guide" for Claude — transforming it from a general-purpose agent into a specialized one with procedural knowledge, domain expertise, and bundled tools.

skill-name/

├── SKILL.md # Required: workflow + instructions (<500 lines)

├── scripts/ # Optional: deterministic, repeatable operations

├── references/ # Optional: loaded into context on demand

└── assets/ # Optional: used in output, never loaded into context

Default assumption: Claude is already very smart.

Only add what Claude doesn't already know. Challenge every paragraph: "Does this justify its token cost?"

Workflow

Copy this checklist and check off items as you complete them:

Skill Forge Progress:

- [ ] Step 1: Understand the Skill ⚠️ REQUIRED

- [ ] 1.1 Clarify purpose and concrete use cases

- [ ] 1.2 Collect 3+ concrete usage examples

- [ ] 1.3 Identify trigger scenarios and keywords

- [ ] Step 2: Plan Architecture

- [ ] 2.1 Identify reusable resources (scripts, references, assets)

- [ ] 2.2 Design progressive loading strategy

- [ ] 2.3 Design parameter system (if applicable)

- [ ] Step 3: Initialize ⛔ BLOCKING (skip if skill already exists)

- [ ] Run init_skill.py

- [ ] Step 4: Write Description

- [ ] Load references/description-guide.md

- [ ] Apply keyword bombing technique

- [ ] Step 5: Write SKILL.md Body

- [ ] 5.1 Set Iron Law

- [ ] 5.2 Design workflow checklist

- [ ] 5.3 Add confirmation gates

- [ ] 5.4 Add parameter system (if applicable)

- [ ] 5.5 Apply writing techniques

- [ ] 5.6 Add anti-patterns list

- [ ] 5.7 Add pre-delivery checklist

- [ ] Step 6: Build Resources

- [ ] 6.1 Implement and test scripts

- [ ] 6.2 Write reference files

- [ ] 6.3 Prepare assets

- [ ] Step 7: Review ⚠️ REQUIRED

- [ ] Run pre-delivery checklist (Step 9)

- [ ] Present summary to user for confirmation

- [ ] Step 8: Package

- [ ] Run package_skill.py

- [ ] Step 9: Iterate based on real usage

Step 1: Understand the Skill ⚠️ REQUIRED

Ask yourself:

What specific problem does this skill solve that Claude can't do well on its own?

What would a user literally type to trigger this skill?

What are 3-5 concrete usage examples with realistic inputs and expected outputs?

If unclear, ask the user (don't ask everything at once — start with the most critical):

"Can you give me 3 examples of how you'd use this skill?"

"What would you literally say to trigger it?"

"What does a good output look like?"

Do NOT proceed until you have at least 3 concrete examples.

Step 2: Plan Architecture

For each concrete example, ask:

What operations are deterministic and repeatable? →

scripts/

What domain knowledge does Claude need at specific steps? →

references/

What files are used in output but not in reasoning? →

assets/

Key constraints:

SKILL.md must stay under 500 lines — everything else goes to

references/

References organized by domain, one level of nesting only

Load references/architecture-guide.md for progressive loading patterns and organization strategies

Step 3: Initialize ⛔ BLOCKING

Skip if working on an existing skill. Otherwise run:

python3 scripts/init_skill.py

<

skill-name

>

--path

<

output-directory

>

The script creates a template with Iron Law placeholder, workflow checklist, and proper directory structure.

Step 4: Write Description

This is the most underestimated part of a skill. The description determines:

Whether the skill triggers automatically

Whether users find it by search

Load references/description-guide.md for the keyword bombing technique and good/bad examples.

Key rule: NEVER put "When to Use" info in the SKILL.md body. The body loads AFTER triggering — too late.

Step 5: Write SKILL.md Body

Load reference files as needed for each sub-step:

5.1 Set Iron Law

Ask: "What is the ONE mistake the model will most likely make with this skill?"

Write a rule that prevents it. Place it at the top of SKILL.md, right after the frontmatter.

→ Load references/writing-techniques.md for Iron Law patterns and red flag signals.

5.2 Design Workflow Checklist

Create a trackable checklist with:

⚠️ REQUIRED for steps that must not be skipped

⛔ BLOCKING for prerequisites

Sub-step nesting for complex steps

(conditional) for steps that depend on earlier choices

→ Load references/workflow-patterns.md for checklist patterns and examples.

5.3 Add Confirmation Gates

Force the model to stop and ask the user before:

Destructive operations (delete, overwrite, modify)

Generative operations with significant cost

Applying changes based on analysis

→ Load references/workflow-patterns.md for confirmation gate patterns.

5.4 Add Parameter System (if applicable)

If the skill benefits from flags like

--quick

,

--style

,

--regenerate N

:

→ Load references/parameter-system.md for $ARGUMENTS, flags, argument-hint, and partial execution patterns.

5.5 Apply Writing Techniques

Three techniques that dramatically improve output quality:

Question-style instructions

Give questions, not vague directives

Anti-pattern documentation

List what NOT to do

Iron Law + Red Flags

Prevent the model from taking shortcuts

→ Load references/writing-techniques.md for all three with examples.

5.6 Add Anti-Patterns List

Ask: "What would Claude's lazy default look like for this task?" Then explicitly forbid it.

→ Load references/writing-techniques.md for anti-pattern examples.

5.7 Add Pre-Delivery Checklist

Add concrete, verifiable checks. Each item must be specific enough that the model can check it by looking at the output. Not "ensure good quality" but "no placeholder text remaining (TODO, FIXME, xxx)."

→ Load references/output-patterns.md for checklist patterns and priority-based output.

Writing Principles

Concise

Only add what Claude doesn't already know

Imperative form

"Analyze the input" not "You should analyze the input"
Match freedom to fragility: Narrow bridge → specific guardrails; open field → many routes High freedom (text): multiple valid approaches Medium (pseudocode/params): preferred pattern, some variation OK Low (specific scripts): fragile operations, consistency critical Step 6: Build Resources Scripts Encapsulate deterministic, repeatable operations Scripts execute without loading into context — major token savings Test every script before packaging In SKILL.md, document only the command and arguments, not the source code References Organize by domain, not by type One level of nesting only Each file referenced from SKILL.md with clear "when to load" instructions Large files (>100 lines) should have a table of contents at the top Assets Templates, images, fonts used in output Not loaded into context, just referenced by path → Load references/architecture-guide.md for detailed patterns. Step 7: Review ⚠️ REQUIRED Present the skill summary to the user and confirm before packaging. Pre-Delivery Checklist Structure SKILL.md under 500 lines Frontmatter has name and description only (plus optional allowed-tools , license , metadata ) Description includes trigger keywords and usage scenarios No README.md, CHANGELOG.md, or other unnecessary files No example/placeholder files left from initialization Quality Has an Iron Law or core constraint at the top Has a trackable workflow checklist with ⚠️/⛔ markers Confirmation gates before destructive/generative operations Uses question-style instructions, not vague directives Lists anti-patterns (what NOT to do) References loaded progressively, not all upfront Resources Scripts tested and executable References organized by domain, one level deep Large references have table of contents Assets used in output, not loaded into context Anti-Patterns to Avoid Stuffing everything into one massive SKILL.md (>500 lines) Vague description like "A tool for X" No workflow — letting the model freestyle No confirmation gates — model runs unchecked to completion Vague instructions like "ensure good quality" instead of specific checks Including README.md, INSTALLATION_GUIDE.md, or other documentation files "When to Use" info in the body instead of the description field Step 8: Package python3 scripts/package_skill.py < path/to/skill-folder

[ output-directory ] Validates automatically before packaging. Fix errors and re-run. Step 9: Iterate After real usage: Notice where the model struggles or is inconsistent Identify which workflow step needs improvement Add more specific instructions, examples, or anti-patterns Re-test and re-package

skill-forge

安装