grade the agent setup from real sessions
skill-doctor grades your agent setup from real, local Claude Code and Codex session history. It scores sessions against efficiency and code-quality rubrics, proposes evidence-backed skill edits, and renders a single self-contained HTML report.
✨ What it does
- Harvests and redacts local session transcripts from Claude Code and Codex.
- Scores sessions against two rubrics (efficiency and code-quality) using LLM judges.
- Detects skill usage and coverage across your installed skills.
- Drafts proposed skill edits with diffs, gated by a deterministic aggregator.
- Generates a self-contained HTML report with dark mode and print-to-PDF.
- Enforces strict privacy: everything runs locally, nothing is uploaded.
🎯 When to use it
- When you want to know how well your agent setup is performing based on actual session history.
- When you suspect some installed skills are not being used effectively or are missing.
- When you want to make data-driven improvements to your skills based on observed failures.
- When you need a shareable report on your agent's efficiency and code quality.
🚀 How to use
Run from the repo being graded. Trigger by asking to grade your agent setup or by invoking the skill directly. The skill expects optional arguments like --repo PATH or --days N. It runs a series of scripts to collect sessions, score them, propose edits, and render a report. Example prompts:
Grade my agent setup from the last 30 days.
skill-doctor --repo /path/to/repo --days 90
📄 Output: A self-contained HTML report (report.html) with the grade, top findings, and proposed skill edits.
📦 Add this skill to Claude Code
# 1. Get the skills repo
git clone --depth 1 https://github.com/alirezarezvani/claude-skills /tmp/claude-skills
# 2. Copy this skill into your project (or ~/.claude/skills for all projects)
mkdir -p .claude/skills
cp -r /tmp/claude-skills/engineering/skill-doctor/skills/skill-doctor .claude/skills/skill-doctorSkill source: engineering/skill-doctor/skills/skill-doctor/SKILL.md
⚠️ Good to know
Requires recent session history; if none found, the skill will stop and suggest adjusting the time window or repo path.
❓ FAQ
What happens if no sessions are found?
The skill tells you there is nothing recent to score and suggests using --days 90 or --repo to find more.
Can I apply the proposed skill edits automatically?
No, the skill only proposes edits and asks for your explicit per-skill approval before applying them.
Is my session data uploaded anywhere?
No, everything runs locally. Transcripts are redacted and never uploaded; only the report you choose to share is shareable.
🤖 Overview, features, install steps and FAQ were generated from the project's SKILL.md on Sep 4, 2026. Always check the original source before running commands.