Skip to main content
skill CX Codex

skill-doctor — Claude Code skill: what it does, how to install

skill-doctor grades your agent setup from real Claude Code or Codex session history — which skills actually work, which don't, and proposes evidence-backed edits.

MIT 15 installs ★ 30,251 updated 2026-10-23

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add alirezarezvani/claude-skills
/plugin install skill-doctor@claude-code-skills
Open on GitHub

What skill-doctor does

The skill scans local Claude Code project history and Codex rollouts, discovers installed skills in .claude/skills, .agents/skills, .codex/skills, detects their invocations in transcripts, and scores sessions against two rubrics — efficiency (scorers/efficiency.md) and code quality (scorers/code-quality.md). Everything stays local: transcripts are secret-redacted, marked chmod 0600, and never uploaded.

After collecting data, the skill assigns labels from the rubric tables (no invented numbers). The aggregator score_aggregator.py validates them and computes the overall grade (0.5·efficiency + 0.35·code_quality + 0.15·skill_coverage). Exit code 4 means validation failed — fix what's named and re-run; bypassing this step is not allowed. Then render_report.py produces a self-contained HTML report with no JS or CDN, supporting dark mode and print-to-PDF. The skill drafts edits for discovered skills but applies them only after explicit per-file confirmation. Zero suggestions is a valid outcome if current instructions are sufficient.

What it helps with

  • find out which skills are actually used in projects
  • grade agent setup from session history
  • spot recurring issues in Claude Code dialogs
  • get skill edits backed by specific session evidence

Example prompts for the agent

  • Grade my agent setup from recent sessions
  • Which of my skills are working and which aren't
  • Check Claude Code history for the past 90 days and suggest fixes

How to install skill-doctor

1Plugin marketplace

/plugin marketplace add alirezarezvani/claude-skills
/plugin install skill-doctor@claude-code-skills

This installs the whole skill-doctor plugin with all its skills

2Skills CLI (Vercel)

npx skills add alirezarezvani/claude-skills --skill skill-doctor -a claude-code

3Manually: put the files in place

~/.claude/skills/skill-doctor/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/skill-doctor/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about skill-doctor

How to install skill-doctor in Claude Code?

Run /plugin marketplace add alirezarezvani/claude-skills, then /plugin install skill-doctor@claude-code-skills. For Codex, copy SKILL.md to .agents/skills/skill-doctor/.

What does skill-doctor do?

It collects Claude Code or Codex session history, scores it against efficiency and code-quality rubrics, finds recurring problem patterns, and proposes edits for installed skills. Everything runs locally, nothing is uploaded.

What happens if session history is empty?

The script collect_sessions.py will write sessions_sampled: 0 to inventory.json, and the skill will suggest trying --days 90 or specifying another repository via --repo. Without sessions there's nothing to score.

Source text

SKILL.md · MIT
---
name: skill-doctor
description: Use when the user wants their agent setup graded from real conversation history, asks which installed skills are actually working, or wants evidence-backed skill edits — scores recent local Claude Code / Codex sessions against efficiency and code-quality rubrics, then drafts skill changes gated by a deterministic aggregator and renders one local shareable report.
argument-hint: "[optional: --repo PATH, --days N, or a question about the setup]"
license: MIT
metadata:
  version: 1.0.0
  build_pattern: "Rebuild of warpdotdev/common-skills skill-doctor (MIT): harvest → LLM-judges-with-rubrics → deterministic aggregation gate → self-contained HTML report"
  distinct_from: "skillopt-sleep (nightly automated replay loop with adopt gate; this is one interactive graded pass); write-a-skill (authors a skill from expertise; this improves skills from observed session evidence); self-eval (grades this session's own work; this grades a window of past sessions)"
---

# skill-doctor — grade the agent setup from real sessions

> **Privacy is the contract.** Everything runs locally. Transcripts are condensed,
> secret-redacted, chmod-0600, and never uploaded — the only shareable artifact is
> the report the user chooses to share.

