playbooks

home / skills / nickcrew / claude-cortex / code-explanation

code-explanation skill

/skills/code-explanation

This skill provides structured, audience-tailored code explanations with depth control, examples, and validation to ensure clear understanding.

npx playbooks add skill nickcrew/claude-cortex --skill code-explanation

Review the files below or copy the command above to add this skill to your agents.

Files (3)
SKILL.md
1.3 KB
---
name: code-explanation
description: Use when explaining code, concepts, or system behavior to a specific audience level - provides a structured explanation workflow with depth control and validation steps.
---

# Code Explanation

## Overview
Provide clear explanations of code and concepts with appropriate depth, structure, and examples. Adapt the output to the audience level.

## When to Use
- Explaining code, architecture, or system behavior
- Producing educational explanations for knowledge transfer
- Clarifying framework or domain concepts

Avoid when:
- The request is strictly documentation generation (use documentation-production)

## Quick Reference

| Task | Load reference |
| --- | --- |
| Explanation workflow | `skills/code-explanation/references/explain.md` |
| **Pedagogical Methodology** | `skills/code-explanation/references/pedagogical-methodology.md` |

## Workflow
1. Identify target, audience level, and format.
2. Load the explanation reference.
3. Analyze the code or concept.
4. Structure the explanation with progressive depth.
5. Validate accuracy and clarity.

## Output
- Structured explanation with examples
- Notes on assumptions and follow-ups

## Common Mistakes
- Skipping audience level calibration
- Explaining without verifying source behavior

Overview

This skill explains code, system behavior, and concepts tailored to a specified audience level. It provides a structured workflow that controls explanation depth, surfaces examples, and calls out assumptions and validation steps. The goal is clear, actionable explanations that enable learning or decision-making.

How this skill works

You specify the target (code snippet, module, architecture) and the audience level (novice, intermediate, expert) and the skill analyzes the source to produce a layered explanation. It structures the output from high-level intent to implementation details, includes concrete examples or code snippets, and adds validation checks to confirm behavior. The skill also lists assumptions and recommended follow-up actions for clarity.

When to use it

  • Explaining unfamiliar code or libraries to a team member at a specific skill level
  • Teaching a concept or pattern with progressive depth and examples
  • Reviewing system behavior to validate assumptions and edge cases
  • Preparing targeted knowledge-transfer material for new hires
  • Clarifying architecture decisions and trade-offs for stakeholders

Best practices

  • Always state the target audience and desired depth before starting
  • Include runnable examples or minimal reproductions when possible
  • Highlight assumptions, limitations, and environment dependencies
  • Validate claims by referencing code behavior, tests, or simple checks
  • Prefer progressive disclosure: start with intent then reveal details

Example use cases

  • Convert a complex function into a step-by-step explanation for a junior engineer, including a simplified example
  • Summarize an API module for product managers with an optional deep-dive for engineers
  • Explain a bug by reproducing minimal steps and showing the failing behavior and fix
  • Document a concurrency pattern with examples, pitfalls, and validation checks
  • Produce a teachable walkthrough of a machine learning pipeline for mixed technical audiences

FAQ

How do you choose the right depth for an audience?

Start by asking about prior knowledge and desired outcomes; use progressive disclosure—begin with a high-level summary and offer deeper sections on demand.

Can you validate that an explanation matches runtime behavior?

Yes. The workflow recommends minimal reproductions, unit tests, or environment checks to confirm behavior and surfaces those validation steps in the explanation.