Agent skill

Map

Structural codebase index generator. An agent skill from SethGammon/Citadel.

Install Map

skills CLI

$ npx skills add SethGammon/Citadel --skill map -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI

$ gh skill install SethGammon/Citadel map --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy

$ git clone --depth 1 https://github.com/SethGammon/Citadel.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/map .claude/skills/map && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Paste into Claude Code

Install the "map" agent skill from https://github.com/SethGammon/Citadel/tree/main/skills/map into .claude/skills/map/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "map", then confirm the skill loads.

Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

$skill-installer

$skill-installer install https://github.com/SethGammon/Citadel/tree/main/skills/map

Type this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.

skills CLI

$ npx skills add SethGammon/Citadel --skill map -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install SethGammon/Citadel map --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/SethGammon/Citadel.git skills-src && mkdir -p .agents/skills && cp -r skills-src/skills/map .agents/skills/map && rm -rf skills-src

Use ~/.agents/skills/ instead of .agents/skills for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "map" agent skill from https://github.com/SethGammon/Citadel/tree/main/skills/map into .agents/skills/map/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "map", then confirm the skill loads.

Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add SethGammon/Citadel --skill map -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install SethGammon/Citadel map --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/SethGammon/Citadel.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/skills/map .cursor/skills/map && rm -rf skills-src

Use ~/.cursor/skills/ instead of .cursor/skills for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "map" agent skill from https://github.com/SethGammon/Citadel/tree/main/skills/map into .cursor/skills/map/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "map", then confirm the skill loads.

Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

gemini skills install

$ gemini skills install https://github.com/SethGammon/Citadel.git --path skills/map

--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.

skills CLI

$ npx skills add SethGammon/Citadel --skill map -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install SethGammon/Citadel map --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/SethGammon/Citadel.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/skills/map .gemini/skills/map && rm -rf skills-src

Use ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.

Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/

Paste into Gemini CLI

Install the "map" agent skill from https://github.com/SethGammon/Citadel/tree/main/skills/map into .gemini/skills/map/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "map", then confirm the skill loads.

Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

GitHub CLI

$ gh skill install SethGammon/Citadel map

Installs for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).

skills CLI

$ npx skills add SethGammon/Citadel --skill map -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

Manual copy

$ git clone --depth 1 https://github.com/SethGammon/Citadel.git skills-src && mkdir -p .github/skills && cp -r skills-src/skills/map .github/skills/map && rm -rf skills-src

Use ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.

GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/

Paste into GitHub Copilot

Install the "map" agent skill from https://github.com/SethGammon/Citadel/tree/main/skills/map into .github/skills/map/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "map", then confirm the skill loads.

GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add SethGammon/Citadel --skill map -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install SethGammon/Citadel map --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/SethGammon/Citadel.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/skills/map .opencode/skills/map && rm -rf skills-src

Use ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "map" agent skill from https://github.com/SethGammon/Citadel/tree/main/skills/map into .opencode/skills/map/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "map", then confirm the skill loads.

OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

Facts

Skill name: map
GitHub stars: 922
Token cost: ~1.8k tokens
SKILL.md length: 803 words
Files: 1
Skills in repo: 48
Repo updated: Oct 1, 2026
First seen: Oct 7, 2026
Licence: MIT

At a glance

Structural codebase index generator. An agent skill from SethGammon/Citadel.

Works in 5 steps: GENERATE INDEX → QUERY (when user provides search terms) → STATS (structural overview) → …
Tasks that involve Codebase knowledge for agents
SKILL.md covers Orientation, Commands, Protocol and Fleet Integration, plus 4 more sections
Calls node and npm

What it does

Map is an agent skill from SethGammon/Citadel. 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.

Its SKILL.md is about 1.8k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Agent Workflows, covering Codebase knowledge for agents, Codebase onboarding and LLM cost and token optimization. The repository describes itself as: The operating layer for Claude Code + OpenAI Codex: persistent project memory, intent routing, safety hooks, cost telemetry, and parallel agent fleets. The licence is MIT.

When your agent uses it

Tasks that involve Codebase knowledge for agents
Tasks that involve Codebase onboarding
Tasks that involve LLM cost and token optimization

Example prompts

“/map”

Workflow steps

5 steps, taken from the step headings in SKILL.md.

GENERATE INDEX
QUERY (when user provides search terms)
STATS (structural overview)
SLICE (agent context injection)
STALENESS CHECK

What it can do on your machine

Read from SKILL.md and the folder at commit e41ff1d. It shows what the files ask for, not the result of running them.

Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
Shell commands in SKILL.md call:
- node
- npm
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md. Its commands use npm, which can reach the network depending on how they are called.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Map loads about 1.8k tokens when it runs. Until then it costs about 58 tokens; SKILL.md has 803 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it: ~58
When it runs · the whole SKILL.md, loaded when a task matches: ~1.8k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from SethGammon/Citadel at commit e41ff1d, republished under its MIT licence (© SethGammon). 803 words, ~1,781 tokens.

