The gap
docs/PLUGIN-PHILOSOPHY.md "Naming" fixes verb meanings: audit/scan are read-only findings reports (mutation only behind an explicit override), clean/tidy/fix mutate, check is a deterministic gate. Nothing mechanically verifies that a skill's description tells the same story as its verb contract and body.
The failure this invites, in both directions:
- a skill whose leaf verb or description reads as report-only while its body mutates on bare invocation (or hides an unadvertised mutation path);
- a skill whose description advertises fixing while the body never mutates.
The description is what the operator and the model route on — a mismatch is a factual defect in the surface being routed on, not a style issue.
Deliberately narrow scope
This was scoped during the context-budget design interview (2026-08-17): description/verb-contract mismatches only — a factual-consistency check a script plus a judged pass can find. Explicitly out of scope: whether any audit skill should gain a --fix path (a per-skill design decision, 175 of them), and any rename campaign. The naming doctrine itself is unchanged; claude-config:audit [--fix] is the compliant precedent shape.
Suggested home
skill-quality:check — it already walks every SKILL.md and owns the leaf-name/verb registry seam (scripts/check-skill-leaf-names.sh, scripts/skill-leaf-name-registry.txt).
Related
docs/topics/context-budget/PLAN.md (Q11 in the interview ledger, .work/startup-context-baseline/interview-checklist.md)
The gap
docs/PLUGIN-PHILOSOPHY.md"Naming" fixes verb meanings:audit/scanare read-only findings reports (mutation only behind an explicit override),clean/tidy/fixmutate,checkis a deterministic gate. Nothing mechanically verifies that a skill's description tells the same story as its verb contract and body.The failure this invites, in both directions:
The description is what the operator and the model route on — a mismatch is a factual defect in the surface being routed on, not a style issue.
Deliberately narrow scope
This was scoped during the context-budget design interview (2026-08-17): description/verb-contract mismatches only — a factual-consistency check a script plus a judged pass can find. Explicitly out of scope: whether any
auditskill should gain a--fixpath (a per-skill design decision, 175 of them), and any rename campaign. The naming doctrine itself is unchanged;claude-config:audit [--fix]is the compliant precedent shape.Suggested home
skill-quality:check— it already walks every SKILL.md and owns the leaf-name/verb registry seam (scripts/check-skill-leaf-names.sh,scripts/skill-leaf-name-registry.txt).Related
docs/topics/context-budget/PLAN.md(Q11 in the interview ledger,.work/startup-context-baseline/interview-checklist.md)