AgentSkillsCN

documentation-quality-checklist

为生成的文档页面制定质量验证清单。涵盖内容完整性、证据支撑、Markdown语法、图表校验以及交叉引用的一致性。在最终确定任何文档页面之前，务必使用此技能进行检查。

SKILL.md
--- frontmatter
name: documentation-quality-checklist
description: Quality validation checklist for generated documentation pages. Covers content completeness, evidence backing, markdown syntax, diagram validation, and cross-reference consistency. Use before finalizing any documentation page.
user-invocable: false

Documentation Quality Checklist

Validation criteria for generated documentation pages. Run through this checklist before writing any page to disk.

Content Completeness

  • • All required sections are present
  • • All required diagrams are generated and embedded
  • • No TODO or placeholder text remains
  • • Introduction provides context and purpose
  • • Conclusion summarizes key points

Evidence Backing

  • • Every major claim cites a source
  • • Code examples are real (from codebase, not invented)
  • • File references use correct paths
  • • Line numbers are accurate
  • • Evidence sources are listed in metadata

Markdown Syntax

  • • Headings have proper hierarchy (h1 → h2 → h3)
  • • Code blocks include language specification
  • • Tables are properly formatted
  • • Lists use consistent formatting
  • • No broken markdown syntax

Diagram Validation

  • • ASCII diagrams render correctly in monospace
  • • Diagram has descriptive title
  • • Diagram has explanatory caption
  • • Diagram content matches surrounding text
  • • Box widths are consistent

Cross-References

  • • Internal links use relative paths: [text](../../path/to/page.md)
  • • Referenced pages exist in sitemap
  • • External links are properly formatted
  • • Bidirectional references where appropriate
  • • Breadcrumb navigation included if appropriate

Word Count Guidelines

Page TypeTarget RangeNotes
Overview pages500-1000Concise, high-level
Architecture pages1000-2000Detailed with diagrams
Component/service pages800-1500Focused on single topic
Workflow pages600-1200Step-by-step with diagrams
Reference pages300-800Tables and lists

Quick Validation

For rapid checks, verify these critical items:

  1. •Required content exists - All sections and diagrams present
  2. •Evidence is real - Code examples from actual codebase
  3. •Links work - Cross-references match sitemap
  4. •Renders correctly - Markdown syntax is valid

Failure Criteria

A page should NOT be written if:

  • •Missing more than one required section
  • •No evidence sources cited
  • •Contains placeholder text (TODO, TBD, etc.)
  • •Markdown has syntax errors that break rendering
  • •Word count is below minimum for page type

Version: 1.0 Last Updated: 2026-01-22