A skill is a teaching document for a future agent: it transfers intent and judgment so that agent can achieve a goal without the author present. A skill exists to wrangle determinism out of a stochastic system — predictability, the agent taking the same process every run (not producing the same output; a brainstorming skill predictably diverges), is the root virtue. Every tenet, axis, and craft rule below is a lever on it.

Everything here governs the whole skill, not just its body: a reference is body content deferred, not a different kind of document, and assets/ prose and script docs are held to the same bar.

Tenets

When a writing decision is not covered elsewhere in this document, resolve it against the tenets directly.

A skill MUST:

Teach the class of problems — how to approach the class, never what to produce for a specific instance.
Be grounded in real expertise — extracted from hands-on task execution or synthesized from real project artefacts (runbooks, schemas, review comments, failure cases). A skill generated from generic training knowledge yields vague procedures ("handle errors appropriately") and adds no delta.
Target the agent, not the user — if the information is not necessary for the agent to perform its task, cut it.
Carry activation entirely in the description — the body is never read until after activation, so the description is the sole activation signal. Never write a "when to use this skill" section in the body.
Encode timeless principles — moderated by the Knowledge ↔ Procedure axis: principles are the default payload; a procedure skill may encode steps instead.
Never encode the current state of the world — corpus contents, file counts, "all existing X do Y". Such facts rot as the skill is used, most sharply when the skill exists to change that very state. Where current state is required, instruct the agent to explore.

A skill SHOULD:

writing-skills

Tenets