write-skills

Topics in the source

• Write Skills
• First Principles
• Leading Words
• Invocation
• Description
• Information Hierarchy
• When to Split
• Failure Modes

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. 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 st

This is an excerpt. Refer to the complete source and its current requirements.