skill-writing
Installation
SKILL.md
A skill is a teaching document for a future agent — it transfers intent and judgment so the agent can achieve a goal without the author present.
Modes
This skill teaches principles, not a procedure — the modes are entry points that point into the knowledge below, not steps to run in order. Each names an intent and where its leverage sits:
| Mode | Intent | Where the leverage is |
|---|---|---|
| create | Build a new skill from a validated concept | The whole document; start from Skill Anatomy and Content Placement |
| extract | Distil a skill from what just happened in the session | Durability is the main risk — session detail leaks in; hold to Writing Standards |
| audit | Assess an existing skill for quality | Run the Quality Gate and report findings |
| update | Revise an existing skill for new requirements | A surgical change, then re-run the Quality Gate; never drop process logic without confirmation |
A create run has a natural default path — adapt it per mode, don't treat it as a fixed sequence:
- Gather context — see Context First, Then Interview.
- Plan structure — characterise the skill on both axes — knowledge↔procedural (see Knowledge or Procedural) and stateful↔stateless (see Stateful or Stateless) — then decide what belongs in the body versus references, scripts, or assets (see Content Placement).
- Write — let the task's fragility and the agent's existing knowledge determine how much structure to impose; apply Writing Standards throughout.
- Run the Quality Gate.