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. State the direction and let smart models figure out implementation details. A wrapper skill can be two sentences: name the capability to use and the skill to follow. Add mechanics only when a demonstrated failure requires them.

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, reached by a pointer that fires only when needed. Put repeatable fragile operations in scripts/. Put reusable output material in assets/.