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

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