feat(skills): add craft-skill

src/skills/craft-skill/GLOSSARY.md

@@ -0,0 +1,161 @@
+# 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.