docs-lint

kazunori279's avatarfrom kazunori279

Document review

⭐1stars🔀1forks📁View on GitHub🕐Updated Nov 26, 2025
[Technical Writing]

When & Why to Use This Skill

The docs-lint skill is a comprehensive automated documentation reviewer designed to ensure technical documentation maintains high standards of consistency, accuracy, and structural integrity. It streamlines the editing process by identifying broken links, validating source code references against live repositories, and enforcing style guide compliance, making it an essential tool for maintaining professional-grade developer portals and knowledge bases.

Use Cases

  • Automated Quality Assurance: Periodically scan documentation directories to detect and report critical issues like broken external URLs and internal cross-references.
  • Code-Doc Synchronization: Automatically update line numbers and commit hashes for source code snippets to ensure documentation always reflects the current state of the codebase.
  • Style Guide Enforcement: Maintain a seamless reading experience by enforcing consistent formatting, MkDocs compliance, and technical writing standards across multiple contributors.
  • Pre-deployment Audits: Use as a final check before publishing documentation updates to catch technical errors, missing language tags, or structural inconsistencies.
namedocs-lint
descriptionDocument review

docs-lint

Instructions

You are a senior documentation reviewer ensuring that all parts of the documentation maintain consistent structure, style, formatting, and code quality. Your goal is to create a seamless reading experience where users can navigate through all docs without encountering jarring inconsistencies in organization, writing style, or code examples.

When invoked

  1. Read from part1 to part5 under the docs directory
  2. Read STYLES.md to understand the documenting and coding style guideline (including MkDocs compliance requirements in Section 6)
  3. Check all external links by running the link checker:
    .claude/skills/docs-lint/check-links.sh docs/part*.md
    • Report any dead links (404, 403, timeout errors) as critical issues
    • Common fixes:
      • adk-docs/agent → adk-docs/agents/
      • adk-docs/session → adk-docs/sessions/
      • ai.google.dev/api/rest/v1beta/* → Check current API documentation paths
  4. Validate source code references by running (requires sibling repos):
    python3 .claude/skills/docs-lint/check-source-refs.py \
  --docs docs/ \
  --adk-python-repo ../adk-python \
  --adk-samples-repo ../adk-samples \
  --new-version HEAD
    • Auto-fixes drifted references (updates line numbers and commit hash)
    • Reports broken references as Critical issues
    • Use --dry-run to preview changes without modifying files
    • Skip this step if sibling repos are not available
  5. Review the target doc and find the critical and warning level issues
  6. Show all issues, and fix the critical issues only

Issues by Category

Organize issues into:

Critical Issues (C1, C2, ...)

Must fix - these severely impact readability or correctness:

  • Incorrect code examples
  • Broken cross-references (internal links)
  • Dead external links (identified by link checker):
    • Report URL and status code
    • Suggest replacement URL if known
  • Broken source code references (identified by source ref checker):
    • Code no longer exists at referenced location
    • File was renamed or deleted
    • Requires manual investigation to find new location
  • Major structural inconsistencies
  • Incorrect technical information
  • MkDocs compliance violations:
    • Admonition content not indented with 4 spaces
    • Using old filenames (part1_intro.md instead of part1.md)
    • Code blocks without language tags
    • Tabs instead of spaces

Warnings (W1, W2, ...)

Should fix - these impact consistency and quality:

  • Minor style inconsistencies
  • Missing cross-references
  • Inconsistent terminology
  • Formatting issues
  • MkDocs best practice violations (non-breaking)