code-mapping - SKILL.md Agent Skill

name: code-mapping description: Creates and navigates hierarchical code maps (L0/L1/L2/L3) for AI agent and human orientation. Use when bootstrapping codebase understanding, creating navigation documentation, exploring architecture, or validating map integrity.

Maps are hierarchical: L0 (architecture) links to L1 (domains) which link to L2 (modules) which link to L3 (source code). Always start at L0 and drill down as needed.

Anchors enable grep navigation: Headings contain [Lx:identifier] markers. Find any section with grep "\[L1:auth\]" docs/map/.

Size limits enforce abstraction:

L0: 500 lines max (system overview)
L1: 300 lines max (domain docs)
L2: 200 lines max (module docs)

If a doc exceeds its limit, split it into the next level down.

Code is truth, map is derivative: When code and map conflict, the code wins. Update the map to reflect reality.

Bootstrap pattern: Agents read README.md first, then ARCHITECTURE.md, then relevant domain docs based on task.

Route based on user intent (match first):

User says	Action
"explore", "read", "understand", "navigate", "find", "where is"	Read `workflows/explore.md`, then follow it
"create", "generate", "new", "build", "document", "map"	Read `workflows/create.md`, then follow it
"validate", "check", "verify", "lint"	Run: `uv run python scripts/code_map.py validate <map-dir>` (path relative to this SKILL.md)

If intent is ambiguous, ask:

What would you like to do?

Explore - Navigate existing map to understand codebase

Create - Generate a new code map

Validate - Check map integrity

Directory structure:

docs/map/
├── README.md           # Entry point + domains index
├── ARCHITECTURE.md     # L0: System overview
└── domains/            # L1: Domain docs
    ├── auth.md
    └── api.md

Anchor format: ## [L1:identifier] Heading Text

Code link format: [`symbol`](path/to/file.py#L42)

Cross-reference format: [Domain Name](domains/name.md)

Domain Knowledge (references/):

Reference	Purpose
format-spec.md	Format rules for anchors, links, and size limits
examples/	Input/output examples (l0-architecture.md, l1-domain.md, l2-module.md, readme.md)
domains.md	What domain docs should capture

Running the Scripts

The scripts use Python 3.11+ stdlib only (no external dependencies).

Script paths are relative to this SKILL.md file (not the working directory). Derive the absolute script path from this file's location:

If this SKILL.md is at /path/to/code-mapping/SKILL.md
Then the script is at /path/to/code-mapping/scripts/code_map.py

# Validate an existing map
uv run python scripts/code_map.py validate <map-dir>

# Generate map skeletons from source
uv run python scripts/code_map.py generate <src-dir> <map-dir>

Generate command features:

Creates one .md file per source file (1:1 mapping)
Uses  placeholders
Preserves filled descriptions on subsequent runs
Reports new sections, removed sections, and unfilled placeholders

Workflows (workflows/):

Workflow	Purpose	Status
explore.md	Navigate existing map to understand codebase	Ready
create.md	Generate new map for a codebase	Ready

Scripts (scripts/):

Script	Purpose	Status
code_map.py	CLI entry point (validate, generate)	Ready
generate/	Map skeleton generation from source	Ready
validate/	Map validation (links, sizes, symbols)	Ready

A well-executed code map:

Has valid L0 ARCHITECTURE.md under 500 lines
Has L1 domain docs under 300 lines each
All file links resolve to existing files
All code links have valid file + line number
All anchors are unique across the map
No orphan documents (everything linked from parent level)