Skill Forge

Skill Forge

Produce Agent Skills that load correctly and trigger reliably. A skill is a folder whose SKILL.md holds YAML frontmatter (name, description) plus a Markdown body of instructions, optionally supported by scripts/, references/, and assets/.

What good output looks like

• name matches the folder name exactly, kebab-case, ≤64 characters.
• description states what the skill does and when to use it, in third person, ≤1024 characters.
• Body stays under 500 lines; depth lives in references/ and is loaded only when needed.
• Any script the body tells the agent to run actually exists and runs from the skill root.
• The folder passes scripts/validate_skill.py with zero errors before it is delivered.

Intake: resolve these before scaffolding

Ask the user only for what is missing, then proceed. Do not scaffold a skill around a guess.

1. Job to be done — the one task this skill owns, in a single sentence.
2. Triggers — the words a user would actually type ("review this PR", "make a quote").
3. Inputs and outputs — file types, formats, or tools involved.
4. Determinism — must any step be executed by code rather than by the model (parsing, math, file conversion)? If yes, that step becomes a script.
5. Deliverable form — folder only, or a packaged .skill archive.

If the user has no strong opinion, choose sensible defaults, say so in one line, and build.

Workflow

1. Scaffold

python3 scripts/init_skill.py <skill-name> --path <parent-dir> \
  --description "What it does. Use when ..." \
  --with-scripts --with-references --with-assets

Creates <parent-dir>/<skill-name>/ with a SKILL.md stub and only the subfolders requested. Add --force to overwrite an existing skill directory.

2. Write the description first

The description is the routing signal — it is the only part loaded at startup, so a weak description means the skill never activates. Formula:

<What it does, third person> + Use when <triggers, symptoms, user phrasings>

Rules: third person, no "I"/"You can"; include the literal words users say; no XML tags.

3. Write the body

Order that works: short overview → when to use / when not to use → numbered workflow → concrete examples → error handling and safety boundaries. Write instructions as imperatives addressed to the agent ("Read the file, then…"), not as prose about the skill.

Keep it lean:

• Body under 500 lines. Exceeding that is a signal to move detail into references/.
• One level of file references (references/tables.md), never nested chains.
• Reference filenames describe content: form_validation_rules.md, not doc2.md.
• State what to do when a step fails; silence forces the agent to improvise.

4. Move deterministic work into scripts

Anything with exact answers — parsing, arithmetic, format conversion, API calls — belongs in scripts/ and gets run, not recalled. Scripts must:

• accept paths as arguments and run from the skill root,
• print machine-readable output (JSON or CSV) to stdout, diagnostics to stderr,
• exit non-zero on failure, and never require network access unless stated in compatibility.

5. Validate, then package

python3 scripts/validate_skill.py <skill-dir> --strict
python3 scripts/package_skill.py <skill-dir> --out <dist-dir>

Never ship a skill with validation errors. Warnings should be fixed or consciously accepted.

Frontmatter reference

Directory layout

<skill-name>/
├── SKILL.md          # required
├── scripts/          # executable helpers the model runs
├── references/       # depth loaded on demand (specs, tables, long procedures)
├── assets/           # templates and files copied into output
└── tests/            # checks for the skill's own scripts (optional)

Quality gate

Before reporting a skill as done, confirm all of these:

• Folder name, name, and description all agree; description contains real trigger phrases.
• Every scaffold placeholder is replaced with real content (the validator flags leftover ones).
• Every path mentioned in the body exists in the bundle.
• Each script was executed once on real or sample input and its output inspected.
• validate_skill.py --strict passes.
• If packaged: archive extracts to a folder whose name matches name.

Cost of a bad skill

• A vague description means the skill never fires; a greedy one hijacks unrelated tasks.
• A 900-line body burns context on every activation and buries the operative instruction.
• A script the model cannot run (missing dependency, wrong relative path) turns the skill into guesswork, which is worse than no skill.

Bundled resources

• scripts/init_skill.py — scaffold a new skill directory.
• scripts/validate_skill.py — check spec compliance; --strict promotes warnings to errors, --json for machine output.
• scripts/package_skill.py — validate and zip into a distributable archive.
• references/specification.md — the full SKILL.md spec, field rules, validation semantics.
• references/authoring-guide.md — description craft, body patterns, anti-patterns, testing method.
• assets/SKILL.template.md, assets/script.template.py, assets/reference.template.md — starting points.
• tests/run_tests.sh — smoke tests for the three scripts.

Example: end-to-end

User: "Make a skill that turns messy meeting notes into a structured action list."

1. Intake — job: notes → action items; triggers: "turn these notes into actions", "extract action items"; output: Markdown table; deterministic step: none required.
2. python3 scripts/init_skill.py meeting-actions --path ~/.claude/skills --description "Converts raw meeting notes into a structured action list with owners and due dates. Use when the user pastes meeting notes or transcripts and asks for action items, owners, or follow-ups." --with-references
3. Body: workflow steps + a worked example; output table format in references/output-format.md.
4. python3 scripts/validate_skill.py ~/.claude/skills/meeting-actions --strict
5. Package if the user wants a shareable file.