llms: Skill for Claude Code

Map-Codebase Skill

Purpose

When starting work on an existing codebase, Claude must discover its structure, patterns, and risks reactively — reading files on demand, accumulating context piecemeal. This skill runs a one-time parallel analysis and persists the results in docs/codebase/ so every future session loads structured context instead of starting blind.

Not for: greenfield projects you built from scratch (you already know the structure).

---

Usage

/map-codebase                  # full analysis (all 7 mappers)
/map-codebase <area>           # single mapper focus (e.g. "security", "stack", "test")
/map-codebase --refresh        # force re-analysis, even if docs/codebase/ exists

Valid area names: stack, architecture, conventions, security, test, dependency, concerns

---

Workflow

Step 0: Cache Check

Before spawning any agents, check if a previous map exists:

ls docs/codebase/INDEX.md 2>/dev/null

If INDEX.md exists AND --refresh was NOT passed:

• Display the existing INDEX.md summary to the user
• Ask: "Map exists from . Refresh all, refresh a specific area, or use existing?"
• Proceed only if user asks to refresh

If --refresh or no map exists: proceed to Step 1.

---

Step 1: Pre-Triage

Before spawning agents, do a 30-second orientation:

# Count files by extension to understand the dominant language
find . -type f -not -path './.git/*' -not -path './.claude/*' \
  | sed 's/.*\.//' | sort | uniq -c | sort -rn | head -20

# Check for common entry points
ls -1 {main.py,app.py,index.ts,index.js,main.go,Cargo.toml,pyproject.toml,package.json} 2>/dev/null

# Size check — warn if > 500 files
find . -type f -not -path './.git/*' | wc -l

If > 2000 files: warn the user that analysis will take longer and suggest a focused area.

---

Step 2: Ensure Output Directory

mkdir -p docs/codebase

---

Step 3: Spawn Parallel Mapper Agents

For a full analysis, launch all 7 Task agents simultaneously. For a focused area (/map-codebase security), launch only that agent.