5.2 KiB
Glossary — Skill Craft
This glossary defines the checks for craft-skill.
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.