Automated documentation auditing - ensures CLAUDE.md coverage, updates stale docs, recommends structural improvements
/plugin marketplace add bryonjacob/aug/plugin install aug-dev@augThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Automated system to keep documentation complete, accurate, and current. Manages CLAUDE.md hierarchy and all project docs.
Documentation drifts from code. This skill:
.docsaudit.yamlTracks audit state for all docs.
Format:
version: 1
ignore:
- node_modules/**
- .git/**
- dist/**
- __pycache__/**
max_age_days: 90
audits:
README.md:
commit: abc123
date: 2025-11-19T10:30:00Z
scope: ["**/*"]
src/auth/CLAUDE.md:
commit: def456
date: 2025-11-15T09:00:00Z
# No scope = directory default (src/auth/**/*)
Bootstrap if missing:
Scope = glob patterns defining which files a doc describes
Every doc scopes to its directory:
README.md (root) → **/* (whole project)src/auth/CLAUDE.md → src/auth/**/*docs/api.md → docs/**/*Predictable, consistent, no special cases.
docs/api.md:
scope: ["src/api/**/*"] # Track API code, not docs dir
CONTRIBUTING.md:
scope: [] # Explicit empty = no code dependencies
Doc is stale if:
commitmax_age_days since dateBoth triggers checked.
Goal: Every meaningful directory has CLAUDE.md
Process:
Decision Criteria:
Ask: "Would CLAUDE.md help understand this?"
Consider:
If yes (even for 2-line doc) → create it.
Ignore only:
No file extension filtering - analyze actual content.
Goal: Un-ignore directories that grew meaningful
Process:
Examples of growth:
tests/fixtures/ added 10 complex test scenariosscripts/ now has deployment orchestrationutils/ grew from 1 to 8 helper modulesGoal: Update stale docs automatically
Process:
For each doc in audits:
Get scope (explicit or directory default)
Check staleness via TWO triggers:
# Code staleness
git diff <last-commit>..HEAD -- <scope-patterns>
# Time staleness
days_since(date) > max_age_days
If stale:
Update audit record:
audits:
path/to/doc.md:
commit: <new-HEAD>
date: <now>
Parallel processing: Use Task tool for multiple docs simultaneously.
Goal: Recommend structural improvements
Process:
Analyze overall doc structure, detect issues:
Consolidate:
Move:
docs/database.md with scope src/db/**/*Delete:
Split:
Merge:
Present recommendations, don't auto-apply - bigger decisions need human judgment.
Write final .docsaudit.yaml with:
All changes staged for git review.
When: Creating new CLAUDE.md file
Analysis:
Template:
# [Module Name]
## Purpose
[1-2 sentences: what this does]
## Key Components
- [file/class]: [purpose]
- [file/class]: [purpose]
## Dependencies
- Uses: [other modules]
- Used by: [other modules]
## Notes
[Important context, conventions, gotchas]
Keep concise:
Examples:
# tests/fixtures/auth
JWT tokens and auth payloads for testing.
Tokens are expired but have valid structure.
# scripts/deployment
Production deployment utilities.
Run via `just deploy <env>` - never manually.
Handles DB migrations, health checks, rollback.
When: Doc is stale (code or time)
Process:
Get changes:
git diff <last-commit>..HEAD -- <scope>
Summarize:
Read current doc:
Determine updates:
Rewrite:
Write updated doc
Preserve:
Update:
Structure:
Documentation Audit Report
Coverage (CLAUDE.md files):
Created (N):
+ path/to/new.md (reason)
Un-ignored (N):
+ path/to/unignored.md (reason)
Freshness (content updates):
Updated (N):
~ path/to/updated.md (summary)
Already current (N):
✓ path/to/current.md
Recommendations:
⚠ Issue: description
⚠ Issue: description
Files changed: N
Review: git diff
Commit: git commit -am "docs: automated audit"
Symbols:
+ Created/added~ Updated/modified✓ Already current⚠ RecommendationSystem defaults:
ignore:
- node_modules/**
- .git/**
- dist/**
- build/**
- __pycache__/**
- "*.pyc"
- .pytest_cache/**
- .mypy_cache/**
- coverage/**
- htmlcov/**
Add project-specific:
Review regularly - directories grow, become meaningful.
Git errors:
git diff fails → report error, continue othersAnalysis errors:
Fail gracefully, report clearly.
Standard:
/docsaudit
# Reviews output
git diff
# If good:
git commit -am "docs: automated audit updates"
# If not:
git restore .
First time (bootstrap):
/docsaudit --init
# Creates .docsaudit.yaml
# Initializes all existing docs
git add .docsaudit.yaml
git commit -m "docs: initialize audit tracking"
# Then regular audits
/docsaudit
Specific directory:
/docsaudit src/auth
# Audits only src/auth and below
Dry run:
/docsaudit --dry-run
# Reports what would change
# Doesn't modify anything
Parallel processing:
Git efficiency:
git diff is cheap, recalculate alwaysSystem working if:
Comprehensive coverage:
Automated maintenance:
Continuous improvement:
Trust but verify:
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.