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

1. Detect project type - Parse package.json, pyproject.toml, go.mod, Cargo.toml, etc.
2. Extract commands - Build, test, lint, dev commands
3. Infer conventions - From existing code patterns
4. 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.md
• extra: Links in CONTENTS.md that don't exist