code-index

name	code-index
description	This skill should be used when the user asks to "create a code index", "index this codebase", "update the code index", "generate code index", "build code index", "refresh semantic summaries", or needs guidance on generating or updating the .metis/code-index.md file for AI agent codebase navigation.

Code Index Generation

This skill guides the process of generating and maintaining .metis/code-index.md — a structured codebase map for AI agent navigation.

CRITICAL: File Editing Rules

The code index file (.metis/code-index.md) is a regular file, NOT a Metis document. You MUST:

• Use the Read tool to read .metis/code-index.md
• Use the Edit tool to modify .metis/code-index.md
• NEVER use mcp__metis__edit_document or mcp__metis__read_document for this file — those are for Metis documents (visions, initiatives, tasks, ADRs, specifications), not the code index

Overview

The code index has two layers:

1. Layer 1 (Structural): Auto-generated file tree and symbol extraction via tree-sitter. Fast, deterministic. Generated by metis index. Tells you what symbols exist.
2. Layer 2 (Semantic): AI-generated summaries that explain what the code means — key abstractions, symbol relationships, non-obvious behavior, and mixed concerns. Generated by the code-index-summarizer subagent.

Background Agent Permissions

The code-index-summarizer agent runs in the background and needs Edit access to write summaries to .metis/code-index.md. By default, background agents cannot prompt for tool approval.

To enable background summarization, the user must add Edit(.metis/code-index.md) to their allowed tools. They can do this by running /permissions and adding the rule.

If this permission isn't configured, tell the user:

"The semantic summarizer needs Edit access to .metis/code-index.md to run in the background. Run /permissions and add Edit(.metis/code-index.md) to your allowed tools. Otherwise I can run it in the foreground, but it'll take a couple of minutes."

Quick Start

Generate a fresh index

1. Run structural index via Bash: metis index (or metis index --incremental to skip unchanged files)
2. Launch the code-index-summarizer agent via the Task tool to generate semantic summaries:

   Task(subagent_type="code-index-summarizer", prompt="Generate semantic summaries for all source modules in .metis/code-index.md. This is a first run — summarize ALL modules.", run_in_background=true, model="sonnet")
   

Update an existing index

1. Re-run structural index via Bash: metis index --incremental
2. Determine which directories had files change (from the incremental output or from .metis/.index-dirty contents)
3. Launch the code-index-summarizer agent to update only changed modules:

   Task(subagent_type="code-index-summarizer", prompt="Update semantic summaries in .metis/code-index.md for these changed modules: <list>. Only re-summarize the listed modules; leave others unchanged.", run_in_background=true, model="sonnet")
   

Automatic Index Updates

Source file changes are tracked automatically:

• A PostToolUse hook records modified source files to .metis/.index-dirty
• At PreCompact and Stop time, metis index --incremental runs automatically if dirty files exist
• After PreCompact, the restored context will note that the index was updated and which directories changed — you can optionally launch the summarizer agent for those modules

File Structure

The code index is organized as ## Modules with summaries co-located next to symbols:

## Modules
### module/path
> *Semantic summary to be generated by AI agent.*  ← summary slot

#### module/path/file.rs                           ← file symbols
- pub `StructName` struct L5-20 — `{ field: Type }`
- pub `function_name` function L22-40 — `(args) -> Result`

#### module/path/other.rs
- symbols...

### another/module
(AI-written summary here)                          ← replaced by summarizer

#### another/module/file.rs
- symbols...

Summaries sit between the ### module heading and the first #### file heading. The structural index preserves existing summaries across regenerations — when metis index runs again, it keeps any AI-written summaries and only resets placeholders for new modules.

What the Semantic Summaries Cover

The summarizer reads ALL source files in each module and produces understanding that symbol names alone can't convey:

• Key abstractions — what types/traits/interfaces actually represent, their invariants, when they're created vs looked up
• Symbol relationships — how pieces connect: what calls what, what implements what, what orchestrates what
• Internal flow — how a request/operation moves through the module
• Mixed concerns / gotchas — modules with impure separation, implicit coupling, surprising behavior
• Dependencies — not just crate names, but what the module uses them for

Guidelines

When to regenerate

Re-run the full index (Layer 1 + Layer 2) when:

• Starting work on an unfamiliar project
• After major refactors that change directory structure
• When significant new modules are added
• When semantic summaries feel stale or inaccurate

Re-run Layer 1 only (structural) when:

• New files were added but directory structure is the same
• You just need updated symbol listings

Model Selection

The code-index-summarizer agent uses Sonnet for generating semantic summaries. It reads ALL source files in each module (not just 2-3 representative files) to produce accurate understanding of symbol semantics and relationships. The structural index (Layer 1) is deterministic and doesn't use any model.