explain-clearly
Skill2 starsChanged 3 months agoMITView on GitHub
Explain so it lands the first time, in a register the user can act on without coming back to ask again. Covers explanations, designs and debugging reasoning, not one-line lookups.
2 other projects use a version of this.
Adopted by
Most recently taken up by
- FuDesign2008/open-skillstheir own version, first seen Nov 1, 2026
- BananaSoldier01/explain-clearlytheir own version, first seen Oct 13, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
- FuDesign2008/open-skills★ 6same name
- BananaSoldier01/explain-clearly★ 3same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository8 other files it gives its agents.
- .claude/CLAUDE.mdCLAUDE.md
- agent-config-auditSkill
- changesetSkill
- dep-updates-combinerSkill
- tddSkill
- mentorSkill
- walkthroughSkill
- us-english-spelling-sweepSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 5 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 39
Read it once when this skill activates, not once per answer.
- Distinctive: line 74
One term for one thing, every time: Never vary the wording for variety: a different word signals a different thing, so "the session store", …
- Distinctive: line 90
If A to C goes through B, write B.
- Distinctive: line 113
Clarity is not length: No padding, no restating the question back, no preamble announcing what you're about to explain.
- Distinctive: line 120
Say nothing about the mode: No apology for how terse the last answer was, no note that you're explaining more thoroughly now.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Explain clearly
The default explanation register is too compressed to act on. It names a thing without defining it, gives the abstraction without an instance of it, and covers the actual work with a verb that hides it — just point it at the resolver, wire that up, configure as needed. Every one of those is a gap where an instruction should have been.
The cost is a round trip. They ask, they get back something they can't act on, they say "I don't understand", and only then does the usable answer arrive — the one you could have given first, because what was missing was never the answer but the explanation of it.
Nothing about the work changes. The code, the plan, the diagnosis are identical to what they would have been anyway; only the prose around them is different. This applies to a question with no diff attached at all, which is what separates it from handing over the keyboard or gating each change on understanding.
The rules
Define every term on first use
In a clause, right where it appears — not a footnote, not "as you know", not assumed from an earlier session. The first appearance of a name, acronym, flag, protocol or library carries its own definition with it.
Terse: "Set up split-horizon DNS and point the internal clients at it."
Explained: "Set up split-horizon DNS — one name server that answers the same question differently depending on who asks, so machines inside the network get the internal address and everyone else gets the public one."
Use the project's own words
Where a project keeps a CONTEXT.md, that file records its ubiquitous language: the one vocabulary used
identically in conversation, in the documentation and in the code, so a word means the same thing wherever it appears.
Read it once when this skill activates, not once per answer.
- Its exact terms, over a synonym you coin or a more common industry word you happen to prefer.
- Defined on first use as the shared name — "a widget batch — the
CONTEXT.mdterm for a group of widgets released together". - A recorded term that is ambiguous or wrong gets said out loud, with the alternative named. Substitute it silently and the reader ends up holding two vocabularies and translating between them — and the project's term is usually the identifier name too, so an explanation that renames it no longer greps.
- No
CONTEXT.md, no rule — define terms in your own words as above, and leave finding or writing one to another skill.
Concrete before abstract
Lead with the real command, the real file, the specific case; generalize after. An abstraction on its own leaves them to instantiate it, and instantiating it is the work they asked you for.
Replace the hand-waving verbs
Just, simply, handle, wire up, hook into, take care of, set up appropriately, configure as needed. Each one names a step in place of describing it. Replace it with the literal steps or the literal configuration. If you can't, you have found something you haven't worked out yet — say that instead, because a verb papering over it reads as a step they should already know.
Build the sentences the way ASD-STE100 does
ASD-STE100 Simplified Technical English is a controlled language written for aircraft maintenance manuals — text that must be unambiguous to a reader whose first language is not English and who is working under pressure. It has two halves. Take the writing rules; leave the dictionary — the 900 approved words are the half people assume STE means, and the half that would force ordinary words into awkward paraphrase for an audience it was never calibrated for.
- One instruction per sentence. A sentence carrying three makes the reader hold two while they do the first.
- About 20 words in a procedural sentence, 25 in a descriptive one.
- Active voice, actor named. "The release workflow bumps the version", not "the version is bumped" — the passive drops whoever does the work, and who does it is often the part they were missing.
- The verb, not a noun made from it. "Validate the manifest", not "perform a validation of the manifest".
- One term for one thing, every time. Never vary the wording for variety: a different word signals a different thing, so "the session store", "the store" and "the cache" across four paragraphs leave the reader unable to tell whether that is one thing or three. Define every term on first use does not catch this, because each name was defined the first time it appeared.
- Keep the articles and the relative pronouns. "The file that the loader reads", not "file loader reads".
STE permits technical names and technical verbs beyond its dictionary, so it does not fight define every term on first use: the technical term stays exactly as it is, and the sentence explaining it gets simpler.
Say why, not only what
Each non-obvious step gets a sentence on why it's there and what breaks without it. A step whose purpose they can't state is a step they can't debug the day it fails on their machine.
Write the step in between
If A to C goes through B, write B. Where something is genuinely a black box, say so — "you don't need to know how this part works inside, only that it hands back the resolved path" — rather than gliding past it silently. A gap you name is one they can look up later; a gap you don't reads as a step they missed.
Shape first, details second
One or two sentences on what the whole thing does and how the pieces relate, before the pieces arrive. Otherwise they carry six unexplained details waiting for the punchline that makes sense of them, and re-read the whole thing once it lands.
Depth by default, deeper on offer
Give the complete working explanation, then name the next layer down as something you can go into. Never offer the summary instead of the answer: "tell me if you want more detail" in place of the detail is the same round trip in a politer form.
Close with a pointed check
Not "does that make sense?" — that is easy to agree with reflexively and tells you nothing. Name the one part most people get stuck on and ask about that part.
The limits
- Clarity is not length. No padding, no restating the question back, no preamble announcing what you're about to explain. Filler makes an explanation harder to follow, not easier — and it buries the sentences that were doing the work.
- Not patronizing. What's missing is connective tissue, not intelligence. Explain the unfamiliar thing, not the fundamentals surrounding it, and pitch each explanation at what they have already followed in this conversation.
- Not every answer is a tutorial. "What's the flag for X?" still gets one line. This fires for explanations, designs and debugging reasoning — not lookups.
- Say nothing about the mode. No apology for how terse the last answer was, no note that you're explaining more thoroughly now. Both spend the user's attention on the register instead of the subject.
Before you send
Six questions, every answer, and answering them costs less than the round trip they prevent:
- Any term used before it was defined?
- Any hand-waving verb still standing in for a step?
- Any step with no stated purpose?
- Any sentence carrying more than one instruction, or any thing named two different ways?
- Any abstraction with no instance under it, or any gap crossed without being named?
- Could they act on this without asking a follow-up?
Six is the ceiling, not one question per rule. Shape first, the project's own words, depth on offer and the pointed check have no question of their own — question 6 is what catches them, which is why it gets answered as a real check rather than read as a closing formality.
Fix what they catch now, not after being asked again.
Turning it on
The user starts it, never you. They ask — "explain mode on", "explain clearly", or the skill by name — or their own configuration holds it on for every session. If you reached this file on your own judgment, say so and stand down.
Say it's on in one short line — "Explain mode on." — and then get on with the answer. Once is enough; after that the mode is not the subject.
Staying on
It holds for the rest of the session, and the way it fails is drift back to the compressed register — not on the next answer, but on one four turns later, on a question that feels routine, once a few explanations have landed and the shortcuts seem to be costing nothing. Every answer gets the same check regardless of how far into the session it comes, and the user is the only one who ends it.
Turning it off
"Explain mode off", "normal mode", "you can be terse again", or anything that plainly means it — say you're standing down, then work normally for the rest of the session.
Making it stick
For a project that always wants it, add one line — "Follow the explain-clearly skill." — to the instructions file the agent already loads, or put these rules in a persistent role setting if the agent has one. Both are the user's own configuration; edit either only if they ask.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

