Agent Skills: skill-doctor

skill-doctor

The orchestrator/triage layer over the user's whole Claude Code customization surface. It does the finding — what to add, merge, fix, or codify — then hands the deep work to the tools that already own it. Reuse, don't reinvent:

• Creating or iterating a skill (drafting, evals, description optimization, packaging) → invoke the skill-creator skill if it's installed (it ships in Anthropic's agent-skills marketplace and bundles improve_description.py, run_loop.py, package_skill.py, quick_validate.py).
• Tuning an agent's prompt → delegate to the development-productivity:prompt-engineer-agent agent. Verify the name resolves before dispatching; if that plugin isn't installed, do the tuning inline.
• "This is really a standing rule, not a skill" → write it into the relevant CLAUDE.md (e.g. via the /update-claude-md command) or the project's memory store.
• Auditing / cleaning up the memory store itself (orphans vs MEMORY.md, stale memories, dedupe, "scope memories into skills") → the memory-doctor skill if installed, the sibling of this one for the memory surface. skill-doctor reads memories as input for skill ideas; memory-doctor maintains the memory files.

Editable targets — read this first

You may edit/create files under:

• ~/.claude/{skills,agents,commands}/ — the user's personal, non-git config. Edited in place.
• Skill/agent/command files inside a git repo the user owns or contributes to. Changes here ship as a draft PR (see "Delivering changes once approved" below) — never an in-place edit on the repo's working branch, never a direct commit to its default branch.

Installed marketplaces and plugin caches (~/.claude/plugins/marketplaces/…, ~/.claude/plugins/cache/…) are read-only install mirrors — map and analyze, never edit. If a worthwhile fix lands on a read-only mirror, fork a copy into a writable location instead. The inventory tags every entry with writable; respect it.

Never auto-apply. Propose a numbered menu and let the user pick. The user always approves which change before you make it.

Delivering changes once approved:

• ~/.claude/… (not a git repo): edit in place; show the before/after first.
• Any file inside a git repo: deliver as a draft PR automatically — don't ask a second time once the change itself is approved. Detect the repo's default branch (git symbolic-ref --short refs/remotes/origin/HEAD — it is NOT always main), branch off origin/<default> in a clean worktree, apply the edit, commit, push, and gh pr create --draft --base <default>. Return the PR URL and leave it in draft. Never push to the default branch directly. One draft PR per logical change; group trivially-related edits in the same repo into one PR.

Run modes

The skill takes an optional mode argument (the slash commands pass it):

| Mode | Steps | When | | --------- | ---------------------------------- | ---------------------------------------------------------------------------------- | | map | 1–3 | Pure audit / fresh session. Inventory + analysis + suggestions. No session mining. | | session | light 1, then 4 | Mine THIS conversation for skills/agents to add or fix. | | create | jump to 4's "new skill/agent" path | "Turn this into a skill." Hand to skill-creator. | | full | 1–5 | Everything. Default when the session contains real work. |

Step 1 — Resolve mode

If a mode was passed, use it. Otherwise auto-detect: if the session already contains substantive prior work (a real task was carried out, not just this invocation), use full; if it's a fresh/empty session, use map. State the mode you picked in one line, then run only the steps its row enables.

Step 2 — Inventory (modes: map, full; light version for session/create)

Run the bundled script — it extracts the signal without you reading hundreds of files:

python3 "${CLAUDE_PLUGIN_ROOT}/skills/skill-doctor/scripts/inventory.py" --cwd "$PWD"
# session/create modes: add --mine-only to limit to writable (own) sources

It writes inventory.json + inventory.md to a temp workspace and prints the path. Read inventory.md (compact tables grouped by source + a Flagged section). Do NOT read every underlying file — that's the whole point of the script.

Present a short summary: counts per source, and the headline flagged issues.

Step 3 — Analysis pass (modes: map, full)

Reason over the map (not the raw files). Produce a prioritized, numbered list of suggested improvements. For each: target file, problem, proposed change, and whether it's writable. Cover:

The script's flags are a starting point, not the boundary of the audit. Read the whole map and report every genuine issue you see, including ones the script did not flag — the flags are keyword and threshold heuristics, so a real overlap or a weak description can sit in an unflagged row. Rank at the end; do not filter during discovery.

• Overlaps / duplicates. Start from the duplicate_names and near_duplicate_descriptions flags. Ignore mirror-only duplicates (marketplace↔plugin-cache are just install mirrors of the same upstream item). Focus on [editable] collisions and genuinely distinct skills doing the same job. Recommend a canonical one + merge/deprecate the rest.
• Gaps. Recurring needs with no skill. Cross-reference the project's memory store if one exists — many feedback memories encode repeated corrections that may deserve a skill.
• Trigger-quality. Start from weak_or_missing_description and no_trigger_language, and flag any other description that reads weak on the rubric. Deep-read the writable items you'll actually propose changing. Read them directly when there are only a few (a handful of reads is cheaper inline than a dispatch); delegate to a single Explore or general-purpose subagent only when the set is large enough that reading it inline would crowd out main context — ask that subagent to return the current description + body summary + a tightened description proposal per item. For rigorous triggering work, hand the item to skill-creator's improve_description.py / run_loop.py loop.
• Oversized bodies. oversized_body items (>500 lines) are candidates for progressive disclosure (move detail into references/).

See references/analysis-rubric.md for the heuristics (good-description shape, overlap judgment, skill-vs-agent-vs-CLAUDE.md decision).

Step 4 — Session mining (modes: session, create, full)

Only meaningful if the session contains real prior work. Read the conversation and look for:

• Codify-worthy workflows — a repeated multi-step sequence, or "do X like last time." Propose a NEW skill or agent: draft name, a pushy description (per the rubric), and a body outline. Decide skill vs agent vs command using the rubric. In create mode, go straight here and hand the draft to the skill-creator skill to flesh out + eval.
• Undertriggering — a skill that should have fired this session but didn't. Identify which one and propose a description fix (the description is the trigger mechanism).
• Misfire / overtrigger — a skill that fired wrongly. Tighten its description.
• Repeated corrections — guidance the user gave more than once. Decide whether it belongs in a skill, an agent, or as a standing rule (a CLAUDE.md entry / a memory file).

Ground every proposal in a specific moment from the conversation — quote the turn that motivates it. Vague "you could add a skill for X" proposals aren't useful.

Step 5 — Present & apply (all modes)

Show the consolidated, prioritized menu. Mark each item [editable] or [read-only]. Keep each entry to a line or two — target, problem, proposed change — so the menu stays scannable; detail belongs in the follow-up on the items the user picks. Let the user choose. Then, for accepted items only:

• New/iterated skill → skill-creator skill.
• Agent prompt tuning → the development-productivity:prompt-engineer-agent agent (inline if that plugin isn't installed).
• Standing rule → the /update-claude-md command or a memory file.
• Direct small edits (e.g. a tightened description):
  • under ~/.claude/… (non-git) → edit in place; show the before/after first.
  • inside a git repo → open a draft PR per "Delivering changes once approved" (branch off the repo's default branch in a clean worktree, commit, push, gh pr create --draft).

After any change, suggest re-running inventory.py to confirm the flag cleared. For draft PRs, surface the PR URL and note it's left in draft for review.