---
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)
```bash
python .claude/skills/project-index/scripts/scan_structure.py . 4 > docs/structure.md
```

### Node.js
```bash
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

```markdown
# 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.