Auto Doc Index

---
name: auto-doc-index
description: Regenerate docs/INDEX.md table of contents from directory tree
type: skill
category: documentation
agents: [doc-maintainer]
knowledge: []
mcp_servers: [filesystem]
axioms: [A1, A3]
---

# Auto-Doc Index

## Purpose

Scan `docs/` directory tree and regenerate `docs/INDEX.md` with categorized table of contents linking to all documentation files. Provides comprehensive navigation structure for the documentation.

## When to Use

- After adding new documentation files
- After removing or moving documentation files
- After reorganizing documentation structure
- When INDEX.md becomes outdated or incomplete
- As part of regular documentation maintenance

## Prerequisites

- Python 3.10+ installed
- Access to `docs/` directory tree
- Write access to `docs/INDEX.md`

## Process

1. **Scan docs directory**: Recursively traverse `docs/` directory tree
2. **Identify markdown files**: Collect all `.md` files with their relative paths
3. **Extract metadata**: Read frontmatter or first heading for file descriptions
4. **Categorize files**: Group files by directory structure and category
5. **Generate TOC**: Create hierarchical table of contents with section headers, nested lists, links, and brief descriptions
6. **Write INDEX.md**: Update or create `docs/INDEX.md` with generated TOC

## Example Usage

```bash
# Regenerate INDEX.md
python scripts/tools/doc-maintainer.py --index

# Preview changes before updating
python scripts/tools/doc-maintainer.py --index --dry-run

# Regenerate with custom categories
python scripts/tools/doc-maintainer.py --index --categories guides,reference,examples
```

## Output

- Updated `docs/INDEX.md` with complete table of contents
- Hierarchical structure matching directory organization
- Links to all documentation files
- Category groupings for easy navigation

## Best Practices

- Run after any documentation file addition, removal, or reorganization
- Use `--dry-run` to preview changes before committing
- Verify all generated links resolve to existing files
- Keep INDEX.md as the single navigation entry point for documentation