writing-for-audiences
Skill0 starsChanged 2 days agoMITView on GitHub
Use when writing prose a specific person or audience will read, act on, or hear — a report, a deck or speech, teaching material, an explanation, a message — and when a reader signals they did not understand ("what is this number of?", "explain it in simpler terms", "I don't get what you mean").
In this repository20 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- addressing-review-feedbackSkill
- budgeting-agentic-workSkill
- coordinating-sessionsSkill
- delegating-to-subagentsSkill
- explaining-changes-visuallySkill
- git-syncSkill
- implementation-gatesSkill
- implement-planSkill
- landing-merged-workSkill
- maintaining-project-memorySkill
- plan-featureSkill
- reporting-defects-upstreamSkill
- review-prSkill
- tracking-open-asksSkill
- verifying-before-sendingSkill
- writing-code-commentsSkill
- writing-commit-messagesSkill
- writing-plan-docsSkill
- writing-pr-descriptionsSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
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 28
A derived number leaks what its parts conceal: If one component must stay private, check that no published total lets a reader recover it …
- Distinctive: line 46
Ask how the text will be consumed and shape it for exactly that:
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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
Writing for Audiences
Two failure modes, both invisible to the writer: prose the reader cannot use (wrong register, numbers without bases, mechanics instead of meaning) and prose the reader should not have (internal detail carried past its boundary). Both survive self-review, because the writer reads with their own context and their own entitlements.
Two skills fire at the send moment, one axis each: verifying-before-sending owns whether the claims are true, and this skill owns whether the prose serves and fits its reader.
When a reader signals non-understanding, the failure is the level the explanation was pitched at, not the reader's attention. Re-explain the mechanism from its concepts in plain language; do not repeat the same sentence slower.
Match the register to the reader
- Plain words over idioms. An idiom costs a non-native reader a re-read and translates badly out loud; real corrections have flagged phrases as mild as "in earnest" and "one-and-done". Jargon is replaced by the concrete action it stands for.
- Terms of art defined at first use — in a deliverable, a reader should never need a follow-up question to act on it.
- Text that will be spoken must survive being spoken: one-breath sentences, no constructions the speaker will stumble on.
- An analogy earns its keep on a genuinely complex mechanism — and gets dropped the moment the reader waves it off. The analogy serves the reader, not the explanation.
Every number carries its base — and its conditions
A figure without its base is noise the reader must interrogate: "40%" invites "of what?" — write "40% of new signups" (invented). Two further rules the base rule implies:
- Numbers measured under different conditions are not one comparison. Two services' error rates — one measured with retries enabled, one without (invented) — presented side by side manufacture a ranking the data does not support. Report them separately, each with its measurement conditions named.
- A derived number leaks what its parts conceal. If one component must stay private, check that no published total lets a reader recover it by subtraction.
The audience gate — strip what the reader is not entitled to
Every artifact written for a surface others can see is scoped to that audience before it leaves. What crosses the boundary: facts, scope, asks. What does not: internal file paths and record identifiers, tooling and vendor names the audience has no reason to learn, personal scheduling, routing and escalation strategy, severity framing, and third parties' verbatim private words — those get paraphrased, and audited by extracting every quoted span, not by one pattern search.
- Re-derive the text for the audience; never condense the internal version. Condensing carries internals along — one task description condensed from an internal backlog delivered interpersonal framing about a colleague — and its escalation plan — onto a shared board. Writing fresh from "what does this reader need" does not.
- A mundane internal choice, written down, can read as strategy. An ordinary staffing arrangement, written up as a record of who was and was not being informed, turned logistics into apparent secrecy. If an aside is incidental to the document's subject, it does not belong in the document — state the operational fact (a date, an owner) without narrating who gets told what.
- Edits reduce the surface; they do not unsend. Shared platforms keep history, so the gate applies at creation time, not as cleanup.
Meaning over mechanics
For a non-implementer audience, every highlight is an action and what it bought the reader — never process detail ("merged", "suite green", "standard upgrade pattern"), which reads as noise to anyone who cannot act on it. And when your text sits alongside companion surfaces — another presenter's section, a linked document — reference and attribute rather than re-announce: duplicated content forces the audience to sit through it twice and drifts against the original.
Ground abstract findings in one worked example that follows the reader's own journey. Define a single concrete scenario once — an id, a handful of items, what happens to each at every stage — and hang each point on it or on the person who meets it, in the order what we see → why it matters → the example → the proposal. A status model that three abstract explanations failed to land was grasped from one such story.
Format for actual use
Ask how the text will be consumed and shape it for exactly that:
- Copied — no formatting gutters (quote markers, table pipes) the user must strip before pasting.
- Spoken — breath-length sentences, no parentheticals.
- Skimmed — the point first; an ask never trails a long paragraph, because the trailing clause is what skimming skips.
- Decoded — a figure or diagram carries its own legend; a reader with no context must be able to say what each element means.
- Published under a person's name (an article, a post, a public doc) — after the content passes, run a de-AI-register pass where such a tool is installed (e.g. the MIT-licensed humanizer skill), feeding the author's own writing samples. Drafting-register tells — bold-label lists, stock vocabulary, uniform cadence — cost the text credibility with exactly the audience it was written for; the sample-priority rule keeps the author's real habits intact, including ones a pattern catalog would flag.
Red flags
| Thought | Reality |
| "The percentage is obvious from context" | The reader asks "of what?" — name the base in the sentence |
| "These two numbers belong in one table" | Different measurement conditions make it a false comparison. Separate, with conditions |
| "I'll condense the internal write-up for them" | Condensing carries internals along. Re-derive from what this reader needs |
| "It's only visible to teammates" | Entitlement is per-audience, not internal-vs-external. Scope it anyway |
| "I'll clean the shared copy up afterwards" | History keeps the original. The gate applies at creation time |
| "The reader will ask if they don't understand" | A re-ask is the failure signal, and most readers won't ask — define terms up front |
| "The detail proves we did the work" | A non-implementer reads mechanics as noise. Action → what it bought them |
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.