Run from the repo being graded. Every artifact goes to one fresh scratch dir, never
into the repo:

```bash
RUN="$(mktemp -d "${TMPDIR:-/tmp}/skill-doctor-XXXXXXXX")"
python scripts/collect_sessions.py --out "$RUN"          # 1 — harvest + redact
```

**1 — Collect.** Scans Claude Code project-history JSONL and Codex rollouts,
discovers repo skills (`.claude/skills`, `.agents/skills`, `.codex/skills`, plugin
layouts), detects skill usage (`Skill` invocations, slash commands, SKILL.md paths), samples
newest-first, and writes redacted transcripts. Read `$RUN/inventory.json`: if
`sessions_sampled` is 0, tell the user there is nothing recent to score (suggest
`--days 90` or `--repo`) and stop. `skills_found` 0 is fine — the report becomes a
case for creating skills.

**2 — Score.** `python scripts/score_aggregator.py --inventory "$RUN/inventory.json"
--emit-template > "$RUN/session_scores.json"`. Read each transcript in
`$RUN/transcripts/` and judge it against **both** rubrics — `scorers/efficiency.md`
and `scorers/code-quality.md`. Fill the template with a **label from the rubric's
table** and a 1–3 sentence reason citing transcript specifics. Never invent numeric
scores — the aggregator derives them from labels. Use `insufficient_evidence` when
a transcript shows no judgeable diff. Also write 1–5 `top_findings`: the most
impactful cross-session patterns, concrete and specific.

**3 — Draft edits.** Follow `references/skill_edit_governance.md` (the filing bar:
would a competent agent with the current instructions still fail this way?). For
each suggestion that clears it, write the full improved SKILL.md to
`$RUN/proposed/<skill>/SKILL.md`, produce `diff -u <current> <proposed>`, and record
it in `$RUN/suggestions.json` citing the sampled session id(s) that motivated it.
Zero suggestions is a valid success — say why per finding. Never modify the user's
real skill files in this step.

**4 — Aggregate (the gate).** `python scripts/score_aggregator.py --inventory
"$RUN/inventory.json" --scores "$RUN/session_scores.json" --suggestions
"$RUN/suggestions.json"`. It validates labels against the rubric tables, refuses
scores for unsampled sessions, requires substantive reasons, rejects suggestions
that cite no scored session, computes `overall = 0.5·efficiency +
0.35·code_quality + 0.15·skill_coverage`, and writes `report.json`. **Exit 4 is a
stop**: fix what it names and re-run; never hand-edit report.json around it.

**5 — Render + tell.** `python scripts/render_report.py --report "$RUN/report.json"`
→ one self-contained `report.html` (no JS, no CDN, dark-mode + print-to-PDF). Then
tell the user the grade and the top findings in text, link
`file://$RUN/report.html`, and ask whether to apply the proposed diffs to their
real skills — apply only on an explicit yes, skill by skill.

## Hard rules

1. **Never upload transcripts, session files, or any excerpt.** Local only.
2. **Labels only, from the rubric tables.** The aggregator owns all arithmetic.
3. **Every suggestion traces to a scored session** — or it is dropped. Generic best practice is not evidence.
4. **Zero suggestions is a success**, not a failure to report around.
5. **Exit 4 from the aggregator is a stop**, not an error to swallow or bypass.
6. **Never touch the user's real skill files** without an explicit per-skill yes; proposed edits live under `$RUN/proposed/`.
7. **A proposed skill edit follows write-a-skill discipline** — trigger phrase in the description, smallest change that expresses the rule, replace over append.

## Scripts

| Script | Role | Exit codes |
|---|---|---|
| `scripts/collect_sessions.py` | Harvest Claude Code + Codex sessions, redact secrets, sample, inventory | 0 · 3 bad input |
| `scripts/score_aggregator.py` | Validate labels/reasons/suggestions, compute grade, emit report.json | 0 · 2 warnings · 3 bad input · 4 validation failure |
| `scripts/render_report.py` | report.json → single self-contained report.html | 0 · 3 bad input |

