/index-init
Generate a complete project index with per-module README files.
Step 1: Announce
Say: "I'm using the index-init skill to generate a project index."
Step 2: Detect project type
Glob the root directory for these signals. Use first match wins priority:
| Priority | Signal | Type | Module detection |
|---|---|---|---|
| 1 | CMakeLists.txt containing add_subdirectory() | cpp-cmake | Each add_subdirectory() argument = module |
| 2 | Cargo.toml containing [workspace] | rust-cargo | Each members entry = crate |
| 3 | go.work or multiple go.mod | go | Each use directive or go.mod directory = module |
| 4 | package.json containing "workspaces" | node-workspaces | Each workspace pattern match = package |
| 5 | *.sln file | dotnet | Each .csproj referenced = project |
| 6 | pom.xml containing <modules> | java-maven | Each <module> = subproject |
| 7 | build.gradle or settings.gradle containing include | java-gradle | Each include(':...') = subproject |
| 8 | pyproject.toml or setup.py | python | Packages or top-level dirs with __init__.py |
| 9 | pubspec.yaml | dart-flutter | Top-level or packages/ dirs |
| 10 | Fallback | generic | Top-level dirs containing source files (.cpp, .py, .js, .ts, .rs, .go, .java, .cs, .dart) |
For each detected type, extract:
- •Modules: from build/manifest files as described above
- •Purpose: from comments, description fields, docstrings, existing README content
- •Dependencies: from link directives (
target_link_libraries), imports, manifest deps - •Public API: from interface files (I*.h), exports, pub functions — names + method signatures only
- •Files: use
git ls-files(respects .gitignore) to list source + config files per module. Fallback to Glob if not a git repo.
Never index: .env, .env.*, .git/, *.key, *.pem, .npmrc, .pypirc, .aws/, .ssh/, *credentials*, *secret*, *token*, binary blobs (images, compiled objects, archives).
Step 3: Generate <Module>/README.md for each module
For each module, create or update <Module>/README.md using this template:
code
# <Module Name> <!-- AUTO-GENERATED by /index-init — do not edit above CUSTOM section --> ## Purpose <1-2 sentences describing what this module does> ## Architecture <ASCII diagram if inferrable from code structure, otherwise omit this section> ## Public API - **IClassName** — `method1()`, `method2()`, `method3()` - **ClassName** — `publicMethod1()`, `publicMethod2()` ## Files | File | Tags | Description | |------|------|-------------| | `relative/path/to/file.ext` | [tag1, tag2] | Short description (<80 chars) | ## Dependencies - **Internal**: Module1, Module2 - **External**: Library1 v1.2, Library2 ## Configs & Scripts | File | Description | |------|-------------| | `CMakeLists.txt` | Build configuration | | `config.json` | Runtime configuration | <!-- AUTO-GENERATED END --> <!-- CUSTOM — your notes below survive re-indexing -->
Rules:
- •If README.md already exists and contains a
<!-- CUSTOMsection, PRESERVE its content entirely - •Generate tags from: file name patterns, class names found in file, function names, import/include keywords
- •Generate descriptions from: first comment block, docstring, class/function declarations, or inferred from naming
- •Include non-code files:
.json,.yaml,.toml,Dockerfile,*.sh,*.ps1, CI config files - •Keep file descriptions under 80 characters
Step 4a: Generate .claude/index.summary.md
This lightweight file is injected at session start. Hard cap: 4KB.
code
# Project Index (Summary) <!-- AUTO-GENERATED by /index-init --> Generated: <YYYY-MM-DD HH:MM> | Type: <project-type> | Modules: <count> | Files: <total-count> Read `.claude/index.md` for full index with dependency graph and tag index. Read `<Module>/README.md` for detailed module documentation. ## Modules | Module | Purpose | Key Tags | |--------|---------|----------| | ModuleName | Short purpose (<60 chars) | tag1, tag2, tag3 | <!-- AUTO-GENERATED END -->
Rules:
- •No CUSTOM section (auto-regenerated, never hand-edited)
- •Keep module purposes under 60 chars
- •If the file would exceed 4KB, truncate the module table with:
| ... | N more modules. See .claude/index.md | |
Step 4b: Generate .claude/index.md
Full index file. Claude reads this on demand for details.
code
# Project Index <!-- AUTO-GENERATED by /index-init --> Generated: <YYYY-MM-DD HH:MM> | Type: <project-type> | Modules: <count> | Files: <total-count> ## How to Use The summary is injected at session start. Read module READMEs for details. ## Modules | Module | Purpose | Tags | README | |--------|---------|------|--------| | ModuleName | Short purpose | [tag1, tag2] | [README](../ModuleName/README.md) | ## Dependency Graph ModuleA → (foundation) ├── ModuleB → ModuleA ├── ModuleC → ModuleA, ModuleB └── MainApp → all modules ## Tag Index tag-name: Module1, Module2 another-tag: Module3, Module4 <!-- AUTO-GENERATED END --> <!-- CUSTOM -->
Step 5: Update CLAUDE.md
Read the existing CLAUDE.md. If it already has a "Code Index" section, update it. Otherwise, append this section:
code
## Code Index This project uses an auto-generated index for efficient code navigation. - **Summary**: `.claude/index.summary.md` — injected at session start (lightweight, <4KB) - **Full index**: `.claude/index.md` — complete module table, dependency graph, tag index - **Module docs**: Each module has a `README.md` with architecture, files, tags - **Auto-sync**: PostToolUse hook maintains the index in background - **Re-index**: Run `/index-init` to regenerate from scratch - **Usage**: Read the relevant module README before grepping source files
Step 6: Handle --gitignore flag
If $ARGUMENTS contains --gitignore:
- •Read
.gitignore(create if not exists) - •Add these lines if not already present:
code
# MacroManAtlas index files .claude/index.md .claude/index.summary.md
- •Do NOT gitignore
<Module>/README.md(useful for humans)
Step 7: Completion
Summarize what was generated:
- •Project type detected
- •Number of modules indexed
- •Number of files catalogued
- •Remind user that hooks are provided by the plugin (auto-registered via hooks.json)
- •Suggest running
/index-statusto verify