/swarm-skill-forge

name: swarm-skill-forge
description: Author new high-quality skills that trigger reliably and stay lean. Use when creating or editing a skill, packaging a workflow as a skill, or deciding whether something should be a skill at all.

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.

Ship

Project skills → `.claude/skills/<name>/` + an AGENTS.md index line (name, description, when-to-use, path) for Codex. Contributions to SwarmVault itself → canonical `skills/`

• a CREDITS.md entry if the technique has an upstream.

--- *Influences: superpowers writing-skills; Pocock's writing-great-skills — see CREDITS.md.*