dev/src/skills/craft-skill/SKILL.md

name, description, disable-model-invocation

name	description	disable-model-invocation
craft-skill	Draft or audit an Agent Skill for structural predictability. Run deliberately as /skill:craft-skill when creating or improving a skill.	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 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.