---
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.

   Finish when the user can review the exact files changed.