CtrlK
BlogDocsLog inGet started
Tessl Logo

review-docs

Use when reviewing the documentation a branch changes — AGENTS.md, READMEs and pages under wiki/ — or sweeping the whole wiki with --full. Cross-checks every claim a page makes against the code, finds wikilinks and heading anchors the branch broke, checks frontmatter and page shape, and reports D-C/H/M/L findings in the four-field format.

75

Quality

92%

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

SKILL.md
Quality
Evals
Security

Quality

Content

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

A high-quality instruction-only skill body: concrete commands for every step, a pre-committed report shape with a mechanical final verification, explicit fallbacks for absent tooling, and a single well-placed one-level-deep reference. The only cost is mild verbosity in a few rationale passages, which does not obscure the procedure.

Suggestions

Tighten the occasional rhetorical framing (e.g. the Step 0 justification and the edit-discipline paragraph in 'When a step cannot run') to recover tokens without losing the rules.

Consider moving the per-tier D-C/D-H/D-M/D-L definitions in 'Finding format' into references/checklist.md alongside the other tier-tagged rules to slim the body further.

DimensionReasoningScore

Conciseness

The body is dense and assumes Claude's competence — no explanations of git, Obsidian, or what documentation review is — with nearly every sentence carrying project-specific rules (tier definitions, MCP caveats, false-positive shapes). A few rhetorical framings ('a run that leaves a differently-shaped file has produced nothing, however good the review inside it') and the edit-discipline digression could be trimmed, which keeps it just below the 'every token earns its place' anchor.

4 / 5

Actionability

Fully executable throughout: a verbatim heredoc for the report skeleton, copy-paste git diff/comm/grep pipelines for claim cross-checking and broken-link detection, a claim-shape-to-check mapping table, a concrete finding block format, and a closing two-command verification with expected output ('Both must print 3'). Common cases are covered with specific commands rather than descriptions.

5 / 5

Workflow Clarity

Steps 0–5 are clearly sequenced with an explicit validation checkpoint at the end (the grep-count check before finishing) and real error-recovery paths: 'No step is a stop' gives a shell fallback for every check when the Obsidian MCP is absent, and known false-positive shapes are enumerated so findings can be corrected. The operation is read-only by default, so the destructive/batch cap does not apply.

5 / 5

Progressive Disclosure

The single bundle reference is real (references/checklist.md exists, 70 lines) and well signaled at the point of need — 'The full per-section checklist … is in references/checklist.md; on a --full sweep, work through it page by page.' It is exactly one level deep (the checklist points back to SKILL.md, not to further files), and the split is appropriate: the always-needed procedure stays inline while the per-page sweep checklist lives in the reference.

5 / 5

Total

19

/

20

Passed

Description

92%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 naming the exact doc surfaces, followed by a third-person enumeration of concrete capabilities and the deliverable format. The only weakness is mild — a few natural synonyms ('docs', '.md') are absent from the trigger vocabulary.

Suggestions

Add common user phrasings like 'docs' or 'stale documentation' to the trigger clause to broaden natural-term coverage.

Mention the '.md' extension or 'markdown' explicitly so file-type-based triggers match as well as path-based ones.

DimensionReasoningScore

Specificity

The description lists multiple concrete actions covering the skill's full scope — 'Cross-checks every claim a page makes against the code, finds wikilinks and heading anchors the branch broke, checks frontmatter and page shape, and reports D-C/H/M/L findings in the four-field format' — all in third person. Anchor 4 ('minor gaps in coverage') fits worse since no capability area of the skill is left unnamed.

5 / 5

Completeness

It opens with an explicit trigger clause — 'Use when reviewing the documentation a branch changes … or sweeping the whole wiki with --full' — and then answers 'what' with concrete capabilities (claim cross-checking, broken wikilinks/anchors, frontmatter and shape checks, tiered findings). Both what and when are explicit with concrete trigger phrases, matching the top anchor.

5 / 5

Trigger Term Quality

Good natural-term coverage: 'reviewing the documentation a branch changes', 'AGENTS.md', 'READMEs', 'pages under wiki/', '--full', 'wikilinks', 'frontmatter' are phrases a user would plausibly say. A few common variants are missing (e.g. 'docs', 'stale docs', '.md'), so it falls just short of the 'comprehensive coverage including synonyms and file extensions' anchor.

4 / 5

Distinctiveness Conflict Risk

A clear niche with distinct triggers: branch-scoped documentation review of named surfaces ('AGENTS.md', 'READMEs', 'wiki/') with its own finding taxonomy ('D-C/H/M/L findings in the four-field format'). It would not naturally trigger for code review or general doc editing; conflict risk with generic review skills is minimal.

5 / 5

Total

19

/

20

Passed

Validation

100%

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

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository
englishstreetventures/osn
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.