Skill Doctor

Skill Doctor

Skills are routed by their description — loaded at every session start, matched against every task. At 20+ installed skills the failure modes are mechanical: vague triggers that never fire (or fire on everything), overlapping descriptions that make routing a coin flip, duplicates drifting out of sync, and hundreds of tokens of dead description text. This skill finds them and fixes them.

Workflow

1. Measure. Run scripts/doctor.py (add --json for machine-readable). It inventories every installed skill across Claude Code/Codex/Cursor/agents dirs and reports: total routing budget (estimated tokens), per-skill description lints, trigger-overlap pairs, and duplicates.
2. Interpret. The script finds mechanical problems; you decide the cure. For each finding class:
   • Vague/thin triggers (LINT-02/03/04) — rewrite the description as a routing rule: what it does + concrete when-to-use. Good: "Use when the user asks to extract form fields or parse tables from a PDF." Bad: "Helps with documents."
   • Overlaps (CONF-01) — read both skills. Either differentiate the descriptions (distinct trigger verbs, distinct scope) or merge the skills if they do the same job.
   • Duplicates (DUP-01) — keep one source of truth. Prefer a single install location; symlink others if multiple agents need it.
   • Bloat (LINT-05) — move detail from the description into the body.
3. Act with consent. Show the user every proposed description rewrite or deletion as a diff before applying it. Never delete a skill without explicit confirmation.
4. Re-run doctor.py after fixes to confirm the budget shrank and no MEDIUM findings remain.

Guardrails

• Descriptions are routing rules, not documentation — every rewrite must keep the skill's real trigger scope; don't narrow a skill out of existence.
• Overlap ≠ redundancy: two skills about "review" can be legitimately distinct (code review vs. PR review process). Read before merging.
• Companion to skill-security-audit: the doctor checks hygiene, the auditor checks safety. Different questions, different tools.