doc-contents
Generate project documentation including CONTENTS.md navigation files and AGENTS.md instructions. Use when creating documentation structure, project indexes, or AI agent configuration files.
When & Why to Use This Skill
The Documentation Contents Generator is a specialized Claude skill designed to automate the creation of project navigation and AI context files. By generating structured CONTENTS.md indexes and AGENTS.md instruction files, it ensures that both human developers and AI coding assistants have a clear, up-to-date understanding of the project's structure, build commands, and coding conventions, significantly improving project maintainability and AI collaboration efficiency.
Use Cases
- Project Indexing: Automatically generate and maintain CONTENTS.md files that provide a clear table of file descriptions for better repository navigation.
- AI Agent Contextualization: Create AGENTS.md files to supply AI coding assistants (like Claude Code or Cursor) with essential build commands, testing approaches, and style guides.
- Automated Project Analysis: Detect project types (Node.js, Python, Go, Rust) and automatically extract relevant scripts and commands to populate documentation templates.
- Documentation Validation: Use built-in validation scripts to ensure that project indexes stay in sync with the actual file system, identifying missing or obsolete links.
- Multi-module Management: Generate nested AGENTS.md files for subdirectories with unique conventions to provide granular instructions without repeating parent configurations.
| name | doc-contents |
|---|---|
| description | Generate project documentation including CONTENTS.md navigation files and AGENTS.md instructions. Use when creating documentation structure, project indexes, or AI agent configuration files. |
| license | MIT |
| author | agent-kit |
| version | "1.0.0" |
Documentation Contents Generator
Generate CONTENTS.md and AGENTS.md files for project navigation and AI agent context.
CONTENTS.md
A simple table listing files and directories with brief descriptions.
- Format: Table with Name and Description columns
- Descriptions: 1-2 sentences max
- Nesting: Place in any directory that benefits from an index
See assets/contents-template.md for the template.
AGENTS.md
Context for AI coding agents (Claude Code, Cursor, Codex, etc.).
Root AGENTS.md
Place at project root with:
- Build commands
- Code style conventions
- Testing approach
- Commit format
- Available skills
Nested AGENTS.md
Place in subdirectories only when they have unique conventions not covered by the root file.
Critical: Never repeat instructions from parent files. Only include directory-specific guidance.
See assets/agents-template.md for the template.
Generation Process
- Detect project type - Parse package.json, pyproject.toml, go.mod, Cargo.toml, etc.
- Extract commands - Build, test, lint, dev commands
- Infer conventions - From existing code patterns
- Apply template - Use the appropriate template
Examples
Generate CONTENTS.md
User: Create a CONTENTS.md for the src directory
Claude: [Scans src/, applies contents-template.md]
# src
| Name | Description |
|------|-------------|
| [index.ts](./index.ts) | Main entry point and exports. |
| [cli.ts](./cli.ts) | Command-line interface handler. |
| [utils/](./utils/) | Shared utility functions. |
Generate AGENTS.md
User: Create an AGENTS.md for this project
Claude: [Detects Node.js from package.json, extracts scripts]
# AGENTS.md
CLI tool for managing project documentation.
## Build Commands
bun install
bun run build
bun test
Validation
Validate that CONTENTS.md files include all files:
bun run scripts/validate-contents.ts [path]
Output (JSON):
{
"valid": false,
"results": [
{
"contentsPath": "src/CONTENTS.md",
"missing": ["newfile.ts"],
"extra": ["deleted-file.ts"]
}
]
}
missing: Files in directory but not in CONTENTS.mdextra: Links in CONTENTS.md that don't exist