Build Better Software with AI Agents Using Engineering Skills

A reference, sourced from mattpocock/skills (MIT), for writing and editing skills well - the vocabulary and principles that make a skill predictable, where predictability means the agent taking the same process every run, not producing the same output. It covers invocation choice: a model-invoked skill keeps a description in context every turn, contributing to context load, so the agent or other skills can fire it autonomously, written with rich trigger phrasing; a user-invoked skill, set with disable-model-invocation: true, strips that description from the agent's reach, paying zero context load but costing the user's own cognitive load as the index that must remember the skill exists - past a certain number of user-invoked skills, a router skill, one user-invoked skill naming the others and when to reach for each, cures the pile-up. It defines a description's two jobs, stating what the skill is and listing the branches that trigger it, with pruning rules: front-load the leading word, one trigger per branch collapsing synonym duplicates, and cut identity already covered in the body. It lays out an information hierarchy of three tiers ranked by how immediately the agent needs material - in-skill steps, ordered actions in SKILL.md each ending on a checkable, ideally exhaustive completion criterion to avoid premature completion; in-skill reference, definitions, rules, or facts consulted on demand, often a legitimate flat peer-set; and external reference, pushed to a separate file reached via a context pointer, loaded only when the pointer fires - with progressive disclosure as the move down the ladder and co-location keeping a concept's definition, rules, and caveats under one heading. It gives two granularity cuts for splitting a skill: by invocation, splitting off a model-invoked skill only when a distinct leading word or another skill's reach independently earns the new always-loaded description, and by sequence, splitting a run of steps when the steps still ahead tempt the agent to rush the current one. Pruning discipline requires a single source of truth per meaning, a relevance check on every line, and hunting no-ops sentence by sentence, deleting the whole sentence when it fails the test rather than trimming words. It defines a leading word as a compact, already-pretrained concept, such as lesson, fog of war, or tracer bullets, that anchors both execution in the body and invocation in the description in the fewest tokens, with worked collapses like "fast, deterministic, low-overhead" into tight, or "a loop you believe in" into red. It closes with five named failure modes and their fixes: premature completion, fixed by sharpening the completion criterion first and only splitting as a last resort; duplication, the same meaning in more than one place; sediment, stale layers that accumulate without a pruning discipline; sprawl, too-long skills cured by the disclosure ladder and splitting; and no-op, a line the model already obeys by default, fixed with a stronger leading word rather than a different technique.

Use it as a reference when writing or editing a skill and needing the vocabulary and principles - invocation choice, information hierarchy, granularity, pruning, leading words, failure-mode diagnosis - that make the result predictable. It is itself "all reference," a flat peer-set of definitions and rules rather than a step-by-step workflow, with bolded terms defined in a companion GLOSSARY.md.

Input is an existing or draft skill to write, edit, or diagnose. Output is a revised skill applying the documented principles - correct invocation mode, a pruned trigger-only description, material placed at the right tier of the information hierarchy, and named failure modes fixed at their root cause rather than patched.

A companion file, GLOSSARY.md, holds the full definitions of every bolded term used here, including leading word, context load, cognitive load, branch, and completion criterion, itself an example of the external-reference pattern it describes.

Skill authors and coding agents writing or reviewing skill definitions who need a shared vocabulary for diagnosing bloat, duplication, and unpredictable behavior rather than rewriting from intuition.