project-index

CongDon1207's avatarfrom CongDon1207

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.

⭐1stars🔀0forks📁View on GitHub🕐Updated Jan 4, 2026
[Memory and Context Management]

When & Why to Use This Skill

The Project Index skill is a specialized developer utility designed to optimize how AI agents interact with large codebases. It automates the generation of an AI-friendly `docs/structure.md` file, providing a high-level architectural map, directory tree, and key entry points. By distilling complex repository layouts into a structured index, it enables agents to navigate projects faster, reduce token usage, and maintain an accurate mental model of the software architecture.

Use Cases

  • Initial Project Setup: Automatically generate a comprehensive structural overview for new repositories to give AI agents immediate context on the project layout.
  • Post-Refactoring Synchronization: Update the project index after major architectural changes, such as moving modules or renaming directories, to prevent AI agents from using stale or misleading file paths.
  • Efficient Codebase Exploration: Provide a 'map-first' navigation strategy where agents read the structure index to locate specific logic or configuration files instead of performing expensive recursive directory scans.
  • Documentation Automation: Maintain a consistently formatted and up-to-date technical map that serves both AI agents and human developers as a quick-reference guide for the project's organization.
nameproject-index
descriptionGenerate 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
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.