About explaining-step-by-step
A skill for explaining topics from the big picture down to the mechanism, with detail scaled to the question. It is aimed at agents handling questions about code, errors, documents, and related material, and emphasizes evidence, uncertainty, and concise examples.
Key features
- 01Progressive explanations from context to detail
- 02Inspection of available sources before explaining
- 03Separation of evidence, inference, and unknowns
- 04Examples grounded in meaningful state changes
- 05Detail adjusted to the question
Use cases
- 01Explaining how a code change works
- 02Tracing an error from symptoms to evidence
- 03Clarifying a document's decisions and consequences
Install
Copy the command and run it in a terminal.
npx skills add https:/After installing, type/explaining-step-by-stepin Claude Code to confirm it loaded.
Details
From the project READMEExplaining Step by Step
Build the user's mental model from the big picture to the exact mechanism. Keep detail proportional to the question; detailed does not mean exhaustive.
Ground the Explanation
- Identify the question the user is actually asking and infer their starting point from context. Ask about background only when it would materially change the answer.
- For code, errors, PRs, issues, or documents, inspect the available sources before explaining. Request only the minimum missing artifact when inspection is impossible.
- Distinguish direct evidence from inference and unknowns. Never present a plausible cause as confirmed or infer an author's intent without support.
Explain Progressively
Use only the layers that help:
- Orient: State what the subject is and why it matters to the question.
- Prepare: Define essential terms in plain language on first use.
- Decompose: Put parts, events, or changes in a natural order.
- Connect: Trace causality, data flow, control flow, state changes, or before/after behavior.
- Demonstrate: Add the smallest example, excerpt, analogy, or calculation that exposes the mechanism.
- Qualify: Include material limitations, risks, exceptions, or tradeoffs.
- Reinforce: End with the few ideas worth remembering.
Adapt the sequence to the material: symptom → evidence → cause for errors; goal → before/after → execution flow for code changes; context → decision → consequences for documents. Cite relevant files, sections, hunks, logs, or tests when they help connect claims to evidence.
Keep Examples Honest
- Walk through meaningful state changes rather than dropping in unexplained code or diagrams.
- For an analogy, say what maps to the real system and where the analogy stops.
- Simplify vocabulary and prerequisites, not the truth. Low assumed knowledge does not justify childish language or a false mental model.
Pace and Boundary
Complete the useful simple-to-deep explanation in one response by default. Pause with one concrete question only when a material ambiguity, a user-requested staged lesson, or clear confusion makes the next step uncertain. Continue follow-ups from the current layer instead of repeating the introduction.
Honor requests for brevity, code only, or no explanation. This skill explains; it does not by itself approve, review, diagnose and fix, or modify an artifact. Combine it with the responsible workflow when the user requests those outcomes.