Build Better Software with AI Agents Using Engineering Skills

Lays out the vocabulary and principles for writing and editing skills so they run predictably, defining predictability as the agent taking the same process every run, not merely producing the same output, and treating that as the root virtue every other lever in the reference serves. Full definitions for its bold terms live in a companion GLOSSARY.md.

On invocation, it frames two choices with different costs. A model-invoked skill keeps a description so the agent can fire it autonomously and other skills can reach it, at the cost of context load since the description sits in the window every turn; the mechanics are omitting disable-model-invocation and writing a model-facing description with rich trigger phrasing like "Use when the user wants..., mentions...". A user-invoked skill strips the description from the agent's reach, invoked only by the user typing its name, paying zero context load but spending cognitive load since the user becomes the index that must remember it exists; the mechanics are setting disable-model-invocation: true and turning the description into a human-facing one-line summary with trigger lists stripped. It recommends model-invocation only when the agent must reach the skill on its own or another skill must, and user-invocation otherwise; when user-invoked skills multiply past what's memorable, a router skill, one user-invoked skill naming the others and when to reach for each, cures the piled-up cognitive load.

Writing the description covers two jobs a model-invoked description must do, state what the skill is and list the branches that should trigger it, with pruning guidance: front-load the skill's leading word since the description does its invocation work there; write one trigger per branch, since synonyms that rename a single branch are duplication and should collapse into the genuinely distinct branches; and cut identity already covered in the body, keeping the description to triggers plus any reach clause for when another skill needs it.

The information hierarchy ranks content by how immediately the agent needs it, across three tiers. An in-skill step is an ordered action in SKILL.md, the primary tier, each ending on a completion criterion that should be checkable (can the agent tell done from not-done) and, where it matters, exhaustive rather than vague, since a vague criterion invites premature completion. In-skill reference is a definition, rule or fact in SKILL.md consulted on demand, often a legitimately flat peer-set rather than a smell. External reference is reference pushed out of SKILL.md into a separate file reached by a context pointer and loaded only when the pointer fires, spanning disclosed reference (a sibling file still part of the skill, like this reference's own GLOSSARY.md) through fully external reference living outside the skill system. A demanding completion criterion drives thorough legwork whether or not the skill has steps, since "every rule applied" binds flat reference just as "every step done" binds a sequence; the whole tension is pushing too little down (bloating the top) against pushing too much down (hiding material the agent actually needs). Progressive disclosure is the move down that ladder into a linked file named for what it holds; branching, where different runs take different paths, is the cleanest disclosure test, inlining what every branch needs and pushing behind a pointer what only some branches reach, with a context pointer's wording (not its target) deciding when and how reliably the agent reaches the material. Co-location decides what sits beside a piece once placed, keeping a concept's definition, rules and caveats under one heading so reading one part brings its neighbours along.

Granularity, how finely skills are divided, spends one of the two loads on every cut, so splitting should only happen when the cut earns it. Splitting by invocation means pulling out a model-invoked skill when a distinct leading word should trigger it on its own or another skill must reach it, paying context load for the new always-loaded description. Splitting by sequence means dividing a run of steps when the steps still ahead (post-completion steps) tempt the agent to rush the one in front of it, since keeping them out of view encourages more legwork on the current task.

Pruning keeps each meaning in a single source of truth, one authoritative place so a behaviour change is a one-place edit; checks every line for relevance to what the skill actually does; and hunts no-ops sentence by sentence rather than line by line, running the no-op test on each sentence in isolation and deleting the whole sentence (not trimming words) when it fails, being aggressive since most failing prose should go rather than be rewritten.

A leading word is a compact concept already living in the model's pretraining that the agent thinks with while running the skill, examples given are lesson, fog of war, and tracer bullets, which anchors a whole region of behaviour in the fewest tokens by recruiting priors the model already holds; it serves predictability twice, anchoring execution in the body (the agent reaches for the same behaviour whenever the word appears) and invocation in the description (shared language across prompts, docs and code links the agent's firing more reliably to the skill). Worked collapses given: "fast, deterministic, low-overhead" collapses into the single pretrained word tight; "a loop you believe in" collapses into red, converting a fuzzy gate into a binary observable state.

It names five failure modes for diagnosing skill problems. Premature completion is ending a step before it's genuinely done, defended first by sharpening the completion criterion, and only if that's irreducibly fuzzy and the rush is actually observed, by hiding post-completion steps through a sequence split. Duplication is the same meaning in more than one place, costing maintenance and tokens and inflating a meaning's prominence past its real rank. Sediment is stale layers that settle because adding feels safe and removing feels risky, the default fate of any skill without a pruning discipline. Sprawl is a skill simply too long even when every line is live and unique, cured by disclosing reference behind pointers and splitting by branch or sequence. No-op is a line the model already obeys by default, tested by whether it changes behaviour versus the default; a weak leading word like "be thorough" on an already thorough-ish agent is a no-op, fixed with a stronger word like "relentless" rather than a different technique.

Use it when writing or editing a skill and needing the shared vocabulary and principles, such as choosing model- versus user-invocation, deciding what belongs in-skill versus in an external reference file, deciding when to split a skill, or diagnosing why a skill is behaving unpredictably. It is itself a reference skill with model invocation disabled, meant to be reached by name rather than triggered automatically.

Input is an existing or draft skill (its description, steps, and reference material) that needs evaluating or editing. Output is a set of concrete edits or decisions: description trigger pruning, tier placement on the information hierarchy, a split-or-don't-split call, pruning of duplicated or no-op lines, and named failure-mode diagnoses.

Points to its own companion GLOSSARY.md for full term definitions.

Anyone authoring or maintaining skills for an AI coding agent who wants a shared vocabulary for keeping a skill's behaviour predictable and its token cost controlled.