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: ```bash 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.