Skill Doctor: inspect Agent Skills through real conversations

Purpose

Installing Agent Skills does not tell you whether an assistant uses them when needed. Skill Doctor, from Warp’s common-skills repository, examines selected local agent conversations and produces a report with draft skill edits tied to those conversations. The source Skill describes the workflow.

Its overall grade combines five measures: efficiency, code quality, procedure compliance, verbosity, and skill coverage. The first four are scored from sampled conversations; coverage checks whether any installed skill was detected in each sample. The weights differ. The report highlights three concrete findings and bases proposed edits on conversations that failed a scoring rule. These are the project’s methods, not results measured by this site.

When to use it

Use it when you maintain project or global skills and want to investigate missed triggers, missing checks, or repeated detours in recent work. You can select conversations from the current repository, chosen projects, or all local conversations. You can evaluate project skills alone or include global skills.

We think it is most useful when you have local conversation history and can review both the evidence and the proposed changes. A grade can point to work worth inspecting; it cannot replace your judgment about requirements or code.

Example

Imagine a team whose “before committing” skill should prompt the assistant to run tests, but several conversations end without that check. The team could ask a supported agent to run Skill Doctor over recent conversations in the repository and its project skills. After asking which conversations and skills to inspect, it samples local records, scores four aspects of each conversation, and calculates skill coverage. If a failed conversation never triggered the relevant skill, the report might suggest changing its trigger description. If a check was missing, it might draft a specific edit and diff.

This example is hypothetical; we have not run Skill Doctor on that team’s conversations. The source workflow requires suggestions to cite moments in failed conversations instead of adding generic advice to skill files.

Limitations

Code quality is scored only when a conversation shows code changes; otherwise the result is insufficient_evidence and is excluded from that average. If the chosen scope contains no recent sessions to score, the run stops and suggests a wider time window or different projects. Scores depend on sampled records and rubrics; they do not prove that a skill works for every task or that a draft edit is correct.

The source Skill says transcripts stay local. It writes reports and proposed skill files to a scratch directory and does not change installed skill files during the suggestion step. The user decides whether to share the report and should review it first. This describes the Skill’s intended procedure, not a security guarantee from this site about every execution environment or later sharing. If the executing agent is not confidently recognized as supported, the workflow stops before reading conversations.

Installation

The official README uses the skills CLI. Following its single-skill command format, this example installs Skill Doctor globally for Warp. This page only shows the command:

npx skills@latest add warpdotdev/common-skills --skill skill-doctor --agent warp --global

For another agent, check the supported harness list and the matching skills CLI agent option. Skill Doctor needs local conversation records it can read; installation alone does not create sessions to score. The workflow asks you to choose conversation and skill scopes before collection.