# Skill Doctor

> Diagnose hygiene problems across an installed skill set — routing token cost, vague or missing trigger descriptions, overlapping triggers between skills, and duplicates installed in multiple places. Use when the user asks to tidy, audit, trim, or debug their skills, when skills fire at the wrong time or not at all, or when too many skills are installed.

- Skill: `joshphoenix1/skill-doctor` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add joshphoenix1/skill-doctor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/joshphoenix1/skill-doctor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: joshphoenix1 (https://skillmd.com/u/joshphoenix1)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/joshphoenix1/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.