explain

name	explain
description	Deep code explainer
argument-hint	[target: code/file/concept]

Explain — Deep Systematic Explanation

Codex Compatibility

When running this skill in Codex, translate Claude Code-only primitives before acting: AskUserQuestion -> chat/request_user_input, TodoWrite -> update_plan, Task/TaskCreate/TeamCreate/SendMessage -> spawn_agent/send_input/wait_agent when available and allowed, and EnterPlanMode/ExitPlanMode -> a concise chat plan plus explicit approval. Resolve Read/Write/Edit/Bash/WebSearch/WebFetch to Codex file/shell/web tools, and map ~/.claude/... paths to ~/.agents/... or ~/.codex/... unless the task explicitly targets Claude Code.

Cursor Compatibility

When running this skill in Cursor Agent, translate Claude Code-only primitives before acting: AskUserQuestion -> AskQuestion; TodoWrite -> Cursor TodoWrite or an equivalent checklist; Task/TaskCreate/TeamCreate/SendMessage/multi-agent flows -> Cursor Task (subagents), parallel Tasks, or run_in_background when allowed (TeamCreate/SendMessage may have no exact match); EnterPlanMode/ExitPlanMode -> Plan mode (SwitchMode / CreatePlan) plus explicit user approval. Resolve Read/Write/Edit/StrReplace/Bash/web/search/MCP via Cursor Composer or Agent equivalents. MCP names written as mcp__server__tool typically map to call_mcp_tool with configured server identifiers. Map ~/.claude/... to ~/.cursor/skills/, .cursor/skills/, and .cursor/rules/ unless the task explicitly targets Claude Code.

Advanced-level explanation with introspection markers, systematic analysis, and accuracy validation.

<essential_principles>

Always Active

• Advanced level: Assume the reader is an experienced developer. No hand-holding. Explain the "why" and architectural reasoning, not just the "what"
• Introspection markers: Make reasoning visible throughout:
  • 🤔 Reasoning — "🤔 This pattern suggests..."
  • 🎯 Decision — "🎯 The author chose X over Y because..."
  • ⚡ Performance — "⚡ This has O(n²) complexity due to..."
  • 📊 Quality — "📊 This follows/violates the SRP principle"
  • 💡 Insight — "💡 This pattern can be applied to..."
• Validate before presenting: Never guess. Read the actual code. Check official docs when explaining library/framework behavior. Flag uncertainty explicitly
• No project-specific rules: This skill works across all projects and AI agents

</essential_principles>

Phase 1: Analyze

Thoroughly examine the target before explaining anything.

1. Identify scope: Is this a file, function, class, concept, or system?
2. Read the code: Use Read, Grep, Glob to gather the actual source
3. Trace dependencies: Follow imports, references, and call sites to understand context
4. Check external APIs: Use Context7 or WebSearch for library/framework specifics if needed
5. 🤔 Form a mental model of how the target works

Tools: Read, Grep, Glob, mcp__serena__find_symbol, mcp__serena__get_symbols_overview, mcp__context7__query-docs

Phase 2: Structure

Plan the explanation for maximum clarity.

1. Identify the core insight — the one thing that unlocks understanding
2. Decide explanation order:
   • Top-down: Start with the big picture, zoom into details
   • Bottom-up: Start with building blocks, compose into the whole
   • Flow-based: Follow data/execution flow from input to output
3. 🎯 Choose the approach that best fits the target

Phase 3: Explain

Deliver the explanation with depth and clarity.

1. Open with context: What is this, and why does it exist?
2. Core explanation: How it works, with introspection markers throughout
3. Key decisions: Why was it built this way? What alternatives exist?
4. Connections: How does it relate to the broader system/pattern?
5. Code examples: Reference actual line numbers (file:line) when explaining code

Explanation Format

Use the insight block format for key educational points:

`★ Insight ─────────────────────────────────────`
[2-3 key educational points]
`─────────────────────────────────────────────────`

Phase 4: Validate

Verify the explanation is accurate and complete.

1. ✅ Cross-check claims against actual code (re-read if needed)
2. ✅ Verify library/framework behavior against official docs
3. ✅ Flag anything uncertain with "⚠️ Note: ..."
4. ✅ Ensure no oversimplification that would mislead

Examples

/explain src/auth/middleware.ts
/explain "how does React Suspense work"
/explain the hook system in this project
/explain this error message: "Cannot read property of undefined"

Boundaries

Will:

• Provide deep, accurate explanations with reasoning made visible
• Read and trace actual code rather than guessing from filenames
• Reference official documentation for framework/library specifics
• Flag uncertainty and knowledge gaps honestly

Will Not:

• Provide shallow or beginner-level explanations (use Claude directly for that)
• Guess at behavior without reading the source
• Modify any code (this is a read-only explanation skill)