write-skills

# Write Skills A skill is not documentation. It is compressed operational memory for an agent that already knows how to code and reason. Its job is **predictability** — the agent taking the same *process* every run, not producing the same output. Put only the context that changes what the agent will do. ## First Principles 1. **Trigger from the description.** The frontmatter `description` is the only part read before the skill loads. Say what the skill does and the concrete situations that should trigger it. Do not hide trigger rules in the body. 2. **Spend tokens like they are scarce.** Assume the agent is already good at general reasoning. Keep only non-obvious workflow, domain constraints, tool choices, failure modes, and validation rules. Delete background, motivation, and generic advice. 3. **Write procedures, not essays.** Prefer imperative rules, decision points, and small examples. A good skill changes behavior in the next turn; it does not merely explain the topic. And match the procedure to the deliverable's shape: a catalog of techniques with "pick what fits" produces tool-picking, not a flow — if the job is a shaped interaction (an interview, a staged walk), the workflow must *be* that shape, with the techniques demoted to steps inside it. 4. **Use progressive disclosure.** Keep the main skill file short. Push long schemas, examples, provider docs, or variant-specific guidance out into linked `references/` files, rea...