map · sethgammon — Claude Code skill: codebase index, how to install
map generates a JSON index of a repository's files, exports, imports and dependency graph so an agent can locate relevant code without extra Glob or Grep calls.
MIT ★ 937 updated 2026-10-29
/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-localWhat map does
The skill runs node scripts/map-index.js --generate --root ., walking the project tree while honoring .gitignore and skipping folders like node_modules and dist. For each source file it pulls out exports, imports and symbols, assigns a role such as component, hook, store, route, test or config, and links files into a dependency graph based on resolved import paths. The result is written to .planning/map/index.json, with per-file SHA-256 hashes letting /map stale detect what changed since the last run.
Indexing covers TypeScript, JavaScript, Python, Go and Rust. A fresh index is cached for five minutes, so repeated runs inside that window exit immediately unless called with --force.
The /map slice command builds a keyword-scoped block capped at 8000 characters for safe injection into another agent's prompt. In Fleet-driven runs, this slice is attached automatically to each spawned agent next to CLAUDE.md whenever an index already exists for the project.
What it helps with
- locate files by keyword without reading the whole repo
- map dependencies between modules before a refactor
- hand Fleet agents a scoped context slice instead of a full directory scan
- detect whether the index went stale after edits
- get a quick breakdown of languages, roles and route counts
Example prompts for the agent
- Run /map to build the codebase index
- Use /map query auth to find files tied to authentication
- Check /map stale before starting a long campaign
How to install map
1Plugin marketplace
/plugin marketplace add SethGammon/Citadel/plugin install citadel@citadel-localThis installs the whole citadel plugin with all its skills
2Skills CLI (Vercel)
npx skills add SethGammon/Citadel --skill map -a claude-code3Manually: put the files in place
~/.claude/skills/map/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/map/
1Skills CLI (Vercel)
npx skills add SethGammon/Citadel --skill map -a codex2Manually: put the files in place
.agents/skills/map/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add SethGammon/Citadel --skill map -a cursor2Manually: put the files in place
.cursor/skills/map/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install SethGammon/Citadel skills/map2Manually: put the files in place
.github/skills/map/SKILL.md1Skills CLI (Vercel)
npx skills add SethGammon/Citadel --skill map -a gemini-cli2Platform CLI
gemini skills install https://github.com/SethGammon/Citadel --path skills/mapManually: put the files in place
.devin/skills/map/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about map
How do I install map in Claude Code?
Run /plugin marketplace add SethGammon/Citadel, then /plugin install citadel@citadel-local.
What does the map skill do?
It builds a JSON index of a project's files, exports, imports, dependency graph and file roles, searchable by keyword. The same index feeds compact context slices handed to other agents.
Which languages does map support?
TypeScript, JavaScript, Python, Go and Rust.
Source text
SKILL.md · MIT
---
name: map
license: MIT
description: >-
Structural codebase index generator. Builds a compact JSON map of files,
exports, imports, dependency graph, and roles. Queryable by keyword. Injected
into fleet agents as context slices to reduce token usage on code navigation.
user-invocable: true
auto-trigger: false
trigger_keywords:
- map
- index codebase
- codebase map
- structural index
- scan codebase
- map stats
- map query
last-updated: 2026-03-29
---
# /map -- Codebase Intelligence
## Orientation
Use `/map` when:
- Starting work on an unfamiliar codebase (build the index first)
- A fleet or archon campaign needs agents to know "what files matter for X"
- You want a quick structural overview (stats, roles, dependency graph)
- You need to find files related to a keyword without exploratory reads
Do not use `/map` for:
- Reading file contents (use Read)
- Searching for string patterns inside files (use Grep)
- Single-file edits where you already know the path
## Commands
| Command | Behavior |
|---|---|
| `/map` | Generate or refresh the index (skips if cache is fresh) |
| `/map --force` | Rebuild the index even if cache is fresh |
| `/map query <terms>` | Search the index for files matching keywords |
| `/map stats` | Print summary statistics (files, lines, languages, roles) |
| `/map slice <terms>` | Output a compact context slice for agent injection |
| `/map stale` | Detect added, changed, or removed indexed source files |
## Protocol
### Step 1: GENERATE INDEX
Run the index generator:
```bash
node scripts/map-index.js --generate --root .
```
Add `--force` if the user requested a fresh rebuild or if the index is stale.
The generator:
1. Walks the project tree (respects `.gitignore`, skips `node_modules`, `dist`, etc.)
2. Extracts exports, imports, and symbols from each source file
3. Infers a role for each file (component, hook, store, route, test, config, etc.)
4. Builds a dependency graph from resolved import paths
5. Records per-file SHA-256 hashes plus a whole-index source signature
6. Extracts route-like paths and package verification scripts
7. Writes the index to `.planning/map/index.json`
**Supported languages:** TypeScript, JavaScript, Python, Go, Rust.
**Cache behavior:** The index is cached for 5 minutes. Subsequent runs within
that window exit immediately unless `--force` is passed.
If `.planning/map/` does not exist, the generator creates it automatically.
### Step 2: QUERY (when user provides search terms)
```bash
node scripts/map-index.js --query "<terms>"
```
The query engine scores files by:
- Path match: +3 per term
- Export match: +5 per term
- Symbol match: +2 per term
- Role match: +1 per term
Results are sorted by score and capped at 20 files (configurable with `--max-files`).
Output is budget-capped at 8000 characters to stay injection-safe.
### Step 3: STATS (structural overview)
```bash
node scripts/map-index.js --stats
```
Outputs: file count, line count, export count, dependency edge count, route count,
package script count, verification command count, breakdown by language, and
breakdown by role.
### Step 4: SLICE (agent context injection)
When another skill or orchestrator needs a map slice for agent injection:
1. Run `node scripts/map-index.js --slice "<scope terms>" --max-files 15`
2. Inject the generated compact block:
```
=== MAP SLICE: <terms> ===
Generated: <timestamp>
Verification: npm run test | npm run typecheck
<score> <role> <path> [<top exports>] (<lines>L)
...
=== END MAP SLICE ===
```
3. The calling skill injects this block into the agent's prompt alongside
CLAUDE.md and rules-summary.md
**Token budget:** A 15-file slice is typically 800-1200 tokens. This replaces
2000-5000 tokens of exploratory Glob/Grep results that agents would otherwise
spend finding relevant files.
### Step 5: STALENESS CHECK
Before injecting an existing map into a long-running campaign, run:
```bash
node scripts/map-index.js --stale
```
The command exits `0` when the map is current and `2` when indexed source files
were added, changed, or removed. Refresh with:
```bash
node scripts/map-index.js --generate --force --root .
```
## Fleet Integration
Fleet agents receive map slices automatically when `/map` index exists:
1. Before spawning each wave, Fleet checks if `.planning/map/index.json` exists
2. If it exists: Fleet runs a slice scoped to each agent's assigned domain
3. The generated slice is prepended to the agent's context alongside CLAUDE.md
and rules-summary.md
4. If the index does not exist: Fleet proceeds without a map slice (no error)
**Context injection order:**
1. CLAUDE.md content
2. `.claude/agent-context/rules-summary.md`
3. **Map slice** (scoped to agent's domain/direction)
4. Campaign-specific direction and scope
5. Discovery briefs from previous waves
## Contextual Gates
**Disclosure:** "Generating codebase map. Creates `.planning/map/index.json`."
**Reversibility:** green — creates `.planning/map/index.json` only; undo by deleting `.planning/map/`.
**Trust gates:**
- Any: generate index, query, stats, slice.
## Quality Gates
- Index must generate without errors on any supported project
- Query must return results sorted by relevance score
- Stats output must be human-scannable in under 5 seconds
- Slice output must stay under 2000 tokens for a 15-file result
- Index must handle 100K+ line repos without hanging (iterative walker, no recursion limits)
- Cache must prevent redundant regeneration within the TTL window
- Stale checks must detect added, changed, and removed indexed source files
- Slice output must include relevant verification commands when package scripts exist
## Fringe Cases
- **No source files found**: Generator writes an empty index (`fileCount: 0`). Query returns no results. Not an error.
- **`.planning/` does not exist**: Generator creates `.planning/map/` automatically via `mkdirSync({ recursive: true })`.
- **Index file missing when querying**: Error message: "Index not found. Run `node scripts/map-index.js --generate` first."
- **Binary or unsupported files**: Silently skipped. Only files with recognized language extensions are indexed.
- **Very large repos (10K+ files)**: The walker is iterative (stack-based), not recursive. No stack overflow risk. May take 5-10 seconds on first run.
- **Windows paths**: All stored paths use forward slashes for cross-platform consistency.
## Exit Protocol
After generation:
```
Index written: <path>
<file count> files, <edge count> dependency links
<route count> routes, <verification command count> verification commands
```
After query:
```
Results for "<terms>" (<count> matches):
Score Role Path
-----------------------------------------------
<results>
```
After stats: print the full statistics block.
After slice: output the formatted slice block ready for injection.
After stale check:
```
Map index is current.
```
or:
```
Map index is stale.
Changed: <paths>
Added: <paths>
Removed: <paths>
```
Reversibility: green — delete `.planning/map/` to remove all generated artifacts; no source files modified.
© SethGammon · MIT · SethGammon/Citadel
Similar skills
All skills for Agent setup: memory, context, orchestration →map by other authors comes first.