doc-review

Reviews documentation for factual accuracy

Quality

61%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.claude/skills/doc-review/SKILL.md

Quality

Content

61%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 admirably lean and lays out a sensible review workflow with a clear report format, but it is undermined by its two bundle references pointing at files that do not exist: the actual fact-checking method the skill depends on is missing entirely. Creating those files (or inlining a concrete verification method) would lift actionability, workflow clarity, and progressive disclosure together.

Suggestions

Create CHECKING.md and EXAMPLES.md (or remove the references), since both linked files are absent from the skill bundle.

Inline a concrete fact-checking method for toolhive claims (e.g., which source of truth to consult, commands to run, how to resolve a discrepancy) so the skill works even without the reference files.

Add an explicit verification checkpoint for the link-checking step (e.g., enumerate every link, confirm the target file exists, and compare linked content against the claim) to close the workflow's validation gap.

Dimension	Reasoning	Score
Conciseness	The body is ~25 lean lines with no explanation of concepts Claude already knows and no padding (e.g. "Read the documentation you are instructed to review", "Do not suggest inline changes"), matching the 'every token earns its place' anchor; the only flaw is trivial overlap between steps 2 and 3, which does not rise to level 4's 'minor instances of over-explanation'.	5 / 5
Actionability	The instructions specify what to check concretely ("all claims about how toolhive works are accurate", "all links point to existing files and the content of the links matches"), but the how-to for fact-checking is delegated to [CHECKING.md](CHECKING.md) and [EXAMPLES.md](EXAMPLES.md), neither of which exists in the bundle, leaving key execution details missing — matching the 'some concrete guidance but incomplete' anchor rather than level 4's minor gaps.	3 / 5
Workflow Clarity	A clear sequence is present (read the docs, verify claims, verify examples/formatting, verify links, report findings as a todo list) with a concrete report format, but the central fact-checking step depends on the missing CHECKING.md, so the workflow has an implicit gap with no explicit checkpoints — matching anchor 3 rather than 4's 'most checkpoints present'.	3 / 5
Progressive Disclosure	The body correctly signals one-level-deep references ([CHECKING.md](CHECKING.md) and [EXAMPLES.md](EXAMPLES.md)) under a dedicated section, but scoring against the actual bundle structure shows no references/, scripts/, or assets/ directories and neither referenced file exists, so the disclosure structure is nominal and non-functional — closer to 'minimal structure' (2) than to the functioning-but-imperfect organization of level 3.	2 / 5
	Total	13 / 20 Passed

Description

45%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 communicates a clear core purpose (fact-checking documentation) but stops there. It lacks any 'when to use' trigger guidance, natural trigger phrases like "fact-check", and the specificity (e.g., that it targets toolhive docs) needed to distinguish it from other review skills.

Suggestions

Add a 'Use when...' clause with concrete triggers, e.g. "Use when asked to fact-check, verify, or review documentation for accuracy."

Include natural trigger terms and synonyms users would actually say ("fact-check", "verify the docs", "documentation review", "accuracy check").

Name the target scope (toolhive documentation) in the description to reduce overlap with generic review/edit skills and improve distinctiveness.

Dimension	Reasoning	Score
Specificity	"Reviews documentation for factual accuracy" names the domain and a single generic action, matching the anchor for minimal/generic actions rather than the 1-2 concrete actions of level 3; it is not level 1 because it is not pure abstraction.	2 / 5
Completeness	The description has a clear 'what' ("Reviews documentation for factual accuracy") but no 'Use when...' clause or equivalent trigger guidance, which caps completeness at 3 per the judging guidelines; it is not level 2 because the 'what' is not vague.	3 / 5
Trigger Term Quality	"documentation" and "factual accuracy" are relevant keywords, but the natural phrases users would say ("fact-check", "verify the docs", "docs review") are missing, matching the 'some relevant keywords but missing common variations' anchor rather than the good coverage of level 4.	3 / 5
Distinctiveness Conflict Risk	"Reviews documentation" is somewhat specific but overlaps with general code-review, doc-editing, and review skills, and the description does not mention toolhive or any distinct trigger that would carve a niche, so it sits at 'could still overlap with similar skills' rather than the mostly-distinct level 4.	3 / 5
	Total	11 / 20 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
relative_links	Relative link issues: 2 missing	Warning

	Total	15 / 16 Passed

Repository: stacklok/toolhive
Path: .claude/skills/doc-review/SKILL.md
Commit: 4c866b5

Reviewed: 8 days 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.