AgentSkillsCN

doc-validate

依据项目规范对文档文件进行验证。检查前言、Markdown 格式、链接以及内容结构。适用于在提交前验证文档，或对现有文档进行审计时使用。

SKILL.md
--- frontmatter
name: doc-validate
description: Validate documentation files against project standards. Checks frontmatter, markdown formatting, links, and content structure. Use to verify docs before committing or to audit existing documentation.
argument-hint: [path] [--fix]
allowed-tools: Read, Bash, Glob, Grep, Edit

Validate Documentation

Validate documentation files against the project's documentation standards.

Instructions

  1. •

    Determine scope:

    • •If a specific path is given, validate that file/directory
    • •If no path given, validate all docs in docs/ and example/
  2. •

    Run the validation script if available:

bash
python scripts/validate_docs.py $ARGUMENTS
  1. •If script unavailable, perform manual checks:

Frontmatter Validation (Critical)

Check each markdown file for:

  • • YAML frontmatter exists (between --- markers)
  • • title field present and is a string
  • • category field present and is a string
  • • tags field present and is an array
  • • order field present and is an integer

Markdown Formatting (Critical)

  • • Only one H1 (#) per document
  • • No skipped header levels (H1 -> H3 without H2)
  • • All code blocks have language specified
  • • Line length under 100 characters (except URLs, code, tables)

Content Structure (Warning)

  • • H1 matches the title frontmatter field
  • • Introduction present after H1
  • • Table of contents for docs with >3 sections
  • • Related resources section at end

Links (Critical)

  • • Internal links use relative paths with .md extension
  • • Internal links resolve to existing files
  • • No "click here" link text

Output Format

Report findings in this format:

code
## Validation Results

### file-path.md
- [CRITICAL] Missing required frontmatter field: tags
- [WARNING] Line 45 exceeds 100 characters
- [INFO] Consider adding table of contents

### Summary
- Files checked: X
- Critical issues: X
- Warnings: X
- Passed: X

Severity Levels

LevelAction RequiredExamples
CRITICALMust fix before commitMissing frontmatter, broken links, no H1
WARNINGShould fixLong lines, missing TOC
INFOOptionalUnusual categories, style suggestions

Auto-Fix Mode

If --fix is specified, automatically fix:

  • •Missing language tags on code blocks (add text)
  • •Trailing whitespace
  • •Missing blank lines around lists
  • •Inconsistent list markers (convert to -)

Do NOT auto-fix:

  • •Missing frontmatter fields (requires human input)
  • •Broken links
  • •Content structure issues

Example Usage

code
/doc-validate                           # Validate all docs
/doc-validate docs/guides/              # Validate guides directory
/doc-validate docs/api/search.md        # Validate single file
/doc-validate docs/ --fix               # Validate and auto-fix