# Explain Properly

> Rewrite an explanation the user could not follow. Use when the user says they don't understand what you wrote, asks you to explain it "properly" or "in plain words", says the text is dense, jumpy, jargon-heavy or unreadable, or expresses dissatisfaction with the clarity of something you produced in any other way.

- Skill: `dsavvinov/explain-properly` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dsavvinov/explain-properly`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dsavvinov/explain-properly/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dsavvinov (https://skillmd.com/u/dsavvinov)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/dsavvinov/explain-properly

---


# Explain properly

## If this skill ran, something is wrong

The user did not follow the text you wrote. That is a defect in the text, not in
the reader. Do not defend the previous version, do not re-send it with a
preamble, and do not apologise at length — diagnose what made it unreadable and
write it again under the guidelines below.

Rewrite; do not patch. Appending a paragraph of clarification to a text that
already lost the reader makes it longer and no clearer.

## Diagnose first: which bucket is it?

Misunderstanding almost always comes from one of three buckets. Identify the one
that applies before rewriting — the fix differs per bucket.

### 1. Conceptual overload

You used too many semantically heavy words, and the user does not carry the
meaning you assumed. Frequent forms:

- **Legitimate terms the user does not know.** Explain them, or use a plainer
  wording.
- **Invented terms.** Prefer an existing well-known term. If none exists,
  introduce and define yours explicitly before using it.
- **Inconsistent terms.** The same thing referred to under slightly different
  wordings reads as several different things. Pick one wording and keep it.
- **"How" before "why".** You described implementation detail before saying what
  the code achieves at a general level. Say what it is for, then how it does it.
- **Overquoting source code.** Every symbol you name is one more term the reader
  must hold. Quote only the code the explanation genuinely turns on.
- **Smart lingo.** "This buys us an opaque transformation of the data" instead of
  "Clients won't know how the data is transformed, so we can swap the
  implementation later if we need to." Say the second one.

### 2. Jumpy narrative

You referred to things you never explained, or explained only further down, in
text the reader had not reached yet. Reorder so every concept is introduced
before its first use, and fill the gaps you skipped.

### 3. Overcompressed text

You bought conciseness by throwing away the lexical glue that makes prose
readable, instead of by limiting what you describe. The hallmark is telegraphic
notation:

> network call + ui responsiveness -> async call

when what the reader needed was:

> To check for updates, we need to access the network. That call can be slow —
> the user may be on a spotty WiFi connection. If we made it a blocking call,
> the whole UI would appear frozen. So we do it in a background task.

## The guidelines

This is where most write-ups fail, and the failure is not length but density.

Be concise, but buy the concision by moderating **what you present and what you
omit**, never by compressing what stays. Spanning a lot of terms, concepts and
class names and then stripping the punctuation and prose to make it lexically
short leaves something still impossible to read.

Instead: select the limited set of terms, abstractions and concepts genuinely
needed to understand the system state, then introduce them one by one,
sequentially, explaining each one — before the sentence that says what went
wrong. Abstract shorthand is unreadable and actively harmful to the final text.

That set should be **four to six concepts**. Needing more is a strong signal
that something is off — there are legitimate exceptions, but they appear only in
genuinely hard and big problems. In case of doubt, always assume the case you're
working on is not one of those "hard and big problems": if the user misses some
depth, it's easy to follow up and ask for more details; the extra noise is not
that easily fixable.

If you are ABSOLUTELY certain a case cannot be explained in six, the answer is
still to moderate the reader's context, by splitting the concepts into cohesive
chunks:

- explain one chunk in depth, then summarise it, so the reader can partially
  offload it and carry only the summary forward;
- move to the next chunk;
- keep the chunks in linear sequence — an earlier chunk never needs knowledge
  from a later one, and a later chunk builds on the earlier ones.

## Before you send it

- Count the concepts you introduced. Over six, cut scope — not words.
- Check that each one is introduced before its first use.
- Check that the same thing is called the same name throughout.
- Read the text as someone who knows the domain but not this code. Every
  sentence they could not answer "what is that?" for is a defect.