# Glossary — Skill Craft This glossary defines the checks for [`craft-skill`](SKILL.md). Each term is a lever on **predictability**. ## Predictability The degree to which a skill makes the agent follow the same process on every run. Predictability does not require identical output. A brainstorming skill can predictably produce different ideas. ## Invocation How the agent or operator reaches a skill. Invocation controls who pays the load for discovery. ### Model-invoked A skill that the harness exposes to the agent's available-skills list. The agent can load it without an explicit operator command. Use model invocation when the agent must discover the skill on its own. ### User-invoked A skill that the operator runs deliberately through the harness invocation mechanism. Use user invocation when human judgment decides when the skill applies. For Pi, keep the required description and add `disable-model-invocation: true`. ### Description Required metadata that states what the skill does and when to use it. For model-invoked skills, the description carries the trigger condition. For user-invoked skills, the description remains valid metadata. ### Context pointer A short reference that tells the agent when to load out-of-context material. The pointer's wording controls whether the agent reaches the target. Fix weak wording before moving the target inline. The description is the top-level context pointer for a model-invoked skill. A link to a sibling reference file is a lower-level context pointer. ### Context load The permanent attention cost of model-invoked skill descriptions. More discoverable skills create more context load. Use context load to decide whether a skill needs model invocation. ### Cognitive load The memory cost that user-invoked skills place on the operator. More user-invoked skills make the operator remember more names and uses. Use cognitive load to decide whether a skill needs discoverability. ## Information hierarchy How a skill ranks information by the moment the agent needs it. Keep the active procedure above supporting reference. Move branch-specific or large reference behind context pointers. ### Steps Ordered actions that the agent performs. Put steps in `SKILL.md` when the skill has an active procedure. End each step with a completion criterion. ### Reference Material that the agent consults while following steps. Keep short reference near the step that needs it. Move large or branch-specific reference to sibling files. ### External reference Authoritative material that lives outside the skill directory. Point to external reference instead of duplicating project policy. Use it when another file owns the meaning. ### Progressive disclosure Moving reference out of `SKILL.md` and behind a precise context pointer. Use progressive disclosure to protect the skill's active procedure. Keep must-read material inline when a pointer would miss too often. ### Co-location Keeping a concept's rules, caveats, and examples near one another. Use co-location so one read gives the agent the complete local meaning. Do not scatter one concept across unrelated sections. ## Steering How a skill shapes the agent's runtime behavior. Steering turns a document into a repeatable process. ### Branch A distinct path through a skill. A branch handles a case that does not run the same steps as other cases. Do not call ordinary checklist items branches. ### Leading word A compact term that anchors a repeated behavior. Prefer words already used by prompts, docs, or code. Repeat the word, not the full explanation. ### Completion criterion The condition that tells the agent a step is complete. A strong completion criterion is checkable and demanding. Use it to prevent early movement to the next step. ### Legwork The work the agent performs inside a step. Strong completion criteria increase legwork. Weak criteria let the agent stop after surface-level work. ### Post-completion steps The steps visible after the current step. Visible later steps can pull the agent forward too early. Hide later steps only when a real context boundary exists. ## Failure modes Use these findings during audit and verification. Quote the offending passage when a finding applies. ### Premature completion A step ends before its necessary work is complete. This usually comes from a vague completion criterion. Fix the local criterion before splitting the skill. ### Duplication One meaning has more than one authoritative expression. Duplication increases maintenance cost and false emphasis. Replace duplicates with one source and pointers to it. ### Sediment Old content remains after the skill's behavior changes. Sediment makes the agent attend to stale instructions. Remove lines that no longer affect the skill's current behavior. ### Sprawl `SKILL.md` contains too much live material. Sprawl hides the active procedure among supporting details. Move reference down the information hierarchy. ### No-op An instruction does not change the agent's default behavior. No-op instructions spend attention without adding control. Judge no-op instructions against behavior, not style. Delete a no-op sentence instead of shortening it. Cut no-op sentences unless they anchor a target-project convention.