CodeMap Skill

Generate AI-annotated codebase maps with inline code context for debugging and understanding.

When to Use This Skill

Activate when the user wants to:

Debugging:

•Trace the cause of an error or bug
•Understand why something is failing
•Analyze error paths and edge cases
•Find where exceptions originate

Feature Explanation:

•Understand how a feature is implemented
•Learn execution flow through the system
•See how components interact
•Trace data transformations

Codebase Understanding:

•Onboard to unfamiliar code
•Plan refactoring or modifications
•Identify entry points for changes
•Document complex flows

Core Instructions

1. Gather Context

Ask clarifying questions:

•For debugging: What error? When does it occur? Error messages?
•For features: Which feature? What's the entry point (URL, function)?
•For understanding: What specific aspect? What's the use case?

2. Systematic Analysis

Use the Explore agent (Task tool with subagent_type=Explore) to:

•Find entry points (routes, main functions, CLI commands, error locations)
•Trace execution flow through function calls
•Identify data transformations and state changes
•Map dependencies between components
•Read actual code at each critical point

3. Extract Code Snippets

For each critical step:

•Read the file using the Read tool
•Extract 5-10 lines of relevant code
•Include the containing function or class signature
•Show the exact line where key operations occur

4. Generate Hierarchical Map

Create a map showing:

For Debugging:

•🐛 Error context (exception, location, trigger)
•📍 Error location with code snippet
•🔄 Execution trace leading to error
•🔧 Root cause analysis
•💡 Recommended fixes with code diffs

For Feature Explanation:

•📍 Entry point with code snippet
•🔄 Execution flow (numbered steps)
•
Each step includes:
- •File:line reference
- •Containing function/class
- •5-10 line code snippet
- •💡 Explanation of what/why
- •⚠️ Edge cases or error conditions
•📊 Component summary
•🔍 Critical decisions
•💡 Modification entry points

5. Code Snippet Format

Use markdown code blocks with proper language identifiers for syntax highlighting. IMPORTANT: Code fences MUST start at column 0 (no indentation) for proper syntax highlighting.

Format:

•Show file:line reference above the code block (can use └─ prefix)
•Code fence starts at column 0 with language identifier (typescript, python, javascript, etc.)
•Include function/class signature as a comment at the top
•Show 5-10 lines of relevant code
•Mark error lines with ❌ in a comment
•Add explanations below the code block with emoji bullets

Example:

Step 1: User Lookup └─ src/services/auth.service.ts:89 - findUserByEmail()

typescript

// class AuthService
async findUserByEmail(email: string): Promise<User | null> {
  const user = await this.db.query(
    'SELECT * FROM users WHERE email = $1',
    [email.toLowerCase()]
  );
  return user.rows[0] || null;
}

💡 Normalizes email to lowercase before query 💡 Uses parameterized query to prevent SQL injection ⚠️ Returns null if user not found → triggers 401 error

For nested calls, use indentation (spaces) with arrow (→):

→ Calls: src/database/users.ts:156 - query()

typescript

// class DatabaseConnection
async query(sql: string, params: any[]): Promise<QueryResult> {
  const client = await this.pool.connect();
  try {
    return await client.query(sql, params);
  } finally {
    client.release();
  }
}

💡 Uses connection pooling for performance

For error locations, mark with ❌ in comment:

typescript

// class SpeechProcessor
async analyzeSpeech(speechId: string): Promise<AnalysisResult> {
  const speech = await this.getSpeechData(speechId);

  // ❌ ERROR: speech.audio is undefined
  const duration = speech.audio.duration;
  return { metrics, duration };
}

6. Format for Terminal

Use these conventions:

Structure:

•📍 Entry points
•🔄 Execution flow header
•Bold step numbers for main flow steps (e.g., Step 1: Request Validation)
•Horizontal rules (---) to separate major steps
•📊 Component summary
•🔍 Key decisions
•🐛 Error/bug context
•🔧 Root cause analysis
•Separator line: ===...=== (80 characters)

Code Blocks:

•Code fences MUST start at column 0 (no indentation before ```)
•Use language identifiers for syntax highlighting (typescript, python, javascript, etc.)
•Function/class context as comment at top of code block
•❌ Error markers in code comments

Hierarchy:

•file:line notation with └─ prefix
•Nested calls: Indent with spaces, use → Calls: prefix
•Explanations: 💡 for insights, ⚠️ for warnings/edge cases

Component Lists:

•Use bullet points (•) instead of tree chars for flat lists

7. Output Directly to Terminal

•Display the complete map inline in the conversation
•Do NOT save to files
•Keep output under 300 lines when possible (pageable in terminal)
•End with a footer suggesting follow-up actions

8. Follow-Up Interactions

Support deepening:

•"Expand step 3" → show more code context for that step
•"Show more of that function" → full function definition
•"What calls this?" → reverse trace to callers
•"Show error handling" → map error paths
•"Show the fix" → generate code diff for recommended changes
•"Create a mermaid graph" → generate visual diagram (see section 9)

9. Mermaid Diagram Generation

When the user explicitly asks to "create a mermaid graph", "generate a diagram", or "visualize this":

Use appropriate diagram types:

•Flowchart (graph TD/LR): For execution flow, decision trees
•Sequence diagram: For inter-component communication
•Class diagram: For object relationships
•State diagram: For state machines

Flowchart Best Practices:

•Use graph TD (top-down) or graph LR (left-right)
•Clear node labels with context
•Show decision points with diamond shapes
•Color-code: blue for entry, red for errors, green for success
•Keep it focused (8-15 nodes maximum)

Example patterns: See mermaid-examples.md for complete patterns including:

•Authentication flow (with error paths)
•Data pipeline (with transformations)
•API request flow (with middleware)
•State transitions
•Sequence diagrams for service communication

After generating:

•Provide links to Mermaid viewers
•Offer to modify (simplify, add detail, different type)
•Suggest related views

10. Quality Standards

✅ DO:

•Include actual code snippets (5-10 lines) for every critical step
•Start code fences at column 0 (no indentation) for proper syntax highlighting
•Use markdown code blocks with proper language identifiers (typescript, python, javascript, etc.)
•Show containing function/class signature as comment at top of code block
•Use bold step numbers for main flow steps
•Use horizontal rules (---) to separate major steps
•Use → Calls: with indentation for nested calls
•Start from actual entry points (not assumed)
•Trace through real code (not guessed architecture)
•Include file:line for every reference
•Explain "why" not just "what" at decision points
•Mark error locations clearly with ❌ in code comments
•Provide actionable fix recommendations for bugs
•Show data flow with concrete examples from code
•Output directly to terminal

❌ DON'T:

•Save to files (output inline only)
•Create diagrams without code grounding
•Guess at implementation details
•Include every function (focus on critical path)
•Show snippets without explaining their purpose
•Assume user knows the codebase
•Create disconnected lists of files
•Skip error handling paths when debugging
•Provide vague "check for null" advice (show actual code fix)
•Generate Mermaid diagrams unless explicitly requested

Token Efficiency

To stay under 500 lines in SKILL.md:

•Keep core instructions concise
•Reference template and example files for detailed patterns
•Progressive disclosure: main instructions here, detailed examples separate

Supporting Files

•mermaid-examples.md - Mermaid diagram patterns
•debug-example.md - Complete debugging scenario
•auth-flow-example.md - Feature explanation example