Find the failure before deciding to change the instruction
Skill Doctor
Diagnose Skills from Conversation Evidence
Sample local agent conversations, score efficiency, code quality, procedure compliance and verbosity, then check whether specific failures justify a skill change. Deliver a local report and reviewable proposals.

Execution and collection
- This page: select $skill-doctor in Codex CLI / IDE
- Source IDs: warp, claude, codex, pi, grok, zcode, hermes
- Repository stars
- 636
- Checked
- Categories
- EngineeringProduct & Project
Start with one project, one source and a small sample
For a first run, use Codex history from the current project over the last week, cap scoring at four sessions, and evaluate project skills only. Check what entered the inventory before reading the low-score explanations. Neither a high grade nor three proposed edits is a required outcome.
Pick a task and get started
First confirm that your model environment is suitable for these records. Install and select skill-doctor from the project root. The first prompt names Codex as the source, sets the project scope and caps scoring at four sessions; that cap does not limit how many candidate logs the collector opens.
Use Codex history, a seven-day window and at most four scored sessions to establish what failed and what the evidence supports.
Install the complete Skill Doctor
Run at the project root and confirm skill-doctor and Codex. Without -g, installation is project-scoped. The pinned 1.7.4 installer requires Node.js 22.20+; skill content still comes from the repository at install time. Check existing same-name entries and the installation summary, keeping every supporting directory.
Read the author’s installation guidenpx skills@1.7.4 add warpdotdev/common-skills --skill skill-doctor -a codexCheck the files and reading scope
Confirm that .agents/skills/skill-doctor/ contains SKILL.md, scripts/, references/, scorers/ and assets/. Keep assets/pierre-diffs.js, which the report requires. In Codex in the same project, use /skills or type $ to select skill-doctor; restart if it has not appeared. Confirm conversation and skill scope before starting. An unsupported or unidentified executing host should stop before creating a report directory or reading history.
Read supported hosts, sources and directoriesGive your AI this first task
These three editorial examples have not been executed here. They need real local records you permit the agent to analyze. The flags configure collection; the agent supplies the judgments. None of the examples authorizes uploading records or applying proposals automatically.
$skill-doctor First confirm that the executing host is supported and that its model and tool data handling meets my requirements for local history. If that cannot be established, explain and stop before reading history. Choose the current Git repository for conversation scoring and project skills only. Collect with --harness codex, --days 7 and --max-sessions 4. Do not enable --include-global-skills or --include-subagents. Create a separate temporary REPORT_DIR following the author’s workflow. Write no report into the project and change no real skill. The collector parses recent candidates from the chosen source before project filtering; four sessions is not a log-reading limit. Inspect inventory.json for source, cwd, window, actual sample count and skill paths. If a same-named project appears to have been included, report the scope problem before scoring it as this project. Stop if no sessions were sampled and explain which scope setting could change. If no skills are found, keep coverage at zero and still assess the conversations. Apply all four rubrics to actual samples, recording each label, raw score and specific evidence in this run directory. Use insufficient_evidence when code changes are not visible. If no sample supports code-quality judgment, disclose the author’s raw 0.5 fallback, which becomes 0.75 in the report. Generate the five-dimension report using the documented formula. Define failures from applicable raw scores below 0.5. Draft only verified instruction gaps; do not fill an edit quota. Deliver the inventory, scoring evidence, report.json, report.html and any proposed files actually created. Check agreement among numbers, evidence and diffs, then provide local paths and the main findings. Upload nothing and apply no changes.
Check what you receive
- An inventory and individual raw scoring evidence with explicit scope and actual sample counts; no samples produce a clear stop.
- JSON and HTML reports using the five-dimension formula, disclosing truncation and insufficient code evidence.
- Proposed skills and diffs only when justified; a report with no suggestions is a valid outcome.
More about this skill
Skill Doctor turns “is this skill helping?” into a traceable workflow: choose the conversations and skills, collect local records, score each sample, group failures, and decide whether an instruction should change. The collector organizes evidence, the agent running the skill makes the judgments, and the renderer presents them. It does not run two skill versions to establish that a proposal improves results.
The current report has five dimensions: efficiency, code quality, procedure compliance, verbosity, and the share of sampled conversations with a detected skill. The first four are rubric judgments transformed into report scores; coverage comes from tool and path markers. The report can reveal recurring clues, but it cannot directly establish which model, project or skill version performs better.
A low score alone is insufficient grounds for a patch. A proposal must identify a missing, wrong or underspecified reusable instruction and explain how following it would have prevented an observed failure. Correct instructions that were ignored, model variance, and problems belonging in code or infrastructure do not justify more prompt text. Returning no changes can be the right outcome.
A run directory holds the inventory, condensed transcripts, scoring material, JSON and HTML reports. Qualified suggestions add complete proposed skill files and diffs. This stage of the author’s workflow leaves the real skills untouched; applying proposals is a later choice. The report can export a scorecard, but project names, evidence and proposed changes still need review before sharing.
Sources and verification
Sources checked
The pinned main skill, two references, four rubrics and three implementation scripts were read in full, with installation and invocation documentation checked. No user history was read, scripts run, report generated or export tested. Examples and source-derived dimensions are labeled.