AgentSkillsCN

docs-audit

对单体仓库中的所有模块进行全面的文档健康审计。发现模块，逐一验证，并生成汇总合规报告。使用 --include-root 参数，还可验证仓库级别的文档结构。

SKILL.md
--- frontmatter
name: docs-audit
description: >
  Audit documentation health across all modules in the monorepo.
  Discovers modules, validates each, and produces an aggregate compliance report.
  Use --include-root to also validate the repo-level docs structure.
allowed-tools: Read, Bash(find *), Bash(ls *), Bash(cat *), Bash(grep *), Bash(wc *)
user-invocable: true

Docs Audit — Monorepo-Wide Documentation Audit

Audit documentation health across all modules in the monorepo and produce an aggregate compliance report.

Command

code
/docs-audit [--modules-dir <path>] [--format summary|detailed] [--include-root]

Arguments

ArgumentRequiredDescription
--modules-dir <path>NoRoot directory containing modules (default: packages or value from config)
--formatNoOutput format: summary (default) or detailed
--include-rootNoAlso validate the repo-level docs/ structure

Workflow

  1. •

    Parse arguments. Extract options from $ARGUMENTS. Use defaults from project configuration where not specified.

  2. •

    Discover modules. Find all subdirectories under the modules directory that appear to be modules (contain a docs/ directory, README.md, or CLAUDE.md).

    • •Filter out modules matching ignoredModules glob patterns from project config.
  3. •

    Determine module types. For each discovered module:

    • •Read the module's CLAUDE.md and look for the ## Module Type section
    • •If not found, use defaultModuleType from project config
    • •If neither available, report the module as "unknown type" and skip validation
  4. •

    Validate each module. For each module with a known type, run the structural validation:

    bash
    bash <plugin-root>/skills/scaffold/scripts/validate-structure.sh \
  --module-path <module-path> --type <type>

    Capture the results (present, missing, placeholder counts).

  5. •

    Validate root (if --include-root). Run:

    bash
    bash <plugin-root>/skills/scaffold/scripts/validate-structure.sh --root
  6. •

    Aggregate results. Compute:

    • •Total modules scanned
    • •Modules passing vs. failing
    • •Compliance rate (percentage)
    • •Most common gaps across all modules
  7. •

    Format output. Based on --format:

    • •summary: High-level statistics, common gaps, list of failing modules
    • •detailed: Per-module breakdown (same format as /validate) plus summary

    See reference/report-format.md for the complete output specification.

Configuration

The audit skill respects project-level configuration from .claude/settings.json:

SettingUsed For
modulesDirectoryDefault modules directory if --modules-dir not specified
defaultModuleTypeFallback module type if CLAUDE.md doesn't declare one
ignoredModulesGlob patterns for modules to skip
strictModeIf true, placeholder-only files are treated as failures

Reference

  • •reference/report-format.md — Complete specification of the audit output format