Generate and maintain project structure index for fast AI navigation. Creates docs/structure.md with optimized file index. Load this skill when starting new project, after major changes, or when docs/structure.md is outdated.
apm install @congdon1207/project-index
[](https://apm-p1ls2dz87-atlamors-projects.vercel.app/packages/@congdon1207/project-index)---
name: project-index
description: Generate and maintain project structure index for fast AI navigation. Creates docs/structure.md with optimized file index. Load this skill when starting new project, after major changes, or when docs/structure.md is outdated.
---
# Project Index Skill
Generate optimized project structure file for fast AI context loading.
## When to Use
- **First time**: Project has no `docs/structure.md`
- **After changes**: Added/removed files, restructured folders
- **Periodic refresh**: Weekly or after major features
- **On demand**: User says "update structure", "refresh index", "scan project"
---
## Output File
**Location**: `docs/structure.md`
**Purpose**: Single source of truth for AI to understand project layout without scanning entire codebase.
---
## Cross-Platform Scripts (Recommended)
This skill includes pre-built scripts that work on all platforms:
### Node.js Script
```bash
# Basic usage (from project root)
node .codex/skills/project-index/scripts/scan-structure.js . 4
# Output to file
node .codex/skills/project-index/scripts/scan-structure.js . 4 > docs/structure.md
# JSON format
node .codex/skills/project-index/scripts/scan-structure.js . 4 json
```
### Python Script
```bash
# Basic usage
python .codex/skills/project-index/scripts/scan_structure.py . 4
# Output to file
python .codex/skills/project-index/scripts/scan_structure.py . 4 > docs/structure.md
# JSON format
python .codex/skills/project-index/scripts/scan_structure.py . 4 json
```
### Script Features
- ✅ Cross-platform (Windows, macOS, Linux)
- ✅ Auto-detect entry points (main.*, index.*, app.*, server.*)
- ✅ Auto-detect config files (package.json, tsconfig.*, etc.)
- ✅ Auto-detect key files (README, CHANGELOG, LICENSE)
- ✅ File distribution by language/type
- ✅ Customizable depth and ignore patterns
- ✅ Output: Markdown or JSON
---
## Generation Workflow
### Step 1: Scan Project (Alternative Methods)
**Option A: Use Built-in Scripts (Recommended)**
```bash
# Node.js
node .codex/skills/project-index/scripts/scan-structure.js . 4
# Python
python .codex/skills/project-index/scripts/scan_structure.py . 4
```
**Option B: VS Code Tools**
```
# Use list_dir tool recursively
# Use file_search tool with glob patterns
```
**Option C: Native Commands (Platform-specific)**
```bash
# Linux/macOS
tree -L 4 -I 'node_modules|.git|dist|build' --dirsfirst
# Windows PowerShell
Get-ChildItem -Recurse -Depth 4 | Where-Object { $_.FullName -notmatch 'node_modules|\.git|dist|build' }
# Windows CMD (limited)
dir /s /b /ad
```
### Step 2: Identify Key Files
Scan for these important files:
- **Entry points**: `main.*`, `index.*`, `app.*`, `server.*`
- **Config**: `*.config.*`, `*.json`, `*.yaml`, `*.toml`, `.env*`
- **Docs**: `README*`, `CHANGELOG*`, `docs/*`
- **Routes/API**: `**/routes/**`, `**/api/**`, `**/controllers/**`
- **Components**: `**/components/**`, `**/views/**`, `**/pages/**`
- **Services**: `**/services/**`, `**/lib/**`, `**/utils/**`
- **Database**: `**/models/**`, `**/schema/**`, `**/migrations/**`
- **Tests**: `**/*.test.*`, `**/*.spec.*`, `**/tests/**`
### Step 3: Generate Structure File
Create `docs/structure.md` with this format:
```markdown
# Project Structure Index
> Auto-generated by project-index skill. Last updated: YYYY-MM-DD HH:mm
## Quick Stats
- Total files: X
- Main language: TypeScript/Python/etc
- Framework: Next.js/Angular/Express/etc
- Package manager: npm/yarn/pnpm
## Directory Tree
\`\`\`
<tree output here>
\`\`\`
## Key Entry Points
| File | Purpose |
|:---|:---|
| src/index.ts | Main entry |
| src/app.ts | App initialization |
## Config Files
| File | Purpose |
|:---|:---|
| package.json | Dependencies |
| tsconfig.json | TypeScript config |
## Feature Map
| Feature/Domain | Location | Key Files |
|:---|:---|:---|
| Authentication | src/auth/ | login.ts, session.ts, middleware.ts |
| User Management | src/users/ | user.model.ts, user.service.ts |
| API Routes | src/api/ | routes.ts, handlers/ |
| Database | src/db/ | schema.prisma, migrations/ |
| UI Components | src/components/ | Button.tsx, Modal.tsx, Layout.tsx |
## File Patterns
| Looking for | Path pattern |
|:---|:---|
| Components | src/components/**/*.tsx |
| API handlers | src/api/**/*.ts |
| Database models | src/models/**/*.ts |
| Tests | **/*.test.ts, **/*.spec.ts |
| Styles | src/styles/**/*.css |
## Recent Changes (Optional)
- 2024-01-15: Added payment module at src/payment/
- 2024-01-10: Restructured auth to src/auth/
```
### Step 4: Validate & Save
1. Ensure `docs/` folder exists
2. Write to `docs/structure.md`
3. Confirm file created/updated
---
## JSON Alternative (Optional)
If project prefers JSON, create `docs/structure.json`:
```json
{
"generated": "2024-01-15T10:30:00Z",
"stats": {
"totalFiles": 150,
"language": "TypeScript",
"framework": "Next.js"
},
"entryPoints": [
{"path": "src/index.ts", "purpose": "Main entry"},
{"path": "src/app.ts", "purpose": "App init"}
],
"features": {
"auth": {
"location": "src/auth/",
"files": ["login.ts", "session.ts", "middleware.ts"]
},
"api": {
"location": "src/api/",
"files": ["routes.ts", "handlers/"]
}
},
"patterns": {
"components": "src/components/**/*.tsx",
"api": "src/api/**/*.ts",
"tests": "**/*.test.ts"
}
}
```
---
## Update Triggers
Structure file should be updated when:
1. **Manual trigger**: User says "update structure"
2. **New feature**: After adding new module/feature folder
3. **Restructure**: After moving/renaming folders
4. **Weekly maintenance**: As part of regular cleanup
5. **Before major task**: Ensure index is fresh before big changes
---
## Integration with AGENTS.md
After generating `docs/structure.md`, AI should:
1. **Read structure first** before searching for files
2. **Use Feature Map** to locate relevant code areas
3. **Use File Patterns** for glob searches
4. **Skip full tree scan** if structure file exists and is recent
---
## Quick Commands
```bash
# Check if structure exists (cross-platform)
test -f docs/structure.md && echo "EXISTS" || echo "NEEDS GENERATION"
# Generate with Node.js script
node .codex/skills/project-index/scripts/scan-structure.js . 4 > docs/structure.md
# Generate with Python script
python .codex/skills/project-index/scripts/scan_structure.py . 4 > docs/structure.md
# Quick check last modified (Linux/macOS)
stat docs/structure.md | grep Modify
# Quick check last modified (PowerShell)
(Get-Item docs/structure.md).LastWriteTime
```
---
## AI Agent Workflow
When generating structure as AI agent:
### Method 1: Use Built-in Script (Fast)
```bash
node .codex/skills/project-index/scripts/scan-structure.js . 4 > docs/structure.md
```
### Method 2: Use VS Code Tools (No Script Required)
1. Use `list_dir` tool to scan root
2. Use `list_dir` recursively on key folders
3. Use `file_search` with patterns like `**/*.tsx`, `**/*.ts`
4. Combine results into structure.md format
### Method 3: Hybrid Approach
1. Run script for basic tree
2. Use `read_file` on package.json to detect framework
3. Manually add Feature Map based on codebase understanding
---
## Best Practices
1. **Keep it updated**: Stale index is worse than no index
2. **Feature-focused**: Group by business domain, not just folders
3. **Include purpose**: Don't just list files, explain what they do
4. **Patterns over lists**: For large folders, show patterns instead of listing all files
5. **Version control**: Commit structure.md so team shares same understanding
6. **Use scripts**: Prefer built-in scripts over platform-specific commands