atoms-studio/nuxt-swiftsearch / .agents/skills/review-docs
review-docs
VerifiedReview 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).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 15.1 KB |
| assets/report-template.md | markdown | 5.2 KB |
| references/clarity-checks.md | markdown | 6.2 KB |
| references/i18n-checks.md | markdown | 5.9 KB |
| references/seo-checks.md | markdown | 6.8 KB |
| references/structure-checks.md | markdown | 7.9 KB |
| references/technical-checks.md | markdown | 12.0 KB |
references/structure-checks.md
View on GitHub# Structure and Organization Guidelines
Guidelines for evaluating documentation structure, organization, and navigation patterns.
## Content Hierarchy
### Recommended Directory Structure
```
content/
├── {locale}/
│ ├── index.md # Landing page (required)
│ ├── 1.getting-started/
│ │ ├── .navigation.yml
│ │ ├── 1.introduction.md
│ │ ├── 2.installation.md
│ │ └── 3.quick-start.md
│ ├── 2.guide/ # or 2.concepts/
│ │ ├── .navigation.yml
│ │ ├── 1.configuration.md
│ │ ├── 2.authentication.md
│ │ └── 3.deployment.md
│ ├── 3.api/ # if applicable
│ │ ├── .navigation.yml
│ │ └── 1.reference.md
│ └── 4.advanced/ # optional
│ ├── .navigation.yml
│ └── 1.customization.md
```
### Depth Guidelines
**Recommended:** Maximum 3 levels of nesting
- Level 1: Main sections (`1.getting-started/`)
- Level 2: Pages within sections (`1.introduction.md`)
- Level 3: Subsections via headings (H2, H3 within pages)
**Avoid:** Deep folder nesting (4+ levels) - use H2/H3 headings instead.
## Section Organization
### Standard Section Types
**1. Getting Started** (Always first)
- Introduction (what & why)
- Installation (prerequisites, commands)
- Quick Start / First Steps
- Project Structure (if applicable)
**2. Guide / Concepts** (Core documentation)
- Feature documentation
- Configuration guides
- Integration tutorials
- Best practices
**3. API / Reference** (If applicable)
- Component reference
- Composable reference
- Function reference
- Configuration options
**4. Advanced / Recipes** (Optional)
- Advanced patterns
- Customization guides
- Troubleshooting
- Migration guides
### Pages Per Section
**Guidelines:**
- **Minimum:** 2 pages per section (1 page = should be merged into another section)
- **Optimal:** 3-8 pages per section
- **Maximum:** 15 pages (beyond this, consider splitting into subsections)
**Red flags:**
- Section with 1 page only
- Section with 20+ pages (too broad, hard to navigate)
## Navigation Files
### .navigation.yml Structure
Each section directory should have `.navigation.yml`:
```yaml
title: Getting Started
icon: i-lucide-rocket
```
**Required fields:**
- `title`: Section display name in sidebar
- `icon`: Lucide icon (format: `i-lucide-{name}`)
### Icon Recommendations
| Section | Suggested Icons |
| ---------------- | ----------------------------------------------- |
| Getting Started | `i-lucide-rocket`, `i-lucide-play` |
| Guide / Concepts | `i-lucide-book-open`, `i-lucide-layers` |
| API / Reference | `i-lucide-code`, `i-lucide-book` |
| Advanced | `i-lucide-settings`, `i-lucide-wrench` |
| Deployment | `i-lucide-cloud`, `i-lucide-upload` |
| Troubleshooting | `i-lucide-alert-circle`, `i-lucide-help-circle` |
## Content Flow
### Logical Progression
Documentation should follow a learning path:
1. **Orientation** - What is this? Why use it?
2. **Setup** - How do I install it?
3. **Basics** - How do I use core features?
4. **Advanced** - How do I customize or extend?
5. **Reference** - Where can I find detailed API info?
### Page Structure
Each page should follow this pattern:
```markdown
---
frontmatter here
---
# H1 Page Title (matches frontmatter title)
Brief introduction (1-2 sentences describing what this page covers)
## First Major Topic (H2)
Content explaining the topic (200-400 words)
### Subtopic (H3)
Detailed information
## Second Major Topic (H2)
More content
## Next Steps
- Link to related pages
- Suggested reading order
```
### Next Steps / Related Content
**Every guide page should include:**
- Links to related documentation
- Suggested next pages
- Prerequisites or dependencies
**Examples:**
```markdown
## Next Steps
- [Configure your theme](/guide/configuration)
- [Add custom components](/guide/customization)
- [Deploy to production](/guide/deployment)
## Related
- [API Reference](/api/reference) - Detailed API documentation
- [Examples](/examples) - Real-world usage examples
```
## Cross-Referencing
### Internal Links
**Use relative links from the content root:**
✅ Good:
```markdown
Learn more about [authentication](/guide/authentication).
```
❌ Avoid:
```markdown
Learn more about [authentication](../guide/authentication.md).
```
### Link Patterns
**Inline links** for contextual references:
```markdown
Configure your app by setting up [environment variables](/guide/configuration#environment-variables).
```
**Callout links** for important related content:
```markdown
::note
This feature requires authentication. See the [Authentication Guide](/guide/authentication) for setup instructions.
::
```
**Frontmatter links** for primary related pages:
```yaml
---
links:
- label: API Reference
to: /api/reference
icon: i-lucide-book
---
```
## Consistency Checks
### Across Pages
- [ ] Consistent heading style (action-based in guide sections)
- [ ] Similar page structure (intro → content → next steps)
- [ ] Consistent code example format
- [ ] Consistent terminology usage
### Across Sections
- [ ] All sections have `.navigation.yml`
- [ ] Numbered directories for consistent ordering
- [ ] Similar depth levels (avoid 2 levels in one section, 5 in another)
- [ ] Consistent icon style (all Lucide, no mixing)
## Common Structure Issues
### Orphaned Pages
- Pages with no incoming links
- No path from landing page to this page
- Not included in navigation
**Fix:** Add links from parent/related pages
### Redundant Content
- Multiple pages covering the same topic
- Duplicate information across sections
- Overlapping content without clear differentiation
**Fix:** Consolidate or clearly differentiate purpose
### Missing Landing Page
- Section without index.md
- Direct jump to numbered pages (causes 404 on the section root URL)
**Fix:** Add `index.md` with section overview. If the page should not appear in the sidebar navigation, use `navigation: false` in frontmatter:
```yaml
---
title: Section Name
description: Overview of this section
navigation: false
---
```
This pattern is useful for section landing pages that serve as entry points (e.g. via redirect or direct URL) but shouldn't clutter the sidebar.
### Inconsistent Numbering
- Gaps in numbering (1, 2, 4, 5 - where's 3?)
- Duplicate numbers (1.intro.md, 1.install.md in same directory)
**Fix:** Renumber files consistently
### Poor Information Architecture
- Guide content in Getting Started section
- Basic setup in Advanced section
- API reference mixed with tutorials
**Fix:** Reorganize into appropriate sections
## Landing Page Structure
The main landing page (`index.md`) should include:
1. **Hero Section** - Project name, tagline, CTA
2. **Key Features** - 3-6 main features with icons
3. **Quick Start** - Minimal example or install command
4. **Links to Sections** - Getting Started, Guide, API
5. **Optional:** Showcase, testimonials, sponsors
**Example Structure:**
```markdown
---
title: Project Name
description: Project tagline
---
::u-page-hero
# Hero content
::
::u-page-section
# Features
:::u-page-grid
# Feature cards
:::
::
::u-page-section
# Quick Start
# Minimal code example
::
```
## Validation Checklist
- [ ] Landing page (index.md) exists at root of each locale
- [ ] All sections have `.navigation.yml` with title and icon
- [ ] Numbered directories follow consistent pattern (1., 2., 3.)
- [ ] Pages within sections are numbered consistently
- [ ] Maximum 3 levels of hierarchy (folders + headings)
- [ ] Each section has 2-15 pages (not 1, not 20+)
- [ ] Pages include "Next Steps" or related links
- [ ] No orphaned pages (all reachable from navigation)
- [ ] Logical progression (Getting Started → Guide → API → Advanced)
- [ ] Consistent heading depth (no lonely H4s without H3)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |