Docs Manager

Documentation Manager for Claude Code

Overview

This skill generates well-structured repository documentation where each file has clear ownership of its content. Whether starting fresh or improving existing docs, the approach is the same: analyze the project and produce properly-structured documentation.

Key principles:

• Single Source of Truth: Each piece of information lives in exactly one place
• Audience Separation: Human-facing docs (README, CONTRIBUTING, STYLE_GUIDE) vs AI-facing docs (AGENTS.md)
• Cross-Reference, Don't Duplicate: Link between files rather than repeating content
• Actionable Commands: All commands should be copy-paste ready

Canonical File Structure

Note on CLAUDE.md vs AGENTS.md: Most AI agents look for AGENTS.md, but Claude Code looks for CLAUDE.md. To maintain a single source of truth, AGENTS.md contains all agent guidance and CLAUDE.md simply redirects Claude to read AGENTS.md.

Workflow

Phase 1: Gather Context

Before generating any documentation, thoroughly analyze the project:

1. Discover Project Configuration:

• Read package.json, pyproject.toml, Cargo.toml, go.mod, Makefile, etc.
• Identify available commands (build, test, lint, format)
• Note dependencies and their purposes

2. Read Existing Documentation:

• Check for existing README.md, CONTRIBUTING.md, STYLE_GUIDE.md
• Check for existing CLAUDE.md, AGENTS.md
• Extract valuable information that should be preserved
• Note any documented patterns, gotchas, or conventions

3. Analyze Codebase Structure:

• Identify entry points and key directories
• Note architectural patterns (monorepo, microservices, etc.)
• Find test directories and testing conventions
• Identify CI/CD configuration

4. Detect Technology Stack:

• Languages used (TypeScript, Python, Rust, Go, etc.)
• Frameworks (React, FastAPI, Actix, etc.)
• Build tools (npm, poetry, cargo, make)
• Linting/formatting tools (ESLint, Prettier, Ruff, rustfmt)

Phase 2: Ask User

Use AskUserQuestion to confirm and gather additional information:

Essential questions:

1. "What is the one-line description of this project?" (for README)
2. "Are there any patterns or gotchas developers should know about?"
3. "Which documentation files should I generate?" (offer: all, or specific subset)

Optional questions based on context:

• "I found commands X, Y, Z. Are these the primary development commands?"
• "Is there a specific PR/contribution workflow to document?"
• "Are there any security considerations or authentication patterns?"

Phase 3: Generate Files

Generate each requested file using the templates in assets/templates/ as starting points. Fill in discovered information and preserve valuable content from existing docs.

Generation order (if generating all):

1. AGENTS.md - Commands and architecture overview (primary AI reference)
2. CLAUDE.md - Redirect to AGENTS.md
3. STYLE_GUIDE.md - Formatting rules
4. CONTRIBUTING.md - Links to STYLE_GUIDE
5. CODE_OF_CONDUCT.md - Community guidelines (if applicable)
6. SECURITY.md - Security policy (if applicable)
7. README.md - Links to other docs
8. LICENSE - Full license text
9. CHANGELOG.md - Version history (if applicable)

For each file:

1. Read the corresponding template from assets/templates/
2. Fill in placeholders with discovered information
3. Merge valuable content from existing docs
4. Ensure cross-references to other generated files

Phase 4: Present and Refine

After generating files:

1. Summarize what was created/modified
2. Highlight any content that was migrated between files
3. Ask if adjustments are needed
4. Make refinements based on feedback

Content Ownership Rules

README.md Owns:

• Project name and badge line
• One-paragraph description
• Quick start (3-5 steps max)
• Links to other documentation
• Links to external resources

README.md Does NOT Contain:

• Detailed setup instructions (→ CONTRIBUTING.md)
• Style rules (→ STYLE_GUIDE.md)
• Full architecture (→ docs/)
• Command reference tables (→ AGENTS.md)
• License text (→ LICENSE, just link to it)

CONTRIBUTING.md Owns:

• Prerequisites and environment setup
• Detailed installation steps
• Development workflow
• How to run tests
• PR process and guidelines
• Code of conduct reference

CONTRIBUTING.md Does NOT Contain:

• Style rules themselves (link to STYLE_GUIDE.md)
• Command reference (link to AGENTS.md)
• Project overview (link to README.md)

STYLE_GUIDE.md Owns:

• Code formatting rules
• Naming conventions
• File organization patterns
• Linting configuration explanations
• Examples of correct/incorrect patterns
• Documentation style rules

STYLE_GUIDE.md Does NOT Contain:

