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

Directory Tree

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

Entry Points

• src/index.ts

Config Files

• package.json

Key Files

• README.md

File Distribution

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.