swarm-skill-forge

swarm-skill-forge — skill authoring

A skill is packaged judgment: instructions a future agent follows instead of its defaults. Write one only when that trade is worth it.

Gate: should this be a skill?

• Recurring task with a non-obvious right way → skill.
• Single fact or preference → memory note. Project convention → CLAUDE.md/AGENTS.md line.
• One-off → nothing. When in doubt, don't — catalogs rot.
• Overlap check first: ls the installed skills; if an existing skill covers 70% of the job, extend it instead of adding a sibling (two skills for one job = router confusion).

Structure

---
name: kebab-case-verb-or-domain
description: <what it does> + <every trigger phrasing a user might use>. The
  description IS the router — write it for the model deciding whether to load.
---
# Name — one-line job
Gate / when NOT to use.
Numbered steps, imperative, each observable ("run X, expect Y").
Rules the defaults would get wrong.
Worked example (input → output).

• Platform-agnostic markdown only — it must read the same via Claude Code skills and a Codex AGENTS.md index.
• Portable on its own (NFR-C4): the folder must work when copied out alone, with no vault, no swarmvault.py, and no siblings installed. Name peer skills by what they add, never as a prerequisite, and give every vault-backed path a local fallback ("voice.md in the vault, else .writing/voice.md"). Skills about the vault are the exception. Degrade, don't downgrade: write the vault path first and fullest, then the fallback. A skill weakened so a lone copy can satisfy it has failed this rule, not passed it.
• Heavy reference material (> ~150 lines) → references/*.md, loaded on demand; the SKILL.md tells the reader which reference to load when.
• Machine-lane style for checklists/tables; prose where nuance matters.

Verify before shipping (skills are code — test them)

1. Trigger dry-run: write 3 paraphrases of how a user would ask; does the description clearly fire for them — and clearly NOT fire for near-misses?
2. Toy walk: execute the skill on a small real case; every step must be doable without information the skill forgot to mention.
3. Altitude check: delete every line the model would do correctly anyway — a skill states only what defaults get wrong.