162 lines
5.2 KiB
Markdown
162 lines
5.2 KiB
Markdown
# 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.
|