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.