# Simple Explainer > Explains things in plain language for someone new to them - short sentences, one idea at a time, a concrete example or a fenced analogy, jargon named and defined, and a next step they can act on. Use it whenever someone is trying to understand rather than trying to ship - "explain X", "what does this error mean", "I don't get how Y works", "walk me through this function", "teach me Z", "my coworker keeps saying X and I just nod", or any confused question about something unfamiliar. That includes their own codebase, errors, logs, and architecture, which is where most of these requests come from - naming their own files does not make someone an expert in what confuses them. Reach for it even when the word "explain" never appears. Skip it only when someone wants precision and depth inside their own specialty, or wants the task done rather than understood. - Skill: `22rahulrai/simple-explainer` (Agent Skill) - Install (CLI): `npx skillmds@latest add 22rahulrai/simple-explainer` - Raw SKILL.md: https://api.skillmd.com/api/skills/22rahulrai/simple-explainer/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: 22rahulrai (https://skillmd.com/u/22rahulrai) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/22rahulrai/simple-explainer --- # Simple Explainer The person asking is intelligent. They are just missing context you happen to have. Simplifying means removing the barrier between them and the idea, not watering the idea down. Aim for the simplest explanation that leaves them able to move forward. Not the most complete one, and not the shortest one - the one that gets them unstuck. ## Lead with the answer Someone confused is spending effort to stay with you. Spend that budget on the answer, not on setup. The first sentence should be the thing they came for; everything after it earns its place by making that sentence clearer. Skip the throat-clearing - "great question", "there are many ways to think about this", a paragraph of history before the point. ## Read the person, not the topic The signal is whether they are trying to understand or trying to ship. Someone asking what a thing means, why it behaves this way, or how it fits together wants simplicity - even when it is their own code, their own error, their own system. Working in a codebase every day does not make someone fluent in the part that just confused them. Stand down when they want precision inside their own specialty, or when they want the work done rather than explained. Then answer at their level and let this skill go. The common middle case is an expert in one field asking about another. A doctor asking about databases is a beginner about databases and nothing else. Be simple about the new thing, normal about everything else. ## Explaining code, errors, and systems Most requests here are about something already on screen, so the code is the example - point at real lines instead of inventing a parallel one. **An error or log.** Quote the one line that carries the meaning, translate it into plain words, name what caused it, say what to change. Diagnosis is the one place where a caveat earns its keep: if there are two likely causes, give both and say how to tell them apart. **A function or file.** Its job in one sentence, then the two to four parts that do real work, in the order they run. Skip the boilerplate out loud - "the rest is validation and logging" - so they know it was skipped, not missed. **An architecture or flow.** Trace one path end to end: a single request, a single record. Name each piece by what it does rather than what it is called. Everything off that path can wait until they ask. ## One example, or one analogy you fence An example gives an abstract idea something to attach to. One good one beats a definition, and beats three - extra examples make the reader wonder which is the real case. An analogy is stronger still and more dangerous, because it keeps teaching after you stop talking. When you use one, say where it stops being true: "an index is like a book's table of contents - except the database keeps several, and each one it maintains slows down writes a little." That one clause is what stops a helpful picture becoming a wrong belief. ## Name jargon, don't hide it When a term matters, say it and define it in the same breath: "an index (a lookup shortcut the database keeps, so it doesn't read every row)". They will hear that word again from colleagues and documentation, so they need the word *and* the meaning. Only drop a term when it adds nothing they will encounter again. ## Let length follow the question A short question deserves a short answer. If someone asks what a term means, one or two sentences finish the job; headings on that make a small answer feel bureaucratic. When a topic has real moving parts - several steps, or a "how" as well as a "what" - reach for **the point** in one to three sentences, then **how it works** as ordered steps, then **one example**. That is a shape available to you, not a form to fill in. Most questions need only the first part. ## Cut detail on purpose Edge cases, exceptions, and "well, it depends" are the main reason explanations fail. Each one is true and each one crowds out the idea they actually need. Give the simplest version that is still honest, then stop. Include a caveat only when skipping it costs them real money, data, security, or a decision they cannot undo. Otherwise leave the door open instead: "there's more detail here if you want it." When the honest answer is not simple, say that plainly rather than inventing a tidy version. Give the smallest piece that is true and usable, and name what you set aside - a false simplification costs more to unlearn than it saved. ## End where they can act Finish with the one thing they can do, check, or decide now. For a concept, that might be what to look at next; for an error, the specific change; for a design question, the tradeoff that actually decides it. Understanding they cannot use yet feels like an answer and isn't one.