skill-doctor

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.

Quality

88%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

—

The risk profile of this skill

Quality

Content

88%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is a well-structured, concise, and highly actionable workflow with strong validation checkpoints. Its main weakness is a packaging gap: step 2 and the references section cite a scorers/ directory that is missing from the bundle.

Suggestions

Ship the scorers/efficiency.md and scorers/code-quality.md rubric files referenced in step 2 and the References section, or correct the paths to where they actually live, so the scoring step is executable as written.

Consider naming the implicit Collect step in the description so the what-coverage is fully comprehensive (currently only Score/Draft/Render are stated).

Add a one-line note in the References section confirming the scorers/ rubrics are present locally vs. fetched upstream, so the local-only contract is unambiguous for the scoring inputs.

Dimension	Reasoning	Score
Conciseness	Lean and token-efficient: terse numbered steps, compact command snippets, a tight hard-rules list and a scripts table, with no padding of concepts Claude already knows.	5 / 5
Actionability	Copy-paste-ready commands with explicit paths ($RUN/inventory.json, $RUN/transcripts/) and a scripts table, but step 2 points to scorers/efficiency.md and scorers/code-quality.md which are absent from the bundle, breaking executability of the scoring step.	4 / 5
Workflow Clarity	Five clearly sequenced steps with explicit validation checkpoints and feedback loops ('if sessions_sampled is 0 ... stop', 'Exit 4 is a stop: fix what it names and re-run'), satisfying the destructive/batch validation requirement.	5 / 5
Progressive Disclosure	Clear overview with well-signaled one-level-deep references (references/.md and assets/.json all resolve) and a scripts table, but two referenced core paths (scorers/efficiency.md, scorers/code-quality.md) do not exist in the bundle, a navigation/packaging gap.	4 / 5
	Total	18 / 20 Passed

Description

87%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is specific, trigger-rich, and clearly distinct, with an explicit 'Use when' clause answering both what and when. The only minor gap is the unstated collection step, keeping specificity just below the top anchor.

Dimension	Reasoning	Score
Specificity	Lists several concrete actions ('scores recent local Claude Code / Codex sessions against efficiency and code-quality rubrics', 'drafts skill changes gated by a deterministic aggregator', 'renders one local shareable report') but omits the harvest/collect step, leaving a minor coverage gap.	4 / 5
Completeness	Explicitly answers both what (scores sessions, drafts edits, renders report) and when via a concrete 'Use when the user wants... asks... or wants...' trigger clause.	5 / 5
Trigger Term Quality	Natural trigger phrases a user would say are present ('wants their agent setup graded', 'asks which installed skills are actually working', 'wants evidence-backed skill edits'); good coverage though a few synonyms (e.g. 'audit', 'review my setup') are missing.	4 / 5
Distinctiveness Conflict Risk	Clear niche — grading an agent setup from real local session history with evidence-backed edits — with distinct triggers and minimal overlap with adjacent skills.	5 / 5
	Total	18 / 20 Passed

Validation

87%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning
relative_links	Relative link issues: 2 missing	Warning

	Total	14 / 16 Passed

Repository: alirezarezvani/claude-skills
Path: engineering/skill-doctor/skills/skill-doctor/SKILL.md
Commit: 19392f7

Reviewed: ~5 hours ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.