Writing a skill

Activation: the directive description

Agents scan the description to decide whether to load the skill. A self-published 650-trial measurement (one author, not peer-reviewed) reported passive descriptions activating far less reliably than directive ones with an explicit exclusion clause. Treat the exact percentages as a hint, not a law — but the direction is consistent and the fix costs nothing, so we took it.

Four required clauses

• WHAT.Open with an imperative verb: “Implement a feature”, “Back every claim”, “Judge another agent's work”.
• ALWAYS. Name concrete triggers, including implicit signals the user might not say literally.
• Do not. Block the default bypass — the thing the agent would do if it skipped the skill.
• Skip for. Name task types, not sibling skill names. This prevents directive saturation without assuming another skill is installed.

Target 350–600 characters. Hard cap 800. The open spec allows 1024, but the tighter limit is a forcing function for clarity.

Body anatomy

Activation is necessary but not sufficient. The body must be shaped so the agent acts on it. Long contexts suffer from U-shaped attention: the start and end are remembered; the middle fades.

Length budgets

• ~200 lines is the practical target.
• 500 linesis the hard cap, backed by Anthropic's own guidance.
• If a skill grows past 200 lines, the question is “what moves to references?”, not “should I raise the limit?”.

Forced visible output

Skills have two reliability problems: activation and execution. A loaded skill can still skip late-stage verification steps because they produce no visible content. The fix is structural: every verification must leave a marker the next reader can see.

Self-containment

A user who installs only write-feature does not have empirical-proof in context. Therefore write-featuremust read correctly on its own. If a related discipline is load-bearing, restate it inline — a sibling may be mentioned only as an optional “if installed” note.

The AGENTS.md contract

Skills name abstract command slots — cmdTest, cmdLint, cmdValidate— never concrete commands. The consuming repo's AGENTS.md Commands table supplies the implementations. An empty slot means ask; a skill never invents a command.

This split is what makes a skill portable: the guide carries the discipline, your repo carries the toolchain.

Task templates

Long-running tasks accumulate intermediate findings, abandoned hypotheses, and decisions. The task file is the agent's working memory, written to disk. It is not the deliverable; it is the scratchpad. Keep it gitignored, local, and personal.

The MIHPSG rubric

Ship a references/task-template.md only when at least three of these six criteria hold:

• Multi-session — likely to span more than one agent session
• Iteration — validate → fix → re-validate cycles
• Hypothesis tracking — multiple competing explanations
• Multi-stage plan — four or more distinct phases
• State separate from deliverable — working state is not the final artefact
• Verification checks — pasted command output required

Personas and cross-cutting quality checks like empirical-proof deliberately ship no template — their discipline lives in the body and surfaces inside whichever workflow's task file is in play.

Scope

A skill must be useful in any consumer repo, by itself, with no implicit dependencies. The catalogue is deliberately narrow so it stays portable.