references/glossary.md
# Glossary – Building Great Skills
The domain model for what makes a skill great. A skill exists to wrangle determinism out of a stochastic system; every term below is a lever on that goal. This is the disclosed reference for [`create-a-skill`](../SKILL.md).
**Bold terms** in any definition are themselves defined in this glossary; find them by their heading.
## Language
### Predictability
The degree to which a skill makes the agent behave the same _way_ on every run – the same process, not the same output (a brainstorming skill should _predictably_ diverge; its tokens vary, its behaviour doesn't). The root virtue every other term serves – cost and maintainability are symptoms of it, not rivals.
_Avoid_: consistency, reliability, robustness, output-determinism
### Model-Invoked
A skill the harness may select implicitly when a request matches its **description**. The human may also invoke it explicitly. The host controls discovery and invocation policy; keeping a description does not by itself guarantee selection.
_Avoid_: ability, tool, capability
### User-Invoked
A skill intended for explicit invocation by the human. Keep its **description** and configure the host to disable implicit invocation. Metadata and context costs differ by harness; explicit-only use does not promise zero context load.
_Avoid_: procedure, workflow, command
### Description
Required portable metadata describing what the skill does and when it applies. It supports discovery and selection. Invocation policy is separate; deleting a description can make the skill invalid.
_Avoid_: frontmatter, summary
### Context Pointer
A reference held in the agent's context that names some out-of-context material and encodes the condition for reaching it. The **description** is the top-level context pointer (context window → skill); pointers to disclosed files are the same object one level down. Its wording, not the target, decides _when_ the agent reaches – and _how reliably_. A must-have target behind a weakly worded pointer is a variance bug: fix the wording first, and inline the material only if sharpening fails.
_Avoid_: link, reference, import
### Context Load
The context consumed by discovered skill metadata and any subsequently loaded instructions or references. Measure the host behavior instead of assuming every description is always loaded in full.
_Avoid_: token cost, context bloat
### Cognitive Load
The cost a **user-invoked** skill imposes on the human – what they must hold in their head: which skills exist and when to reach for each (the human is the index). What **model-invocation** removes by being agent-discoverable, and the brake on splitting into more user-invoked skills. Not a cost to minimise: it is the price of human agency, the reason some skills stay user-invoked. Spend it where human judgement matters; remove it where it does not.
_Avoid_: human index, burden, overhead
### Granularity
How finely you divide skills. Finer division spends one of the two loads: more **model-invoked** skills spend **context load** (more descriptions crowding the window and competing for attention); more **user-invoked** skills spend **cognitive load** (more for the human to remember and reach for). Two cuts guide the division. By **invocation**, split off a model-invoked skill where you have a distinct **leading word** to trigger it – a trigger word you actually use in your prompts. By **sequence**, split a run of **steps** where a step's **post-completion steps** need hiding, since isolating it in its own context clears what follows. Beware the reverse: merging sequences exposes each step's post-completion steps to what follows, inviting premature completion.
_Avoid_: chunking, modularity
### Router Skill
A skill that points to a small set of related skills and explains when to use each. Respect the invocation policy and authorization of each destination; routing does not grant additional authority.
_Avoid_: dispatcher, menu, registry, index, router procedure
### Information Hierarchy
A skill's content ranked by how immediately the agent needs it – a single ladder, produced by two cuts: in-file or behind a pointer, and step or reference. The rungs:
- **Steps** – in-file, primary
- **Reference**, in-file – secondary
- **Reference**, disclosed – behind a **context pointer**
A skill with no **steps** uses just the bottom two rungs – often a legitimately flat peer-set (e.g. every rule of a review on one rung), which is a fine arrangement, not a smell. The hierarchy is independent of invocation: a skill can be model- or user-invoked whether it is all steps, all reference, or both. When a skill has steps, in-file reference that should be disclosed buries them and turns attending to them into a coin-flip – a variance lever, not just a legibility one. Keep the top of the ladder legible; push down it whatever you can.
_Avoid_: structure, organization, layout
### Co-location
Keeping the material an agent needs at once in one place – a concept's definition, rules, and caveats under a single heading, not scattered across the file – so reading one part brings its neighbours with it. The within-file companion to the **Information Hierarchy**: the hierarchy ranks _how far down_ a piece sits; co-location decides _what sits beside it_ once there. There is no formula for the right format of a body of **reference**; the test is that a skill should read like documentation written for the agent, and grouped material reads that way where scattered material does not. Distinct from **Duplication**: that repeats one meaning in two places, where scattering fragments a single meaning across many.
_Avoid_: grouping, clustering, cohesion
### Branch
A distinct way a skill can be invoked – a case the skill handles – so different runs take different paths through it. A skill with many steps may carry many branches; a linear one has none.
_Avoid_: path, case, fork
### Progressive Disclosure
Moving **reference** down the ladder – out of SKILL.md and behind a **context pointer** – so the top stays legible. Not primarily a token optimisation; it is how the **information hierarchy** is protected. Licensed by **branching**: disclose what only some branches need, inline what every path needs, and if a pointer fires unreliably on must-have material, sharpen its wording, and pull it back inline only if that fails.
_Avoid_: lazy loading, chunking
### Steps
The ordered actions the agent performs – when a skill has them, the primary tier of its content, and the part that earns its place in SKILL.md. Not every skill has steps: a skill can be all steps (`tdd`), all **reference** (a review), or both, independent of invocation. Every step ends on a **completion criterion**, clear or vague.
_Avoid_: workflow, instructions, choreography
### Completion Criterion
The condition that tells the agent a unit of work is done – the target it judges against. Two properties make it a lever, not just a quality. Its **clarity** (can the agent tell done from not-done?) resists **premature completion** – a vague bound ("understanding reached") lets the agent declare done and slip to the next step; this axis needs _steps_ to bite, since premature completion is a between-steps failure. Its **demand** (how much it requires) sets **legwork** – "every modified model accounted for" forces thorough work where "produce a change list" does not – and this axis is _not_ step-bound: it can bind a body of flat reference too, which is how a skill with no steps still carries an exhaustiveness bar ("every rule applied"). The strongest criteria are both checkable and exhaustive.
_Avoid_: done condition, exit condition, stopping rule
### Post-Completion Steps
The **steps** that follow the current step. Visible, they pull the agent forward into **premature completion** – the more it sees, the stronger the tug; the defence is to hide them by splitting the sequence of steps into two.
_Avoid_: horizon, fog of war, lookahead
### Legwork
The work an agent does behind the scenes within a single step – reading files, exploring the codebase, making changes, digging up what it needs rather than offloading to the user. It lives below the step structure: never written as its own step, latent in the wording, controlled by the agent rather than the skill. The within-step counterpart to **post-completion steps**' across-step pull. Raised by a **leading word** (_comprehensive_, _thorough_) or a **completion criterion** that demands the work be exhaustive – including the demand axis applied to flat reference, which is what drives a skill of flat reference to cover all its rungs. Goes thin either when that demand is missing or when **premature completion** cuts the step short.
_Avoid_: scope, effort, diligence, coverage
### Reference
Material the agent refers to on demand – definitions, facts, parameters, examples, conditional instructions. When a skill has **steps** it is secondary to them; when a skill has none it is the entire content; or it lives outside any skill entirely – see **External Reference**. Reached via **context pointers**, and the prime candidate for **progressive disclosure**.
_Avoid_: supporting material, docs, background
### External Reference
Material outside the skill entry point that multiple skills can read when needed. A shared convention or API reference need not become an independently invocable skill.
_Avoid_: doc, resource, knowledge base
### Leading Word
A compact concept – also called a _Leitwort_ – already living in the model's pretraining, that the agent thinks with while running the skill. It encodes a behavioural principle in the fewest possible tokens by invoking priors the model already holds (e.g. _lesson_, _proximal zone of development_, _fog of war_, _tracer bullets_). Repeated as a token, never as a sentence, it accumulates a distributed definition across the skill and anchors a whole region of behaviour. Coining your own works if you define it clearly, but a made-up word recruits no priors – you pay in definition tokens what a pretrained word gives free. Reach for an existing word first.
A leading word serves **predictability** twice. In the body it anchors **execution** – the agent reaches for the same behaviour every time the concept appears, and inside flat reference it focuses attention on a class of thing to look for, recruiting the right checks each run. In the **description** it anchors **invocation** – and not only within the skill: when the same word lives in your prompts, your docs, and your codebase, the agent links that shared language to the skill and fires it more reliably. Word a description with the leading words you actually use when you want the skill.
_Avoid_: keyword, term, motif
### Single Source of Truth
The desired state where each meaning lives in exactly one authoritative place, so a change to the skill's behaviour is a change in one place. **Duplication** is its violation.
_Avoid_: home, canonical location
### Relevance
Whether a line still bears on what the skill does – the lens for what to keep. A line loses relevance either by never bearing on the task (mere exposition, or a **branch** that should be disclosed) or by going stale: drifting out of date as the behaviour or world it describes changes. Shorter skills are easier to keep relevant, because each line is cheaper to check. Distinct from **no-op**: relevance asks whether a line bears on the task, not whether it changes behaviour.
_Avoid_: load-bearing, staleness, freshness
## Failure Modes
### Premature Completion
Ending the current step before it is genuinely done, because the agent's attention slips to being done rather than to the work. A between-steps failure: it needs **steps** to occur – a skill with no steps that quits early isn't premature completion but thin **legwork** under an unmet demand. A tug-of-war between two forces: visible **post-completion steps** (the pull forward) and the **completion criterion**'s clarity (the resistance – a sharp, checkable bar holds; a vague one gives way). Fuzziness is the necessary condition: a sharp bound resists the pull no matter how many later steps are visible, so a step that never rushes needs no defending. Two levers hold a step that does, but reach for them in order: **sharpen the bound first** – it is local and cheap. Only when the criterion is irreducibly fuzzy _and_ you actually observe the rush do you **hide the later steps** – and hiding only works across a real context boundary (a user-invoked hand-off or a subagent dispatch; an inline model-invoked call leaves the later steps in context and clears nothing). One cause of thin legwork, but distinct from it: legwork can be thin even when a step runs to full completion.
_Avoid_: premature closure, the rush, rushing, shortcutting
### Duplication
The same meaning given more than one **single source of truth**. It costs maintenance (change one place, you must change the others), costs tokens, and inflates prominence – repeating a meaning weights it on the ladder past its real rank. The accidental inverse of a **leading word**, which raises attention on purpose by repeating a token, never the meaning.
_Avoid_: repetition, redundancy
### Sediment
Layers of old content that settle in a skill and are never cleared, because adding feels safe and removing feels risky – so stale and irrelevant lines accumulate and you must core down through them to find what is still live. The default fate of any skill without a pruning discipline; the slow erosion of **relevance**, as opposed to **duplication**'s repeated meaning.
_Avoid_: accretion, bloat, cruft, rot
### Sprawl
A skill that is simply too long – too many lines in SKILL.md – independent of whether they are stale or repeated. Even an all-live, all-unique skill can sprawl. It costs readability (the agent wades through more before it can act, and attention thins across the excess), maintainability (every extra line is one more to keep **relevant**), and tokens. The cure is the **information hierarchy**: push **reference** down behind **context pointers**, and split by **branch** or sequence so each path carries only what it needs. Distinct from **sediment** (length from stale accumulation) and **duplication** (length from repeated meaning) – sprawl is length itself, whatever its cause.
_Avoid_: bloat, length, size, verbosity
### No-Op
An instruction that changes nothing because the model already does it by default – you pay load to tell the agent what it would do anyway. The test: does a line change behaviour versus the default? A line can be perfectly **relevant** and still be a no-op. The same priors that make a **leading word** free make a no-op worthless.
A leading word is a _technique_; No-Op is a _verdict_ on a line – and they cross. A leading word too weak to beat the default is a no-op (_be thorough_ when the agent is already thorough-ish), and the fix is a stronger word that passes the verdict (_relentless_), not a different technique. So the No-Op test – does it change behaviour versus the default? – is also how you grade whether a leading word is earning its repetitions. This is model-relative, not reader-relative: two people disagreeing over whether a line is a no-op disagree about the default, and settle it by running the skill, not by debate.
_Avoid_: redundant instruction, restating the obvious, belaboring
SKILL.md
---
name: create-a-skill
description: Create, edit, and improve agent skills with the right invocation, information hierarchy, leading words, and pruning so each skill runs predictably. Use when the user wants to create, write, edit, refactor, or review a skill, or asks what makes a skill good.
license: MIT
metadata:
author: Alexander Thalhammer
version: '1.0'
---
# Create a skill
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 – is the root virtue; every decision below serves it.
**Bold terms** are defined in [`references/glossary.md`](references/glossary.md); look them up there for the full meaning. When writing the skill's Markdown, follow `style-guide/style-guide.md.md`. If the skill will produce code, docs, package, or Git output, point it at the relevant `style-guide/` file rather than restating that guide.
## Process
### 1. Gather
Establish what the skill must do before shaping it. Ask the user:
- What task or domain does it cover?
- What are the distinct **branches** – the separate use cases a run might take?
- Does it need deterministic scripts, or just instructions?
- What reference material already exists to fold in or point at?
_Done when_ you can name the skill's branches and say whether it carries **steps**, **reference**, or both.
### 2. Shape
Make the two structural calls before writing a line of body:
- **Model-invoked** vs **user-invoked**: keep a clear **description** in both cases. Choose whether implicit invocation is useful, then configure that policy through the target harness. For Codex, use `agents/openai.yaml` with `policy.allow_implicit_invocation: false` for explicit-only use. Other harnesses have different controls; verify them before writing metadata. Do not promise zero context load.
- **Information hierarchy**: rank every piece by how immediately the agent needs it – **steps** (in-file, primary) → in-file **reference** → disclosed reference behind a **context pointer**. Inline what every branch needs; **progressively disclose** what only some branches reach. Keep a concept's definition, rules, and caveats **co-located** under one heading.
_Done when_ invocation is chosen with a reason and each piece of content has a rung.
### 3. Draft
Create the folder and write the content to the shape from step 2:
```
skill-name/
├── SKILL.md # required – metadata plus lean core instructions
├── references/ # optional – one-level-deep context loaded just in time
├── scripts/ # optional – tiny deterministic CLIs
├── assets/ # optional – templates or static output material
└── agents/ # optional – harness metadata such as openai.yaml (invocation policy)
```
```md
---
name: skill-name
description: <what it does>. Use when <one trigger per branch>. # required for both invocation modes
---
# Skill Name
[Ordered steps, each ending on a completion criterion – or flat reference
under co-located headings, or both.]
```
Each **step** ends on a **completion criterion**: make it _checkable_ (can the agent tell done from not-done?) and, where it matters, _exhaustive_ ("every modified model accounted for", not "produce a change list") – a vague bound invites **premature completion** and thin **legwork**. Reach for **leading words** – compact concepts already in the model's pretraining (_lesson_, _fog of war_, _tracer bullets_) – repeated as tokens, never as sentences, to anchor a whole region of behaviour in the fewest tokens.
Add a script when an operation is deterministic, would otherwise be regenerated every run, or needs explicit error handling – it saves tokens and removes variance.
Do not add per-skill `README.md` files. Keep human-facing catalogue text in the repo-root `02-SKILLS.md`; keep agent-facing behavior in `SKILL.md` and just-in-time support files.
### 4. Write the description
The **description** is the only thing the agent sees when choosing a skill. It does two jobs – say what the skill is, and list the triggers:
- Front-load the skill's **leading word** – the word you actually type when you want it.
- One trigger per **branch**; collapse synonyms that merely rename one branch (**duplication**).
- Cut identity already in the body; keep triggers plus any "when another skill needs…" reach clause.
Good: `Extract text and tables from PDFs, fill forms, merge documents. Use when working with PDFs or when the user mentions forms or document extraction.`
Bad: `Helps with documents.` – gives the agent no way to tell it from other document skills.
### 5. Prune
- **Single source of truth**: each meaning in exactly one place, so changing behaviour is a one-place edit.
- **Relevance**: does each line still bear on what the skill does? Cut exposition and stale lines.
- **No-ops**: test each sentence in isolation – does it change behaviour versus the model's default? Delete whole failing sentences, aggressively, rather than trimming words. A weak leading word (_be thorough_) is a no-op; fix it with a stronger word (_relentless_), not more prose.
- Collapse restatements that gesture at one idea into a single **leading word**.
_Done when_ no sentence can be cut without losing behaviour.
### 6. Review
Present the draft and confirm with the user: does it cover every branch? Anything missing or unclear? Should any section be more or less detailed? Then run the checklist.
## Evaluate
Run a direct match, a paraphrase, an adjacent non-match, a missing-prerequisite case, and an authority
boundary case in fresh sessions. Inspect selection, process and output. Keep a record of failures,
harness/model version and fixture revision. Refer to the repository's SKILL-MAINTENANCE.md when present.
_Done when_ expected matches follow the process, non-matches avoid it, and blocked cases stop with
the missing information or capability. Structural validation alone is not a behavioral evaluation.
## Checklist
- [ ] Name and description are present; description states scope and triggers; invocation policy matches the target harness
- [ ] Every step ends on a checkable completion criterion
- [ ] Reference the agent needs only on demand is disclosed behind context pointers, not bloating the top
- [ ] One source of truth per meaning; no time-sensitive facts
- [ ] Concrete examples included; pointers reach one level deep
## Failure modes
Diagnose a misbehaving skill against these (full definitions in [`references/glossary.md`](references/glossary.md)):
- **Premature completion** – a step ends before it is genuinely done. Sharpen its completion criterion first; only if the bound is irreducibly fuzzy _and_ you observe the rush, split the sequence to hide the **post-completion steps**.
- **Duplication** – one meaning in two places. Costs maintenance and inflates the meaning's rank on the ladder.
- **Sediment** – stale layers left because adding feels safe and removing risky. The default fate of any skill without a pruning discipline.
- **Sprawl** – simply too long, even when every line is live and unique. Cure with the hierarchy: disclose reference, and split by branch or sequence.
- **No-op** – a line the model already obeys by default. Pure load, no behaviour change.