CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

review-article

Review a docs article

Quality

56%

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 ./.github/skills/review-article/SKILL.md
SKILL.md
Quality
Evals
Security

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 an efficient, well-scoped instruction-only skill: a concrete checklist of review tasks plus a clearly specified output format. Its main weaknesses are execution gaps (how to test commands and code samples, no accessibility checks despite an Accessibility output category) and an implicitly sequenced workflow without consolidation checkpoints.

Suggestions

Specify how to perform the technical checks — e.g. 'Run code samples and CLI instructions in a sandbox; note any environment assumptions or missing prerequisites' — to close the actionability gaps.

Add accessibility review tasks (heading structure, alt text, link text, color contrast) so the required 'Accessibility' output category has corresponding instructions.

Number the workflow phases explicitly (style review → technical validation → structure evaluation → consolidated report) and briefly define what each output category should contain.

DimensionReasoningScore

Conciseness

The body is a lean checklist with no explanations of concepts Claude already knows and every bullet instructs an action. Minor trims are possible — 'actionable feedback for improvement' is restated as 'suggest concrete improvements with examples', and 'without redundancy or repetitive language' is itself redundant — matching 'Efficient; minor instances of over-explanation that could be trimmed'.

4 / 5

Actionability

The guidance lists specific checks (verify code samples, confirm API references, check heading hierarchy) and a well-defined output format, but key details are missing: 'Test command-line instructions' gives no method, 'follow best practices' is vague, and the required 'Accessibility' output category has no corresponding review task. This matches 'Some concrete guidance but incomplete'.

3 / 5

Workflow Clarity

Three review task groups plus an explicit reporting step are present, but there is no explicit ordering across the phases and no checkpoints for consolidating findings before reporting, matching 'Steps listed but validation gaps; sequence present but checkpoints missing or implicit'. The destructive/batch cap does not apply since this is a read-only review skill, but it still does not reach 4's 'clear sequence'.

3 / 5

Progressive Disclosure

At ~30 lines with no bundle files, the body is appropriately compact and its single reference — the writing style guidelines at ../../instructions/docs-writing.instructions.md — is one level deep and clearly signaled. It falls short of 5 because the task groups and output spec lack section headers, and the referenced file lives outside the skill bundle, making it fragile and unverifiable.

4 / 5

Total

14

/

20

Passed

Description

36%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 extremely terse: it identifies the domain (docs articles) and a single generic action, but omits any concrete capabilities, trigger guidance, or synonyms. It reads closer to the bad examples ('Helps with documents') than the good ones, and would rarely be selected confidently over competing review skills.

Suggestions

Add an explicit trigger clause, e.g. 'Use when the user asks to review, proofread, or audit a documentation article, tutorial, or docs section.'

Enumerate the concrete actions the skill performs, e.g. 'Checks style-guide adherence, verifies code samples and CLI instructions, validates API references, and evaluates structure, accessibility, and SEO.'

Include natural synonyms and variations users would say — 'documentation', 'docs', 'technical writing', 'article', 'tutorial' — to improve trigger-term coverage and distinctiveness.

DimensionReasoningScore

Specificity

"Review a docs article" names the domain but offers only the generic action "Review" — no concrete review activities (style checks, code validation, structure evaluation) are stated, matching the anchor 'Names the domain but actions are minimal or generic'. It is not a 3 because no 1-2 concrete actions are enumerated.

2 / 5

Completeness

The 'what' is vague — "Review" does not say what the review covers — and there is no 'when'/trigger clause at all, matching 'Has a vague what and no when'. The missing 'Use when...' guideline also caps this dimension at 3, and it falls below that cap.

2 / 5

Trigger Term Quality

The terms "review", "docs", and "article" are natural phrases a user might say, but common variations and synonyms ("documentation", "technical writing", "tutorial", "proofread") are missing, matching 'Some relevant keywords but missing common variations or synonyms'. Not a 4 because coverage is only three terse words with no synonym breadth.

3 / 5

Distinctiveness Conflict Risk

"docs article" carves out a documentation-review niche, but the bare verb "Review" leaves overlap risk with code-review and generic review skills, matching 'Somewhat specific but could still overlap with similar skills'. Not a 4 because nothing distinguishes it from other review-type skills.

3 / 5

Total

10

/

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

relative_links

Relative link issues: 1 suspicious

Warning

Total

14

/

16

Passed

Repository

microsoft/vscode-docs

Path

.github/skills/review-article/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.