feat(skills): add craft-skill

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.