AgentSkillsCN

Documentation Freshness Audit

定期审核文档的新鲜度——及时发现过时的 README 文件、陈旧的 API 文档、孤立无援的引用，以及针对新代码缺失的必要文档。

SKILL.md
--- frontmatter
name: Documentation Freshness Audit
description: Audit documentation freshness — detect stale READMEs, outdated API docs, orphaned references, and missing documentation for new code
category: documentation
version: 1.0.0
triggers:
  - doc-audit
  - release-prep
  - quarterly-review
globs: "docs/**,**/README.md,**/CHANGELOG.md"

Documentation Freshness Audit Skill

Systematically audit all documentation for freshness, accuracy, and completeness.

Trigger Conditions

  • •Documentation audit is scheduled
  • •Release preparation begins
  • •Quarterly review cycle
  • •User invokes with "doc freshness" or "documentation-freshness"

Input Contract

  • •Required: Path to documentation root and source code root
  • •Optional: Last audit date for delta reporting

Output Contract

  • •Freshness score per document (last modified vs last code change)
  • •Stale documents (code changed but docs not updated)
  • •Orphaned documents (reference deleted code/features)
  • •Missing documents (new code without documentation)
  • •Dead links in documentation
  • •Overall documentation health score

Tool Permissions

  • •Read: All documentation files, source code (for cross-reference)
  • •Write: Freshness audit report
  • •Search: Grep for file references, URLs, code references in docs
  • •Shell: Run link checkers, markdown linters

Execution Steps

  1. •Inventory documents: List all .md files, OpenAPI specs, and inline doc comments
  2. •Check freshness: Compare last-modified dates of docs vs corresponding source files
  3. •Check references: Verify all file paths, function names, and URLs in docs still exist
  4. •Check coverage: For each exported function/endpoint, verify documentation exists
  5. •Check links: Validate all URLs and cross-references in documentation
  6. •Score: Assign health score based on freshness, coverage, and accuracy
  7. •Report: Produce audit report with specific files and remediation actions

Freshness Thresholds

  • •Fresh: Doc updated within 7 days of corresponding code change
  • •Aging: Doc updated 7-30 days after code change
  • •Stale: Doc not updated 30+ days after code change
  • •Orphaned: Doc references code that no longer exists

References

  • •.cursor/rules/048-documentation-standards.mdc