CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

skill-doctor

Environment diagnostics — check providers, auth, config, hooks, scheduler, and more

Quality

76%

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

Fix and improve this skill with Tessl

tessl review fix ./.claude/skills/skill-doctor/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

77%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 highly actionable with an exceptionally well-validated workflow — copy-paste commands, gated repairs, dry-run/apply flows, and post-repair verification loops. Its weaknesses are redundancy and monolithic structure: duplicated confirmation text, ~100 lines of inline reference-grade configuration detail, and no bundle files despite being well over the size where SKILL.md should become an overview pointing at separate materials.

Suggestions

Delete the duplicated Step 5 sentence about cache/PID/login/package/plugin-update confirmation (stated twice in consecutive paragraphs) and drop Step 4's --verbose example that repeats Step 1's final command.

Move the context/legacy intensity profile, project tier hint, remote session, and RUNTIME.md sections (~100 lines) into a references/ file, keeping SKILL.md focused on the diagnostic workflow and check-category overview.

Ship the 40-line plugin-root resolver as a scripts/ helper so per-category invocations in Steps 2-4 become standalone one-liners instead of requiring resolver reassembly.

DimensionReasoningScore

Conciseness

The body is mostly efficient and plugin-specific, but it could be tightened: the sentence 'Cache cleanup, stale PID cleanup, login flows, package installation, and plugin updates ... require explicit confirmation' appears nearly verbatim twice in Step 5, Step 4's --verbose example repeats Step 1's command, and roughly 100 lines of context/legacy-profile, tier, remote-session, and RUNTIME.md detail is reference-grade digression, plus a time-sensitive version note ('removed in v9.41.0'). It is not 2 because nothing explains concepts Claude already knows and the bulk is concrete, not padded fluff.

3 / 5

Actionability

Guidance is fully executable and copy-paste ready: a complete 40-line resolver script with error handling and a failure message, exact per-category doctor commands, install-deps commands, the JSON output contract, complete AskUserQuestion payloads, and concrete fix commands in the issues table. The 'replacement lines, not standalone shell calls' pattern for Steps 2-4 is explicitly instructed and unambiguous, leaving no real gaps.

5 / 5

Workflow Clarity

The five steps are clearly sequenced with explicit validation checkpoints and feedback loops: repair requires a --dry-run preview and explicit authorization, config repairs use a validated temp file plus atomic rename with keep-original-on-failure, and after repair the affected category is rerun first before offering a full scan. The exit-code contract (fail=1, usage errors=2, 'do not retry them as full scans') covers error recovery, and destructive cleanups are confirmation-gated so the missing-validation cap does not apply.

5 / 5

Progressive Disclosure

The skill ships no bundle at all — no references/, scripts/, or assets/ — so all 430 lines live in SKILL.md. Section structure itself is good (clear headers, tables), which rules out anchor 2, but content that clearly belongs in separate files is inlined: the 40-line resolver belongs in scripts/, and the context-profile, legacy-intensity, tier, remote-session, and RUNTIME.md sections (~100 lines of reference-grade detail) belong in a references/ file. This matches anchor 3 ('content that should be separate is inline'), and the under-50-line no-references exception does not apply.

3 / 5

Total

16

/

20

Passed

Description

66%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 solid, specific description that names the domain and five concrete check areas with natural 'check X' phrasing. Its main weakness is that the 'when to use' guidance is absent from the description field itself (delegated to a separate trigger field), capping completeness, and natural synonyms like 'doctor' or 'health check' are missing.

Suggestions

Append a 'Use when...' clause to the description itself (e.g., 'Use when something isn't working, after installing or updating the plugin, or before an important run') so the trigger guidance travels with the description field.

Fold one or two natural trigger synonyms — 'doctor', 'health check', 'troubleshoot my setup' — into the description to broaden natural-term coverage.

Replace the vague 'and more' tail with the remaining high-level category names (state, scheduler, cache, conflicts) or drop it entirely.

DimensionReasoningScore

Specificity

The description lists several concrete check targets ("check providers, auth, config, hooks, scheduler") with "and more" explicitly acknowledging minor coverage gaps, matching the 'several specific actions; minor gaps' anchor. It is not 5 because 'and more' hedges instead of comprehensively enumerating capabilities, and not 3 because it goes well beyond 1-2 concrete actions.

4 / 5

Completeness

The 'what' is clear ("Environment diagnostics — check providers, auth, config, hooks, scheduler, and more"), but the description field itself contains no 'Use when...' clause or equivalent trigger guidance — the when-guidance lives in a separate frontmatter trigger field, not the description. Per the rubric guideline, this caps completeness at 3.

3 / 5

Trigger Term Quality

Phrases like "Environment diagnostics", "check providers", "check auth", and "check hooks" are natural user phrasings, giving good keyword coverage. Common synonyms a user would actually say — 'doctor', 'health check', 'troubleshoot', 'why isn't it working' — are missing, keeping it below the comprehensive anchor 5.

4 / 5

Distinctiveness Conflict Risk

"Environment diagnostics — check providers, auth, config, hooks, scheduler" carves a mostly distinct diagnostic niche with only minor overlap risk against closely related setup/status/debug skills in the same plugin. It is not 5 because the description carries no distinct trigger phrases of its own to fully disambiguate from those siblings.

4 / 5

Total

15

/

20

Passed

Validation

87%

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

CriteriaDescriptionResult

frontmatter_unknown_keys

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

Warning

referenced_paths_exist

Referenced path issues: 2 missing

Warning

Total

14

/

16

Passed

Repository

nyldn/claude-octopus

Path

.claude/skills/skill-doctor/SKILL.md

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.