CtrlK
BlogDocsLog inGet started
Tessl Logo

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.

76

Quality

96%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

The canonical home for this skill is skill-doctor in alirezarezvani/claude-skills

SKILL.md
Quality
Evals
Security

Quality

Content

100%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.

An exemplary skill body: a five-step pipeline of copy-paste-ready commands with explicit stop conditions and an aggregator validation gate, hard rules that are all enforceable, and a clean one-level-deep reference structure. It assumes Claude's competence and spends every token on procedure and gates rather than explanation.

DimensionReasoningScore

Conciseness

Lean and efficient throughout — it assumes Claude's competence (never explains mktemp, diff -u, chmod 0600, or rubric judging) and every line is instruction, exit code, gate, or file pointer, matching the 5 anchor; there is no padded or over-explained section to trim, so not 4.

5 / 5

Actionability

Fully executable guidance: copy-paste commands with exact flags and paths (`python scripts/score_aggregator.py --inventory ... --emit-template > "$RUN/session_scores.json"`, `diff -u <current> <proposed>`), an exit-code table, and `--help/--output json/--sample`; no pseudocode or missing key details, matching the 5 anchor rather than 4's 'minor gaps'.

5 / 5

Workflow Clarity

Five clearly sequenced steps with explicit validation checkpoints and feedback loops: step 1's "if `sessions_sampled` is 0 ... and stop", step 4's "**Exit 4 is a stop**: fix what it names and re-run; never hand-edit report.json", and the step-5 gate "apply only on an explicit yes, skill by skill" — the exact validate→fix→re-run, only-proceed-when-valid pattern of the 5 anchor, so the batch/destructive cap at 3 does not apply.

5 / 5

Progressive Disclosure

The body is a clear overview with a dedicated references section listing eight one-level-deep, well-signaled paths (`scorers/efficiency.md`, `scorers/code-quality.md`, three `references/*.md`, three `assets/*.json`), each with a one-line purpose; no nesting or buried references, matching the 5 anchor.

5 / 5

Total

20

/

20

Passed

Description

96%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.

A strong description: explicit 'Use when' triggers phrased as natural user requests, concrete three-action pipeline, and a distinct local-session-evidence niche. Its only weakness is slight overlap risk with adjacent skill-improvement skills not resolved within the description text itself.

DimensionReasoningScore

Specificity

Lists multiple concrete actions covering the full pipeline — "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" — with comprehensive coverage, matching the 5 anchor rather than 4's 'minor gaps'.

5 / 5

Completeness

Explicitly answers both: "Use when the user wants..., asks..., or wants..." (when, with concrete trigger phrases) and the score→draft→aggregate→render pipeline (what), matching the 5 anchor's dual explicit what+when; the when-clause is as explicit as the anchor example, so not 4.

5 / 5

Trigger Term Quality

Natural user phrasings across three explicit trigger clauses ("agent setup graded from real conversation history", "which installed skills are actually working", "evidence-backed skill edits") plus tool names (Claude Code, Codex), giving synonym-level coverage; only trivially misses variants like "audit my skills", which the 4 anchor would require as 'a few natural terms missing'.

5 / 5

Distinctiveness Conflict Risk

The niche (grading installed skills from real session evidence) is clear, but "wants evidence-backed skill edits" carries minor overlap risk with adjacent skill-authoring/self-eval skills that the description text itself does not disambiguate — that separation lives in frontmatter metadata — fitting the 4 anchor rather than 5's 'minimal conflict risk'.

4 / 5

Total

19

/

20

Passed

Validation

81%

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

Validation — 13 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

relative_links

Relative link issues: 8 missing

Warning

referenced_paths_exist

Referenced path issues: 20 missing

Warning

Total

13

/

16

Passed

Repository
alirezarezvani/claude-skills
Reviewed

Table of Contents

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.