All support `--help`, `--output json`, and `--sample` (no real history needed).

## References and assets

- [`scorers/efficiency.md`](scorers/efficiency.md) · [`scorers/code-quality.md`](scorers/code-quality.md) — the two rubrics, preserved verbatim from upstream
- [`references/transcript_scoring_canon.md`](references/transcript_scoring_canon.md) — why rubric-anchored LLM judging works and where it fails (7 sources)
- [`references/session_mining_privacy.md`](references/session_mining_privacy.md) — the local-only contract, redaction pattern canon (7 sources)
- [`references/skill_edit_governance.md`](references/skill_edit_governance.md) — the filing bar for proposing skill edits (7 sources)
- [`assets/session_scores.example.json`](assets/session_scores.example.json) · [`assets/suggestions.example.json`](assets/suggestions.example.json) · [`assets/report.example.json`](assets/report.example.json) — the three handoff shapes

© Alireza Rezvani · MIT · alirezarezvani/claude-skills

Similar skills

All skills for Agent setup: memory, context, orchestration →
improve-agent-setup jackulau improve-agent-setup — a Claude Code skill that finds recurring agent failures in recorded sessions and links them to instructions that may address them. It runs when asked to diagnose repeated mistakes or assess a rule change. CX Codex +1 ★ 149repo stars basecamp-doctor basecamp basecamp-doctor runs a diagnostic check on your Basecamp CLI, credentials, and agent integration. Quickly identifies what's misconfigured or needs updating. CX Codex +1 325installs yao-meta-skill Yao Team The yao-meta-skill Claude Code skill builds, revises, and evaluates agent skills. It handles skill migration, packaging, routing checks, and release tests. CX Codex +1 686installs skill-compass Evol-ai skill-compass — a skill for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode. Scores installed skills across six dimensions, finds the weakest one, and applies fixes. Runs on the first session after install. CX Codex +1 ★ 214repo stars skill-evaluation ft.ia.br skill-evaluation scores an agent skill against a framework merged from Anthropic's Claude Code practices and Matt Pocock's writing-great-skills method. Returns a scorecard across 4 axes with evidence-cited 0–100 marks. CX Codex +1 ★ 141repo stars session-reflection-analysis harperreed session-reflection-analysis — a skill for Claude Code and five other platforms that inspects session history. It spots wasted tokens, repeated mistakes and missing documentation, then proposes fixes. CX Codex +1 ★ 339repo stars

From the same set488

The whole set →
linkedin-analytics linkedin-analytics analyzes personal LinkedIn post exports using medians and permutation tests without leaping to false conclusions. Refuses to make claims on under 10 posts. CX Codex +1 17installs iso13485-audit-prep iso13485-audit-prep runs a six-question stress test on medical device quality systems before ISO 13485 audits, MDR reviews, or DHF closure. CX Codex +1 17installs fda-qsr-audit-prep fda-qsr-audit-prep runs six FDA 21 CFR 820 audit questions before an internal QSR audit, an inspection, or a Form 483 response. CX Codex +1 17installs md-slides md-slides turns a markdown deck into a single HTML file with keyboard navigation, a presenter view and one-slide-per-page printing. CX Codex +1 15installs pw-init pw-init — a Claude Code skill that sets up Playwright end-to-end testing: config, folder structure, an example spec, and a CI workflow. It detects the project framework before generating any files. CX Codex +1 15installs linkedin-skills Builds an organic LinkedIn presence without automation or bots. It routes your requests across five lanes, covering profile rewrites, strategy, and drafts. CX Codex +1 12installs skillopt-sleep skillopt-sleep is a Claude Code skill that learns from past sessions and proposes memory or skill updates. It replays recurring tasks offline and tests proposed edits. CX Codex +1 12installs deep-learning-book deep-learning-book is a Claude Code skill for studying the Deep Learning textbook and applying its ideas to model training. It plans chapter sequences, diagnoses training failures, and calculates model costs. CX Codex +1 12installs

Project sponsors

Companies that keep this analytics open