| name | docs-manager |
| source | botcore |
| description | Manages documentation architecture, review, staleness detection, and maintenance policy across project repositories. Covers README, AGENTS.md, CLAUDE.md, CHANGELOG, ROADMAP, doc sites, and skill indexing. Use when creating docs, reviewing documentation structure, auditing for staleness, updating changelogs, maintaining roadmaps, or enforcing documentation standards. Triggers: docs, documentation, readme, changelog, roadmap, agents.md, claude.md, doc site, docsify, update docs, sync docs, documentation audit, docs review.
|
| version | 1.0.0 |
| triggers | ["docs","documentation","readme","changelog","roadmap","agents.md","claude.md","doc site","docsify","update docs","sync docs","documentation audit","docs review"] |
| portable | true |
Managing Documentation
Documentation architecture, review, staleness detection, and maintenance policy for project repositories.
Capabilities
- Architecture guidance -- define where documentation belongs and enforce layer boundaries
- Format enforcement -- apply format standards per document type (README, AGENTS, CHANGELOG, ROADMAP)
- Staleness detection -- identify outdated docs via git history, version mismatches, and count drift
- Documentation review -- run structured audits across all project documentation
- Rot prevention -- enforce the "drive content to skills" principle to keep root docs lean
- Doc site management -- Docsify configuration for browsable skill documentation
- Index generation -- auto-generate skill indexes and sidebars from frontmatter
- CLAUDE.md sync -- maintain CLAUDE.md as auto-generated from AGENTS.md
Routing Logic
| Trigger | Load Reference |
|---|
| Architecture, doc layers, where docs belong | doc-architecture.md |
| Format specs, AGENTS/README/CHANGELOG/ROADMAP format | doc-formats.md |
| Staleness, audit, review, freshness checks | staleness-detection.md |
| Doc site, docsify, sidebar, index generation | doc-site-and-indexing.md |
| Skill creation and structure | See skill-manager skill (cross-link, not duplicated) |
Core Principles
1. Skills Are Truth
All detailed knowledge lives in .claude/skills/. CLAUDE.md, AGENTS.md, and README.md are routing tables that point to skills for depth. If you are writing more than 5-10 lines about a topic in a root doc, it belongs in a skill.
2. Single Source of Truth
AGENTS.md is the canonical agent instruction file. CLAUDE.md is auto-generated from it -- never edit CLAUDE.md directly. Edit AGENTS.md, then run the sync script.
3. Link, Don't Duplicate
Reference skills and other docs instead of copying content. Duplication leads to rot. For skill and prompt format standards, defer to the skill-manager and related skills.
4. Each Document Has an Audience
README.md serves developers (self-contained quick start). AGENTS.md serves AI tools (canonical instructions). CHANGELOG.md serves users (human-curated history). ROADMAP.md serves stakeholders (aspirational direction). Skills serve AI agents and developers (deep guidance).
5. Keep a Changelog
CHANGELOG.md follows Keep a Changelog 1.1.0 strictly. Entries are human-curated summaries, never git log dumps. Always maintain an [Unreleased] section.
Workflow
Documentation Update Pass
- Gather changes --
git log --oneline -20 to identify recent activity
- Check CHANGELOG -- are recent features/fixes captured in
[Unreleased]?
- Check AGENTS.md -- does it reflect current architecture, skill count, component count?
- Check README.md -- are commands, descriptions, and quick start current?
- Check ROADMAP.md -- should any items move phases based on shipped work?
- Verify counts -- list
.claude/skills/, src/components/, .github/prompts/ and compare to doc claims
- Apply updates -- follow each doc's format spec from the reference files
- Sync CLAUDE.md -- run the sync script to regenerate from AGENTS.md
- Report -- summarize what was updated and what was already current
Documentation Rot Prevention
Add this note to the top of CLAUDE.md and README.md:
> **Documentation Policy**: Skills are the source of truth. This file is a
> routing table. See the docs-manager skill for full policy.
Checklist
When to Escalate
- Major restructuring of documentation architecture
- Adding new documentation layers or document types
- Changing the skill specification format
- New document type needed -- discuss format before creating
- Conflicting information across documents that cannot be resolved independently
- Architecture changes requiring simultaneous updates to multiple docs
