review-docs

Review documentation for quality, clarity, SEO, and technical correctness. Optimized for Docus/Nuxt Content but works with any Markdown documentation. Use when asked to: "review docs", "check documentation", "audit docs", "validate documentation", "improve docs quality", "analyze documentation", "check my docs", "review my documentation pages", "validate MDC syntax", "check for SEO issues", "analyze doc structure". Provides actionable recommendations categorized by priority (Critical, Important, Nice-to-have).

Quality

79%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./docs/skills/review-docs/SKILL.md

Quality

Content

67%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 well-organized, actionable review workflow with good progressive disclosure and a clear step sequence. Its main weakness is conciseness: the report template is inlined despite an existing asset, creating redundancy that could be trimmed.

Suggestions

Replace the inlined ~150-line report template in Step 5 with a concise pointer to assets/report-template.md to remove duplication and improve token efficiency.

Trim or consolidate the 'Quick Reference / Most Common Issues' section, which overlaps with references/technical-checks.md, or explicitly mark it as a summary pointer.

Add an explicit validate->fix->retry feedback loop for batch review operations (e.g., re-run validation after applying fixes) to strengthen workflow clarity.

Dimension	Reasoning	Score
Conciseness	Mostly efficient and free of 'concepts Claude already knows' padding, but it could be tightened: the full ~150-line report template is inlined in Step 5 despite an existing assets/report-template.md, and the 'Quick Reference / Most Common Issues' list restates technical-checks content.	3 / 5
Actionability	Provides concrete detection indicators (package.json deps, config files, numbered-directory patterns), specific validation rules (u- prefix, required frontmatter fields), and an exact report format, with only minor gaps where full rules are deferred to reference files.	4 / 5
Workflow Clarity	Clear 5-step sequence with checkpoints (the 'Verify Core Files' checklist, project-type adaptation), though it lacks an explicit validate->fix->retry feedback loop for the batch review process and defers some validation detail to reference files.	4 / 5
Progressive Disclosure	Well-structured into 5 step sections with clearly signaled, one-level-deep references (technical/clarity/seo/structure/i18n-checks plus report-template), all verified to exist; the inlined report template duplicates the asset file, a minor organization gap.	4 / 5
	Total	15 / 20 Passed

Description

91%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, complete description that pairs a concrete capability statement with an extensive list of natural trigger phrases and explicit 'Use when' guidance. Minor overlap risk and slightly generic review verbs keep it just below perfect on two dimensions.

Dimension	Reasoning	Score
Specificity	Lists several specific review actions ("Review documentation for quality, clarity, SEO, and technical correctness", "validate MDC syntax", "check for SEO issues", "analyze doc structure") with minor gaps, as the verbs are review-domain and somewhat abstract.	4 / 5
Completeness	Explicitly answers both 'what' (review docs for quality/clarity/SEO/technical correctness with categorized recommendations) and 'when' ("Use when asked to:" with concrete trigger phrases).	5 / 5
Trigger Term Quality	Comprehensive coverage of natural trigger phrases with synonyms ("review docs", "check documentation", "audit docs", "check my docs") plus specific technical triggers ("validate MDC syntax", "check for SEO issues").	5 / 5
Distinctiveness Conflict Risk	Clear niche (documentation review, Docus/Nuxt Content optimization) with distinct triggers, but "review documentation" is somewhat broad and could minorly overlap with general review skills.	4 / 5
	Total	18 / 20 Passed

Validation

100%

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

Validation for skill structure

No warnings or errors.

Repository: nuxt-content/docus
Path: docs/skills/review-docs/SKILL.md
Commit: 5d75559

Reviewed: 3 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.