• Setup instructions
• Commands to run linters (→ AGENTS.md)
• Contribution workflow

AGENTS.md Owns:

• Build/test/lint/format commands (canonical location)
• Project architecture overview (high-level)
• Key files and entry points
• Non-obvious patterns and gotchas
• Tool usage patterns specific to this codebase
• Multi-step workflow guidance
• Context that helps AI agents work effectively

AGENTS.md Does NOT Contain:

• Detailed style rules (link to STYLE_GUIDE.md)
• Human-oriented prose
• Contribution workflow (link to CONTRIBUTING.md)
• Full architecture documentation (→ docs/)

CLAUDE.md Owns:

• A redirect pointing Claude to AGENTS.md

CLAUDE.md Does NOT Contain:

• Any actual documentation (all content lives in AGENTS.md)

LICENSE Owns:

• Full license text
• Copyright holder and year

CODE_OF_CONDUCT.md Owns:

• Expected behavior standards
• Unacceptable behavior examples
• Enforcement procedures
• Contact information for reporting

SECURITY.md Owns:

• Supported versions
• How to report vulnerabilities
• Security policy
• Disclosure timeline

CHANGELOG.md Owns:

• Version history
• Release dates
• Changes per version (Added, Changed, Deprecated, Removed, Fixed, Security)

docs/ Directory Owns:

• Full architecture documentation
• Detailed technical documentation
• API documentation
• Design documents

walkthroughs/ Directory Owns:

• Interactive code walkthroughs (virgil format)
• Use the virgil skill to create walkthroughs

Cross-Reference Patterns

Use these patterns for linking between files:

From README.md:

See [Contributing](CONTRIBUTING.md) for development setup.
See [LICENSE](LICENSE) for license information.

From CONTRIBUTING.md:

Follow our [Style Guide](STYLE_GUIDE.md) for code formatting.
For available commands, see [AGENTS.md](AGENTS.md#commands).

From AGENTS.md:

For detailed style rules, see [STYLE_GUIDE.md](STYLE_GUIDE.md).
For full architecture documentation, see [docs/](docs/).

From CLAUDE.md (redirect only):

Read [AGENTS.md](AGENTS.md) for all agent guidance.

File Templates

Templates are available in assets/templates/:

• README.md - Project overview template
• AGENTS.md - AI guidance template (primary, all agent content)
• CLAUDE.md - Redirect to AGENTS.md
• CONTRIBUTING.md - Contribution guide template
• STYLE_GUIDE.md - Style guide template
• LICENSE - License text template
• CODE_OF_CONDUCT.md - Community guidelines template
• SECURITY.md - Security policy template
• CHANGELOG.md - Version history template

Each template contains:

• Section structure for the file
• Placeholder markers ({{PROJECT_NAME}}, {{DESCRIPTION}}, etc.)
• Cross-reference links already in place
• Comments explaining what goes in each section

Handling Existing Documentation

When existing docs contain valuable content:

1. Identify content type: Is it a command, a style rule, a gotcha, setup instructions?
2. Route to canonical location: Move content to the file that owns that type of information
3. Add cross-reference: Replace moved content with a link to its new location
4. Preserve unique insights: Don't lose valuable information discovered over time

Example migration:

• Commands table in README → move to AGENTS.md, add link in README
• Style rules in CONTRIBUTING → move to STYLE_GUIDE, add link in CONTRIBUTING
• Full architecture in any file → move to docs/, add link
• Content in CLAUDE.md → move to AGENTS.md, make CLAUDE.md a redirect

Reference Files

For detailed guidance on each file's purpose and structure:

• See references/file-purposes.md

Common Patterns

Monorepo Projects

• Note workspace/package structure in AGENTS.md
• Document per-package commands if applicable
• Consider package-level AGENTS.md files

Python Projects

• Document virtual environment setup
• Include pip/poetry/uv commands
• Note type checking configuration

TypeScript/JavaScript Projects

• Document Node version requirements
• Include npm/yarn/pnpm commands
• Note bundler configuration

Rust Projects

• Document cargo commands
• Note feature flags
• Include clippy/rustfmt configuration

Validation Checklist

Before finalizing documentation:

• Each file stays within its content boundaries
• No duplicate information across files
• All cross-references are valid
• Commands are copy-paste ready
• Quick start in README is actually quick (3-5 steps)
• Style rules are in STYLE_GUIDE.md only
• All AI-specific content is in AGENTS.md (single source of truth)
• CLAUDE.md only contains a redirect to AGENTS.md
• License text is in LICENSE (no extension, README just links to it)
• Full architecture is in docs/ (AGENTS.md has overview only)