Download SKILL.mdSave it as .claude/skills/map/SKILL.md (or your agent's skills folder).

name: map
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.
license: MIT
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:

Walks the project tree (respects .gitignore, skips node_modules, dist, etc.)
Extracts exports, imports, and symbols from each source file
Infers a role for each file (component, hook, store, route, test, config, etc.)
Builds a dependency graph from resolved import paths
Records per-file SHA-256 hashes plus a whole-index source signature
Extracts route-like paths and package verification scripts
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:

Run node scripts/map-index.js --slice "<scope terms>" --max-files 15
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 ===

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 .

Show full SKILL.md (334 more words)Show less

Fleet Integration

Fleet agents receive map slices automatically when /map index exists:

Before spawning each wave, Fleet checks if .planning/map/index.json exists
If it exists: Fleet runs a slice scoped to each agent's assigned domain
The generated slice is prepended to the agent's context alongside CLAUDE.md and rules-summary.md
If the index does not exist: Fleet proceeds without a map slice (no error)

Context injection order:

CLAUDE.md content
.claude/agent-context/rules-summary.md
Map slice (scoped to agent's domain/direction)
Campaign-specific direction and scope
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.

Files

Just SKILL.md in skills/map of SethGammon/Citadel.

Open the folder on GitHubat commit e41ff1d

Compare with similar skills

Map next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Map compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
Map this skillSethGammon/Citadel	922	—	~1.8k	Automated safety check: Pass	MIT	6 days ago
ccc Semantic Code Searchcocoindex-io/cocoindex-code	2.7k	—	~938	Automated safety check: Pass	Apache-2.0	yesterday
Repomix Codebase Packeryamadashy/repomix	29k	—	~1.3k	Automated safety check: Notes	MIT	4 days ago
Codebase Handbook BuilderRuhan-Wang/Harness_Handbook	331	—	~2.2k	Automated safety check: Pass	Apache-2.0	1 mo ago
CodemapJordanCoin/codemap	704	—	~1.8k	Automated safety check: Pass	MIT	today
Codebase SearchHelweg/open-codebase-index	216	—	~1.3k	Automated safety check: Pass	MIT	yesterday

Similar skills

ccc Semantic Code Search
cocoindex-io/cocoindex-code
Semantic code search and index management with the ccc CLI: the agent initializes, indexes and queries the project by concept, filtering by language or path.
2.7k GitHub stars~938 tokensUpdated yesterday
Agent WorkflowsAuto-check passed
Repomix Codebase Packer
yamadashy/repomix
Packs a local directory or remote GitHub repository into one AI-friendly file with Repomix, then searches it to explore structure, find patterns and count tokens.
29k GitHub stars~1.3k tokensUpdated 4 days ago
Agent WorkflowsAuto-check: notes
Codebase Handbook Builder
Ruhan-Wang/Harness_Handbook
Generates, refreshes, validates and uses a compact handbook that maps where a change touches in a repository, using the active Codex session and no external LLM API.
331 GitHub stars~2.2k tokensUpdated 1 mo ago
Agent WorkflowsAuto-check passed
Codemap
JordanCoin/codemap
Gives an agent a quick map of a codebase's structure, dependencies, changes and handoffs, and tunes per-project config so the output stays code-first.
704 GitHub stars~1.8k tokensUpdated today
Agent WorkflowsAuto-check passed
Codebase Search
Helweg/open-codebase-index
Chooses the right retrieval tool for code questions: compact context for unfamiliar repos, direct lookup for known symbols, call graphs for relationships and grep for exhaustive matches.
216 GitHub stars~1.3k tokensUpdated yesterday
Agent WorkflowsAuto-check passed
Entroly Context Control
juyterman1000/entroly
Surgically select, compress, and recover codebase context using Entroly's MCP tools.
472 GitHub stars~501 tokensUpdated today
Agent WorkflowsAuto-check passed

Questions about Map

What does Map do?

Structural codebase index generator. An agent skill from SethGammon/Citadel. Map is an agent skill from SethGammon/Citadel. Structural codebase index generator.

When should I use Map?

Map fits situations like: tasks that involve Codebase knowledge for agents; tasks that involve Codebase onboarding; tasks that involve LLM cost and token optimization.

How do I install Map in Claude Code?

Run `npx skills add SethGammon/Citadel --skill map -a claude-code`. Or copy the skill folder (skills/map in SethGammon/Citadel) into .claude/skills/map in your project. Claude Code loads it when a task matches its description.

How do I install Map in Codex?

Run `npx skills add SethGammon/Citadel --skill map -a codex`. Or copy the skill folder (skills/map in SethGammon/Citadel) into .agents/skills/map in your project. Codex loads it when a task matches its description.

Can I use Map in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add SethGammon/Citadel --skill map -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/map, .gemini/skills/map, .github/skills/map and .opencode/skills/map in your project.

What does Map need to run?

Going by SKILL.md and its folder, Map needs the command-line tools its instructions call (node and npm).

Does Map access the network?

SKILL.md contains no URLs. Its commands use npm, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Map safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Map use?

Map is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Map use?

About 1.8k tokens (SKILL.md is roughly 7.1k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Map?

Skills that share tags, products or a category with Map: ccc Semantic Code Search (cocoindex-io/cocoindex-code, 2.7k stars), Repomix Codebase Packer (yamadashy/repomix, 29k stars), Codebase Handbook Builder (Ruhan-Wang/Harness_Handbook, 331 stars) and Codemap (JordanCoin/codemap, 704 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Map?

SethGammon (a GitHub user) maintains it in SethGammon/Citadel, which has 922 GitHub stars. The repository holds 48 skills in this directory. The repository was last updated on October 1, 2026.

Source: SethGammon/Citadel on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.

Install Map

Facts

At a glance

What it does

When your agent uses it

Example prompts

Workflow steps

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

/map -- Codebase Intelligence

Orientation

Commands

Protocol

Step 1: GENERATE INDEX

Step 2: QUERY (when user provides search terms)

Step 3: STATS (structural overview)

Step 4: SLICE (agent context injection)

Step 5: STALENESS CHECK

Fleet Integration

Contextual Gates

Quality Gates

Fringe Cases

Exit Protocol

Files

Compare with similar skills

Similar skills

More from SethGammon/Citadel

Related

Questions about Map