# Index Init

> Generate a complete project index with per-module README files for efficient code navigation. Use when starting work on a new project or after major restructuring. Run once per project. Use when this capability is needed.

- Skill: `tomevault-io/index-init` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/index-init`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/index-init/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/index-init

---


# /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:

```
# <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 `<!-- CUSTOM` section, 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**.

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

```
# 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 file-level detail.
See CLAUDE.md "Code Navigation" section for the search strategy.

## 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" or "Code Navigation" section, update it. Otherwise, append this section:

```
## Code Navigation

When you need to search the codebase and don't already know the exact file:

1. Read `.claude/index.md` → Tag Index to find which module(s) own the topic
2. Read `<Module>/README.md` → exact file paths, classes, responsibilities
3. Grep/glob within that module — not the whole repo

Skip this if you already know the file path. This is for discovery, not mandatory ritual.

Index files: `.claude/index.md` (full), `.claude/index.summary.md` (session start), `<Module>/README.md` (per-module). Re-index: `/index-init`
```

## Step 6: Handle `--gitignore` flag

If `$ARGUMENTS` contains `--gitignore`:
- Read `.gitignore` (create if not exists)
- Add these lines if not already present:
  ```
  # 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-status` to verify

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/macroman5) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-15 -->