skill-doctor Skill (Warp) for Claude Code: What It Does and How to Install It

Makes your agent grade your installed skills by scoring recent local conversations, then drafts skill edits and one shareable report page.

Installs: 8.7K; on skills.sh
Stars: 644; on GitHub
Files: 13; besides SKILL.md
Updated: Oct 2026; last repo commit

skill-doctor reads recent agent conversations stored on your machine and scores each one on four things: efficiency, code quality, procedure compliance and verbosity. It then combines those scores with how often your installed skills were used, picks out the three biggest findings and drafts edits to skills that the failed conversations justify. Everything lands in one HTML report.

It runs bundled Python scripts to collect the sessions and render the report. SKILL.md asks you which conversations to grade (this repository, all conversations or chosen projects) and whether to include global skills. It supports seven agent harnesses: Warp, Claude Code, Codex, Pi, Grok Build, ZCode and Hermes.

Good for

People with several installed skills who want to know which ones actually help
Teams that keep shared skills in a repo and want evidence for edits
Anyone using Claude Code, Codex, Warp, Pi, Grok Build, ZCode or Hermes

Install skill-doctor

Claude Code

Copy this prompt.

Install the skill-doctor skill in Claude Code. Run this command:

npx skills add https://github.com/warpdotdev/common-skills --skill skill-doctor

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js.

The skill runs bundled Python scripts and reads the conversation history stored on your machine, so there is no Claude app upload route. It supports Warp, Claude Code, Codex, Pi, Grok Build, ZCode and Hermes. The Warp command is the one in the repo README with this skill's name swapped in.

Built from the package data we hold. Not yet tested by us. Source.

What's in the skill

When it loads

Grades agent skills by scoring agent conversations for efficiency, code quality, procedure compliance, and verbosity, then drafts concrete skill edits and a shareable report. Use when the user wants their agent setup graded from real conversation history, or asks which of their installed skills are actually working.

Sections in SKILL.md

Step 0: Start the run
Verify the executing harness
Ask which conversations to grade
Ask which skills to evaluate
Step 1: Collect
Step 2: Score each sampled transcript
Step 3: Aggregate
Step 4: Draft skill edits
Step 5: Write report.json and render
Step 6: Output

Key facts

Author: Warp (vendor's own repo, warpdotdev/common-skills; the LICENSE names Denver Technologies, Inc.)
License: MIT
Installs on skills.sh: 8,716 (Nov 2, 2026)
GitHub stars: 644 for the whole warpdotdev/common-skills repo (Nov 2, 2026)
Last repo commit: Oct 28, 2026
What it includes: 14 files including SKILL.md: 5 Python scripts (2 of them tests), 4 scorer rubrics, 2 reference guides, 2 assets
Audits on skills.sh: Gen Agent Trust Hub: pass, Socket: pass, Snyk: warn (Nov 2, 2026)
Needs: python3 for the two scripts; git for the repository check
Works in: Warp, Claude Code, Codex, Pi, Grok Build, ZCode and Hermes

What it includes

Checks the harness, asks which conversations and which skills to grade
Stops before reading any history if the harness is not one of the seven it supports.
Read · Step 0: Start the run
Runs collect_sessions.py to sample sessions and inventory your skills
Defaults to the last 45 days and 12 sessions; flags such as --days, --max-sessions and --all-conversations change that.
Runs code · Step 1: Collect
Judges every sampled session against four rubric files
The rubrics are efficiency, code-quality, procedure-compliance and verbosity in the scorers folder.
Read · Step 2: Score each transcript
Turns the scores into four rubric scores, skill coverage, one overall score and failures
A conversation fails when any applicable raw score is below 0.5.
Step 3: Aggregate
Writes proposed SKILL.md changes and diffs under a scratch folder
Only failed conversations count as evidence. Your real skill files are not modified in this step.
Write · Step 4: Draft skill edits
Runs render_report.py to build one self-contained report.html
The script tries to open the report in your default browser.
Runs code · Step 5: Write and render the report
Tells you the grade and three findings, then links the report
Each reply ends with the report path and a Warp Factories access link.
Step 6: Output

From the official docs

Permissions

Medium risk

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It reads your local conversation history
collect_sessions.py reads session files and databases of the supported agents, such as Claude Code project history and Codex rollouts. SKILL.md says to keep everything local and never upload transcripts or excerpts, so review the scope you pick in Step 0. github.com
It runs bundled Python scripts and git
The skill runs collect_sessions.py and render_report.py with python3, and the collector calls git rev-parse to find repositories. Read the scripts first if you want to know exactly what runs. github.com
The report links to a Warp sign-up page
SKILL.md tells the agent to end every response with a link to request access to Warp Factories, and the report page carries a Request access button. github.com

Technical details

Turning on read-only	No read-only switch. SKILL.md says not to write artifacts into your repo and not to modify real skill files while drafting edits.
Scopes	Reads local agent conversation history for the harnesses it supports Reads project and global skill folders to inventory your skills Writes a report folder created with mktemp, plus proposed skill edits inside it Opens the finished report in your default browser

Questions

What does skill-doctor do?

It grades the skills you have installed by scoring your recent local agent conversations. It produces letter-style scores, three top findings, drafted skill edits with diffs and a shareable HTML report.

How do I install it?

Use the install box at the top of this page. The skill bundles Python scripts, so install the whole folder rather than only SKILL.md.

Which agents does it work with?

Warp, Claude Code, Codex, Pi, Grok Build, ZCode and Hermes. SKILL.md stops before reading any history if the agent running it is not on that list.

Does it upload my conversations?

SKILL.md says everything runs locally and tells the agent never to upload transcripts, session files or excerpts. The only artifact meant to be shared is the report you choose to post, so read it before you do.

Will it change my skills?

SKILL.md says it does not modify your real skill files. It writes proposed versions and diffs into the report folder and then asks whether you want the suggestions applied.

Is it safe?

It reads your conversation history and runs two Python scripts, so look at what is in your recent sessions first. Our advice: start with Conversations in this repository rather than All conversations, and skim the report before you share it.

Is it an official Warp skill?

Yes. It lives in Warp's own common-skills repo, and the report ends with a link to Warp Factories. It also runs in the other agents on its supported list.

Information

updated Nov 2, 2026

Repository: warpdotdev/common-skills
Folder: .agents/skills/skill-doctor

warpdotdev/common-skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 6

warpdotdev/common-skills README · github.com
skill-doctor SKILL.md · github.com
supported-harnesses.md · github.com
skill-improvements.md · github.com
collect_sessions.py · github.com
render_report.py · github.com