Project Index Skill

Generate an AI-friendly docs/structure.md so agents can understand project layout quickly without scanning the whole repo.

When to Use

• First time: project has no docs/structure.md
• After major changes: added/removed modules, moved folders, renamed domains/features
• When docs/structure.md looks stale or misleading
• On demand: user says “update structure”, “refresh index”, “scan project”

Output

• File: docs/structure.md
• Content: Top-Level Map (purpose hints) + directory tree + entry points + config/key files + file-type distribution

Scripts (Recommended)

Python (recommended default)

python .claude/skills/project-index/scripts/scan_structure.py . 4 > docs/structure.md

Node.js

node .claude/skills/project-index/scripts/scan-structure.js . 4 > docs/structure.md

Flags

• json: output JSON instead of Markdown
• --no-gitignore: ignore .gitignore rules and scan everything (not recommended)

Script Behavior (What “optimized” means)

• Respects .gitignore patterns by default (simplified matching)
• Has built-in ignores for common noise:
  • dependencies/build outputs: node_modules/, dist/, build/, coverage/, .next/, .nuxt/, .turbo/
  • virtualenv/caches: venv/, .venv/, .tox/, __pycache__/, .pytest_cache/, .mypy_cache/, .ruff_cache/
  • IDE: .vscode/, .idea/
  • typical build outputs: bin/, obj/, target/
  • secrets files: .env*
• Uses ASCII tree connectors (|--, “–`) to avoid encoding issues on Windows terminals
• Generates a Top-Level Map with heuristic purpose descriptions (fast navigation)

Expected Structure File Format

# Project Structure Index
> Auto-generated by project-index. Last updated: YYYY-MM-DD HH:mm

## Quick Stats
- Total files: X
- Total directories: Y
- Main language: TypeScript/Python/etc

## Top-Level Map
| Path | Type | Purpose |
|:---|:---:|:---|
| src/ | dir | Main application source code |
| apps/ | dir | Application(s) (often runnable targets) |
| packages/ | dir | Packages (shared modules/libraries) |
| docs/ | dir | Documentation |
| README.md | file | Project overview and getting started |

## Directory Tree

repo/ |– src/ | -- ... — README.md

## Entry Points
- src/index.ts

## Config Files
- package.json

## Key Files
- README.md

## File Distribution
| Category | Count |
|:---|---:|
| typescript | 120 |

Integration Notes

• Agents should read docs/structure.md first for large/broad tasks, then use rg for precise lookup.
• A stale docs/structure.md is worse than none; refresh it after restructures.