src/skills/.pi/skills/craft-skill

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

src/skills/craft-skill/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: craft-skill
+description: Draft or audit an Agent Skill for structural predictability. Run deliberately as /skill:craft-skill when creating or improving a skill.
+disable-model-invocation: true
+---
+
+# craft-skill
+
+Draft or audit an Agent Skill.
+Judge the skill against one bar: **predictability**.
+Predictability means the agent follows the same process on every run.
+
+Read [`GLOSSARY.md`](GLOSSARY.md) before applying glossary terms.
+Use this skill for skill structure, not general prose review.
+Apply project writing rules when the target project defines them.
+
+## Choose the branch
+
+Use **Draft** when creating a new skill source.
+Use **Audit** when reviewing an existing skill in its authoritative source.
+
+Finish when one branch matches the user's requested change.
+
+## Draft
+
+1. Resolve the destination.
+   Read the target project's instructions and skill-source conventions.
+   Prefer an existing source directory over a new convention.
+   Trace symlinks and generated placements to their source.
+   Ask the user when multiple writable sources remain plausible.
+
+   Finish when the destination is writable and authoritative.
+
+2. Create the skill structure.
+   Create a directory whose name matches the skill name.
+   Add `SKILL.md` with valid Agent Skills frontmatter.
+   Add `disable-model-invocation: true` only for Pi user-invoked skills.
+   Add sibling files only when they protect the **information hierarchy**.
+
+   Finish when the file layout matches the target harness and project.
+
+3. Write the skill body.
+   Put active **steps** in `SKILL.md`.
+   Keep shared **reference** near the steps that need it.
+   Move large or branch-specific reference behind precise **context pointers**.
+   Front-load the **leading word** in descriptions and other context pointers.
+   Write pointer text for the condition that loads the target.
+   Give each step a checkable **completion criterion**.
+   Cut sentences that do not change agent behavior.
+   Use relative paths for all skill-local references.
+
+   Finish when each branch has ordered steps, resolved references, and checkable completion criteria.
+
+## Audit
+
+1. Locate the authoritative source.
+   Read the target project's instructions and skill-source conventions.
+   Inspect enabled-skill directories only to find the source.
+   Do not edit symlinks, generated files, installed packages, or vendored copies.
+   Ask the user when multiple sources claim the same skill.
+
+   Finish when you have identified the authoritative source.
+
+2. Read the skill surface.
+   Read `SKILL.md` and every disclosed file.
+   Read project documents that the skill treats as authoritative.
+   Record which file owns each meaning before judging duplication.
+
+   Finish when all referenced behavior is visible.
+
+3. Apply the checklist.
+   Quote each passage that fails a glossary check.
+   Check **invocation** against the intended harness.
+   Check **context pointers** for weak trigger wording.
+   Check **information hierarchy** for buried steps or disclosed required material.
+   Check **completion criteria** for vague or weak stopping points.
+   Check **leading words** for repeated explanations they can replace.
+   Check **pruning** for sentences that explain default model behavior.
+   Check **duplication**, **sediment**, **sprawl**, and **no-op** instructions.
+
+   Finish when every finding has quoted evidence or no finding remains.
+
+4. Report or fix findings.
+   Report findings by default.
+   Fix findings only when the user requests edits.
+   Preserve behavior that passes the checklist.
+   Change only structural skill problems unless the user expands the scope.
+
+   Finish when you have reported each finding or fixed each requested finding.
+
+## Verify
+
+1. Run deterministic checks.
+   Verify required frontmatter exists.
+   Verify the name is portable and matches the directory.
+   Verify the description is specific and under 1024 characters.
+   Verify every skill-local reference resolves with a relative path.
+   Verify context pointers name when to load referenced material.
+   Verify disclosed files exist.
+   Verify each retained sentence changes behavior or records target-project policy.
+   Verify no stale harness-specific assumption remains.
+
+   Finish when each check passes or the final report names checks that could not run.
+
+2. Re-read against the glossary.
+   Re-check **invocation**, **information hierarchy**, and **completion criteria**.
+   Re-check **duplication**, **sediment**, **sprawl**, and **no-op** instructions.
+   Fix any new structural finding.
+
+   Finish when no unresolved structural finding remains.
+
+3. Report the result.
+   List every changed path.
+   State whether you enabled the skill or only authored it.
+   Do not stage or commit unless the user requested it.
+
+   Finish when the user can review the exact files changed.