| name | review-docs |
| description | 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).
|
Review Docs
Comprehensive documentation review, optimized for Docus/Nuxt Content but compatible with any Markdown documentation.
Workflow Overview
This skill performs a 5-step review process:
- Detect Project Type - Identify Docus/Nuxt Content vs generic Markdown
- Analyze Structure - Map documentation organization, locales, sections
- Technical Validation - Check frontmatter, MDC syntax (if applicable), file naming
- Content Quality Review - Evaluate clarity, SEO, structure, i18n
- Generate Report - Provide categorized, actionable recommendations
Priority Levels
- Critical - Blocks deployment or causes errors (missing frontmatter, invalid MDC syntax)
- Important - Significantly impacts UX/SEO (poor metadata, passive voice, unclear headings)
- Nice-to-have - Polish and optimization suggestions (add callouts, improve examples)
Expectations
This skill generates a detailed report only. After reviewing, it offers to fix identified issues if requested.
Step 1: Detect Project Type
Goal: Determine if this is a Docus/Nuxt Content project or generic Markdown documentation.
Detection Indicators
Check for Docus/Nuxt Content:
-
package.json dependencies:
"docus" - Docus theme"@nuxt/content" - Nuxt Content module"@nuxtjs/mdc" - MDC support
-
Configuration files:
nuxt.config.ts or nuxt.config.js with @nuxt/content modulecontent.config.ts - Content collections configuration
-
Content structure:
content/ or docs/content/ directory.navigation.yml files in subdirectories- MDC syntax in markdown files (
::component-name)
-
Project structure:
- Numbered directories (
1.getting-started/, 2.guide/)
- Frontmatter with
navigation, seo fields
Project Type Classification
Type A: Docus/Nuxt Content Project
- All Docus-specific validations apply
- MDC component syntax checks (u- prefix requirement)
- Nuxt Content frontmatter structure
- Navigation files (.navigation.yml)
- Full technical validation
Type B: Generic Markdown Documentation
- Basic Markdown validation only
- Generic frontmatter (title, description, date, author)
- Standard Markdown syntax
- Focus on content quality (SEO, clarity, structure)
- No Docus-specific technical checks
Detection Output
After detection, note in the report:
Project Type: [Docus/Nuxt Content | Generic Markdown]
Validation Mode: [Full (Docus-specific) | Basic (Markdown-only)]
Adapt validation steps based on detected type:
- Type A (Docus): Execute all steps with full validation
- Type B (Generic): Skip Docus-specific checks, focus on content quality
Step 2: Analyze Documentation Structure
Locate Content Directory
Find the documentation content directory:
- Check for
docs/content/ (most common)
- Check for
content/ (root-level)
- Check for
app/content/ (alternative location)
Detect Locales
Identify language structure by examining subdirectories:
Single language (no locale subdirectories):
content/
├── index.md
├── 1.getting-started/
└── 2.guide/
Multi-language (locale subdirectories):
content/
├── en/
│ ├── index.md
│ ├── 1.getting-started/
│ └── 2.guide/
└── fr/
├── index.md
├── 1.getting-started/
└── 2.guide/
Detection logic:
- If immediate subdirectories are 2-letter codes (en, fr, es, de, etc.), it's multi-language
- If immediate subdirectories are numbered (1.getting-started), it's single language
List Documentation Sections
Identify all numbered directories within each locale:
1.getting-started/2.guide/ or 2.concepts/3.api/ or 3.essentials/4.advanced/ or 4.ai/
For each section, note:
- Section name
- Presence of
.navigation.yml file
- Number of pages (count
.md files)
- Page file names
Verify Core Files
Check for required files:
Create Structure Map
Document the structure for the report:
Project: [project-name]
Locales: [en, fr] (or "Single language")
Sections:
- 1.getting-started: 5 pages, .navigation.yml ✅
- 2.guide: 8 pages, .navigation.yml ✅
- 3.api: 3 pages, .navigation.yml ❌ (missing)
Step 3: Technical Validation
Adapt validation based on project type detected in Step 1.
For Docus/Nuxt Content Projects (Type A)
Perform full technical validation using references/technical-checks.md:
Validate:
- Frontmatter structure - Required:
title, description. Optional: navigation, seo, links
- MDC component syntax - All Nuxt UI components MUST have
u- prefix (::u-page-hero, :::u-button)
- Code block labels - All code blocks representing files need descriptive labels (
```vue [App.vue], ```ts [config.ts])
- Code language consistency - Code examples should match the project's language stack (e.g., TypeScript if the project uses TypeScript,
lang="ts" on Vue <script setup>)
- Package manager coverage -
::code-group install blocks must cover all package managers the project/ecosystem supports
- Code preview - Use
::code-preview for visually renderable examples (tables, lists, rendered markdown, etc.)
- Code group scope - Only group equivalent alternatives (e.g., package managers, framework variants) — don't mix unrelated steps (e.g., install command + config file)
- File naming - Numbered directories/files, kebab-case,
.navigation.yml in each section
- Hidden pages - Use
navigation: false for pages that should exist as routes but not appear in sidebar
Common Critical Errors:
- Missing
u- prefix: ::page-hero → should be ::u-page-hero
- Missing required frontmatter:
title, description
- Invalid
.navigation.yml structure
- Missing section
index.md causing 404 on section root URL
See references/technical-checks.md for complete validation rules, examples, and error patterns.
For Generic Markdown Projects (Type B)
Simplified validation - Skip Docus-specific checks:
Basic Frontmatter Validation:
- Check for common fields:
title, description, date, author, tags
- No strict requirements - just recommendations
- Flag if completely missing frontmatter
Standard Markdown Syntax:
- Validate basic markdown (headings, lists, links, code blocks)
- Check for broken internal links
- Verify image paths exist
Skip:
- MDC component syntax (not applicable)
- Nuxt Content frontmatter structure
.navigation.yml files- Docus-specific conventions
Focus on:
- Content quality (next step)
- SEO optimization
- Clarity and readability
- General structure
Step 4: Content Quality Review
This step applies to ALL project types (both Docus and generic Markdown).
Evaluate content quality across four dimensions. Refer to reference files for detailed checklists.
Clarity Review
Use references/clarity-checks.md to check:
- Voice & Tone: Active voice, present tense, second person
- Sentence Structure: 15-20 words target, avoid wordy phrases
- Paragraph Structure: 2-5 sentences, 200-400 words between headings
- Action-Based Headings: Page titles (H1) and headings (H2/H3) use action verbs for guides (Nuxt pattern)
- Examples: "Create Your First Module", "Configure your app", "Build a Plugin"
- Exceptions: Getting Started (nouns), API (function names), Concepts (descriptive)
- Terminology: Consistent naming, technical terms defined
- Code Examples: Complete, copy-pasteable, realistic, with file labels
SEO Review
Use references/seo-checks.md to check:
- Titles: 50-60 chars, keywords, unique
- Descriptions: 120-160 chars, compelling, unique
- Headings: Single H1, logical hierarchy (H1→H2→H3), descriptive
- URLs: Kebab-case, descriptive, stable
- Links: Descriptive anchors, "Next steps" sections
- Content Length: 300+ words for landing, 400+ for guides, 200-400 per section
- Images: Alt text, color mode variants
Structure Review
Use references/structure-checks.md to check:
- Hierarchy: Max 3 levels, logical progression
- Organization: 2-15 pages per section,
.navigation.yml present, appropriate icons
- Flow: Logical progression, "Next Steps" links, no orphaned pages
- Landing Page: Hero, features, quick start
- Consistency: Similar structure across pages
i18n Review (if multi-language)
Use references/i18n-checks.md to check:
- Parallel Structure: Same directories, files, page counts across locales
- Translation Completeness: Similar content length (±30%), same headings
- Navigation: Same icons, translated titles
- Locale-Specific: No mixed languages, correct internal links, translated comments
Step 5: Generate Report
Create a comprehensive review report using assets/report-template.md.
Adapt report based on project type:
- Docus/Nuxt Content: Include all sections (Technical, SEO, Clarity, Structure, i18n)
- Generic Markdown: Focus on content quality (SEO, Clarity, Structure), omit Docus-specific technical issues
Report Structure
# Documentation Review Report
**Generated:** [current date and time]
**Project:** [project name from package.json or directory]
**Reviewed:** [X] pages across [Y] sections in [locales]
---
## Executive Summary
- **Critical Issues:** [count] (must fix - block deployment/cause errors)
- **Important Issues:** [count] (significant impact on UX/SEO)
- **Nice-to-Have:** [count] (polish and optimization recommendations)
**Overall Assessment:** [1-2 sentence summary of documentation quality]
---
## Critical Issues
[List all Critical issues grouped by category]
### Technical: MDC Syntax Errors
#### Missing u- prefix on Nuxt UI components
**File:** `/content/en/1.getting-started/1.introduction.md:15`
**Problem:** Page hero component missing `u-` prefix
**Current:**
\`\`\`markdown
::page-hero
#title
Welcome
::
\`\`\`
**Should Be:**
\`\`\`markdown
::u-page-hero
#title
Welcome
::
\`\`\`
**Impact:** Component will not render, causing build errors
---
### Technical: Missing Frontmatter
[Similar format for each issue]
---
## Important Issues
[List all Important issues grouped by category: SEO, Clarity, Structure]
### SEO: Suboptimal Metadata
[Details with file paths and recommendations]
### Clarity: Passive Voice
[Details with examples and suggested rewrites]
### Structure: Poor Navigation
[Details with organizational recommendations]
---
## Nice-to-Have Suggestions
[List optimization suggestions by category]
### SEO Optimizations
- : [Suggestion]
: Consider adding callout for [specific content]
: Consider splitting into subsections
---
[Only if multi-language detected]
[Translation issues]
---
| Section | Pages (en) | Pages (fr) | Avg Words/Page |
|---------|------------|------------|----------------|
| Getting Started | [X] | [X] | ~[XXX] |
| Guide | [X] | [X] | ~[XXX] |
| Category | Critical | Important | Nice-to-Have | Total |
|----------|----------|-----------|--------------|-------|
| Technical | [X] | [X] | [X] | [X] |
| SEO | [X] | [X] | [X] | [X] |
| Clarity | [X] | [X] | [X] | [X] |
| Structure | [X] | [X] | [X] | [X] |
| i18n | [X] | [X] | [X] | [X] |
| | | | | |
---
[Call out 2-3 things done well]
Good use of callouts and code examples
Consistent MDC component usage
Well-organized section structure
---
[Specific actionable items]
[X] files
[Specific actionable items]
[X] files
[Specific actionable items]
[X] files
---
- I can automatically correct MDC syntax and frontmatter issues
- Point out which pages need clarity improvements, and I'll rewrite them
- I can update all titles and descriptions to optimal lengths
- If sections need reorganization, I can help restructure
- If you need i18n content completed
Report Generation Guidelines
Be specific:
- Include exact file paths and line numbers
- Show current vs. recommended code
- Explain why each issue matters (impact)
Be actionable:
- Provide clear fix instructions
- Include code examples
- Prioritize by impact
Be balanced:
- Highlight positive aspects
- Don't overwhelm with minor issues
- Focus on high-impact improvements
After generating the report:
- Offer to fix issues if the user requests
- Be ready to address specific categories or files
- Suggest starting with Critical issues
Quick Reference
Most Common Issues:
- Missing
u- prefix on Nuxt UI components (::page-hero → ::u-page-hero)
- SEO descriptions too short (need 120-160 chars)
- Passive voice in instructions ("can be done" → "do it")
- Generic headings ("Configuration" → "Configure your app")
- Code blocks missing file name labels (every block representing a file should have one)
- Code language not matching the project's stack (e.g., missing
lang="ts" on Vue <script setup> in a TypeScript project)
- Incomplete package manager coverage in
::code-group install blocks (check against the ecosystem/project)
- Unrelated steps grouped in
::code-group (e.g., install command + config file) — keep as separate blocks
- Missing
::code-preview where rendered preview would add clarity (tables, lists, etc.)
- Section landing page missing → 404 on section root URL (add
index.md with navigation: false if needed)
See reference files for complete checklists and examples.
