name: project-index
description: Generate and maintain a project structure index for fast AI navigation. Creates docs/structure.md with an AI-friendly map + tree. Use when starting a new project, after major changes, or when docs/structure.md is stale.
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 .opencode/skills/project-index/scripts/scan_structure.py . 4 > docs/structure.md
Node.js
node .opencode/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.
1---2name: project-index3description: ---4---5---6name: project-index7description: Generate and maintain a project structure index for fast AI navigation. Creates docs/structure.md with an AI-friendly map + tree. Use when starting a new project, after major changes, or when docs/structure.md is stale.8---910# Project Index Skill1112Generate an AI-friendly `docs/structure.md` so agents can understand project layout quickly without scanning the whole repo.1314## When to Use1516- First time: project has no `docs/structure.md`17- After major changes: added/removed modules, moved folders, renamed domains/features18- When `docs/structure.md` looks stale or misleading19- On demand: user says "update structure", "refresh index", "scan project"2021## Output2223- File: `docs/structure.md`24- Content: **Top-Level Map** (purpose hints) + directory tree + entry points + config/key files + file-type distribution2526## Scripts (Recommended)2728### Python (recommended default)29```bash30python .opencode/skills/project-index/scripts/scan_structure.py . 4 > docs/structure.md31```3233### Node.js34```bash35node .opencode/skills/project-index/scripts/scan-structure.js . 4 > docs/structure.md36```3738### Flags3940- `json`: output JSON instead of Markdown41- `--no-gitignore`: ignore `.gitignore` rules and scan everything (not recommended)4243## Script Behavior (What "optimized" means)4445- Respects `.gitignore` patterns by default (simplified matching)46- Has built-in ignores for common noise:47 - dependencies/build outputs: `node_modules/`, `dist/`, `build/`, `coverage/`, `.next/`, `.nuxt/`, `.turbo/`48 - virtualenv/caches: `venv/`, `.venv/`, `.tox/`, `__pycache__/`, `.pytest_cache/`, `.mypy_cache/`, `.ruff_cache/`49 - IDE: `.vscode/`, `.idea/`50 - typical build outputs: `bin/`, `obj/`, `target/`51 - secrets files: `.env*`52- Uses ASCII tree connectors (`|--`, ``--`) to avoid encoding issues on Windows terminals53- Generates a **Top-Level Map** with heuristic purpose descriptions (fast navigation)5455## Expected Structure File Format5657```markdown58# Project Structure Index59> Auto-generated by project-index. Last updated: YYYY-MM-DD HH:mm6061## Quick Stats62- Total files: X63- Total directories: Y64- Main language: TypeScript/Python/etc6566## Top-Level Map67| Path | Type | Purpose |68|:---|:---:|:---|69| src/ | dir | Main application source code |70| apps/ | dir | Application(s) (often runnable targets) |71| packages/ | dir | Packages (shared modules/libraries) |72| docs/ | dir | Documentation |73| README.md | file | Project overview and getting started |7475## Directory Tree76```77repo/78|-- src/79| `-- ...80`-- README.md81```8283## Entry Points84- src/index.ts8586## Config Files87- package.json8889## Key Files90- README.md9192## File Distribution93| Category | Count |94|:---|---:|95| typescript | 120 |96```9798## Integration Notes99100- Agents should **read `docs/structure.md` first** for large/broad tasks, then use `rg` for precise lookup.101- A stale `docs/structure.md` is worse than none; refresh it after restructures.102