From c004073137ed58831004f08a2532afc92e8b0a3e Mon Sep 17 00:00:00 2001 From: alexion Date: Sat, 5 Sep 2026 17:59:24 -0400 Subject: [PATCH] fix(skills): sharpen craft-skill audit checks --- src/skills/craft-skill/GLOSSARY.md | 4 ++++ src/skills/craft-skill/SKILL.md | 8 ++++++++ 2 files changed, 12 insertions(+) diff --git a/src/skills/craft-skill/GLOSSARY.md b/src/skills/craft-skill/GLOSSARY.md index d8bbc82..dfd7525 100644 --- a/src/skills/craft-skill/GLOSSARY.md +++ b/src/skills/craft-skill/GLOSSARY.md @@ -35,6 +35,8 @@ 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. @@ -154,4 +156,6 @@ Move reference down the information hierarchy. 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. diff --git a/src/skills/craft-skill/SKILL.md b/src/skills/craft-skill/SKILL.md index f1064af..c504cc5 100644 --- a/src/skills/craft-skill/SKILL.md +++ b/src/skills/craft-skill/SKILL.md @@ -43,7 +43,10 @@ Finish when one branch matches the user's requested change. 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. @@ -68,8 +71,11 @@ Finish when one branch matches the user's requested change. 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. @@ -89,7 +95,9 @@ Finish when one branch matches the user's requested change. 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.