writing-for-humans
Skill11 starsChanged 51 days agoMITView on GitHub
Writes user-facing DorkOS prose a non-developer can read: changelog fragments, release notes, READMEs, npm copy, docs guides and concept pages, blog posts, UI microcopy, and error messages. Use when writing or reviewing any copy a person (not a coding agent) will read.
9 other projects use a version of this.
Adopted by
Most recently taken up by
- Suge8/friedbuntheir own version, first seen Nov 15, 2026
- drosam/agentstheir own version, first seen Nov 15, 2026
- adelrodriguez/skillstheir own version, first seen Nov 15, 2026
- draekien/skillstheir own version, first seen Nov 15, 2026
- edgarcosta/skillztheir own version, first seen Nov 1, 2026
- lstmemery/skillstheir own version, first seen Oct 8, 2026
Used with
Projects with it also use retro.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
AWSSkillretro
Conduct a retrospective on a coding session.
Also in 3 projects that use this
Other versions9 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 9
- timharris707/skills★ 44same name
- Suge8/friedbun★ 13same name
- edgarcosta/skillz★ 2same name
- adelrodriguez/skills★ 1same name
- draekien/skills★ 1same name
- drosam/agents★ 1same name
- jd-solanki/krutrimbox★ 1same name
- lstmemery/skills★ 1same name
- J03Fr0st/skills★ 0same 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 repository44 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .claude/CLAUDE.mdCLAUDE.md
- auditing-uiSkill
- browser-testingSkill
- capturing-product-mediaSkill
- ci-local-exportSkill
- ci-pulseSkill
- ci-quarantineSkill
- ci-statusSkill
- creating-pull-requestsSkill
- debugging-systematicallySkill
- debugging-test-failuresSkill
- debugging-typescript-errorsSkill
- deps-weeklySkill
- designing-frontendSkill
- opensrcSkill
- organizing-fsd-architectureSkill
- runtime-watchSkill
- stewarding-ci-pipelineSkill
- syncing-agent-skillsSkill
- verification-before-completionSkill
- vision-drift-checkSkill
- visual-companionSkill
- writing-adrsSkill
- writing-app-copySkill
- writing-blog-postsSkill
- writing-changelogsSkill
- writing-developer-guidesSkill
- writing-to-usersSkill
- adding-config-fieldsSkill
- clarifying-requirementsSkill
- maintaining-dependenciesSkill
- maintaining-dev-playgroundSkill
- managing-specsSkill
- marketplace-devSkill
- orchestrating-parallel-workSkill
- reading-session-transcriptsSkill
- receiving-code-reviewSkill
- requesting-code-reviewSkill
- styling-with-tailwind-shadcnSkill
- test-driven-developmentSkill
- upgrading-runtime-dependenciesSkill
- working-in-worktreesSkill
- dorkbot-triageSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
21 rules. 0 are common, 16 are distinctive, and 5 are very specific to this project.
0
Common
Most of the 8 edited versions we read keep these.
16
Distinctive
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 8
Every word a user reads should be plain enough for a smart 9th grader who does not write code.
- Distinctive: line 14
Aim for a 9th-grade reading level: If a sentence needs a second read, rewrite it.
- Very specific: line 24
Governs: every surface a user reads: changelog fragments, release notes, READMEs, npm package copy, the GitHub repo description, docs/ …
- Very specific: line 36
When a page mixes both (a user guide with a developer-reference tail), split it with a clear heading like ## Reference and a framing …
- Distinctive: line 45
Before: "per-turn context (git status, UI state, queued-message notes) travels alongside them instead of being injected into the text." …
- Distinctive: line 46
After: "Your notes to the agent (like git status) now arrive as context, so the agent never mistakes them for something you typed."
- Distinctive: line 49
Before: "Batch 9 — browser acceptance PASS.
- Distinctive: line 50
After: "Fix the chat losing your place when you switch between two running sessions (DOR-73)." The ID is a footnote.
- Distinctive: line 53
Before: "A ULID is assigned, providing a unique, time-ordered identifier." After: "Each agent gets an ID that also records when it was …
- Distinctive: line 54
After: "Each agent gets an ID that also records when it was created, so lists stay in order." Name the concept, not the acronym.
- Distinctive: line 57
Before: "SDK-native breakdown via held-open prompt (A1)." Can you tell what the user got?
- Distinctive: line 61
Before: a single 68-word highlight making four separate claims.
- Distinctive: line 62
After: one idea per sentence.
- Distinctive: line 65
Before: a flags table dropped in with no lead-in.
- Distinctive: line 66
After: "Most people never change these.
- Very specific: line 78
Before: "An AgentManifest is assembled from discovery hints merged with any overrides you provide." After: "DorkOS builds each agent's …
- Very specific: line 79
After: "DorkOS builds each agent's profile from what it finds on disk, plus any details you add."
- Distinctive: line 87
Run all five on the finished prose:
- Distinctive: line 89
So what?: Ask "so what?" after each sentence.
- Distinctive: line 92
Read aloud: If you have to inhale in the middle of a sentence, split it.
- Distinctive: line 118
No hype words ("powerful," "seamless," "effortless"): show the outcome instead.
“Common” is measured: kept by at least 6 in 10 of the 8 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Writing for Humans
Every word a user reads should be plain enough for a smart 9th grader who does not write code. This skill is the readability standard for user-facing DorkOS writing. It is the shared source the other writing skills build on.
The readability contract
Hold every user-facing sentence to these five rules:
- Aim for a 9th-grade reading level. If a sentence needs a second read, rewrite it.
- Keep sentences short. Aim under 20 words. Never pack two big ideas into one sentence. Split them.
- Use active voice with a clear actor. Say who does what: "DorkOS opens your browser," not "the browser is opened."
- Lead with the benefit, then the mechanism (if at all). Say what the user gets first. Most of the time you can drop the mechanism.
- Define or drop every technical term. Either avoid the jargon or gloss it in the same sentence. Prefer numbers and concrete scenarios over abstractions.
House punctuation rule: no em dashes. They invite run-on sentences that smuggle in a second idea; use a comma, colon, parentheses, or a new sentence instead.
What this governs (and what it does not)
Governs every surface a user reads: changelog fragments, release notes, READMEs, npm package copy, the GitHub repo description, docs/ guide and concept pages, blog posts, UI microcopy, and error messages.
Does not govern surfaces written for developers or coding agents, which stay precise and technical:
- ADRs →
writing-adrs contributing/developer guides and API reference pages →writing-developer-guides- Code comments → keep them technical (
.claude/rules/conventions.md)
In-app copy (UI microcopy and error messages the app renders) follows these rules and a stricter set on top: writing-app-copy, which adds the word-count cap, the no-"we" voice, and the rules for buttons, errors, empty states and approvals.
A reply to one person about their own report or question (a GitHub issue comment, a feedback email, a decline) follows these rules and adds its own: writing-to-users, which enforces the standard in meta/user-care.md.
When a page mixes both (a user guide with a developer-reference tail), split it with a clear heading like ## Reference and a framing sentence so the reader knows the audience just shifted.
Brand voice note: meta/brand-foundation.md §10 has two registers. This skill is the plain-language register. Brand vocabulary (Autonomous, Orchestration, Operator) is allowed here only with an in-sentence gloss.
Ten ways we ruin our writing
Each is a real quote from this repo, then a rewrite.
1. Leading with mechanism instead of benefit. Before: "per-turn context (git status, UI state, queued-message notes) travels alongside them instead of being injected into the text." After: "Your notes to the agent (like git status) now arrive as context, so the agent never mistakes them for something you typed."
2. A ticket or PR ID carrying the meaning. Before: "Batch 9 — browser acceptance PASS; implementation complete (DOR-73)." After: "Fix the chat losing your place when you switch between two running sessions (DOR-73)." The ID is a footnote; the sentence stands on its own.
3. Acronyms with no gloss on first use. Before: "A ULID is assigned, providing a unique, time-ordered identifier." After: "Each agent gets an ID that also records when it was created, so lists stay in order." Name the concept, not the acronym.
4. Shipping a commit message to users. Before: "SDK-native breakdown via held-open prompt (A1)." Can you tell what the user got? Neither can we, and that is the lesson: when the commit message does not tell you, do not paraphrase it into the changelog. Dig into the PR or the code until you can say what changed for the user, then write that sentence. Internal batch, task, and tracking notes never ship: cut them when you curate.
5. One sentence carrying three or four ideas. Before: a single 68-word highlight making four separate claims. After: one idea per sentence. Break it into a short lead plus a bullet each.
6. A reference table with no framing sentence. Before: a flags table dropped in with no lead-in. After: "Most people never change these. Here is the full list if you need it," then the table.
7. Tonal whiplash: warm opening, then man-page. A README that opens with a story ("It's 7am, CI has been red since 2:47am") and then jumps to bare command lists reads like two documents. Bridge the shift with a sentence, or keep the reference in its own section.
8. Describing a visual feature in text only. "Glance at your browser tabs and know which are working" is telling, not showing. When a feature is visual, add a screenshot or short clip. (Media is a separate task, so at minimum flag the gap.)
9. Developer reference mixed into a user page with no signal. A concepts page that slides from "what you get" into file paths and type names loses the non-developer mid-page. Put the deep-dive under its own heading and say who it is for.
10. Passive, nominalized phrasing that hides the actor. Before: "An AgentManifest is assembled from discovery hints merged with any overrides you provide." After: "DorkOS builds each agent's profile from what it finds on disk, plus any details you add."
Name things people can find
Never show a raw id to a person: not a chat id like 48f74bb4, not a run id, not a database key. Name the thing by the title they see in the app, and link it when they can open it. A chat is [Chat title](/session?session=<full id>); a ticket or a pull request is its number linked, then its title (rule 2 above). If a thing has no name a person would recognise, describe it ("the chat Scout started this morning") instead of printing its id.
Self-checks before you ship
Run all five on the finished prose:
- So what? Ask "so what?" after each sentence. If the answer is not obvious, add the benefit or cut the line.
- Explain-back. Could a non-developer read it once and explain it back? If not, simplify.
- Acronym scan. Find every acronym. Gloss it in the same sentence, or cut it.
- Read aloud. If you have to inhale in the middle of a sentence, split it.
- Us or them? Does the sentence describe what the user gets, or what we did? Rewrite anything that is about us.
When jargon is unavoidable
Some terms have no plain replacement. Name the term, then gloss it in the same breath:
- "MCP (the standard that lets AI tools talk to each other)"
- "a boundary (the folders on your computer DorkOS is allowed to touch)"
- "CORS (the browser rule that controls which sites may call your server)"
Gloss on first use only; after that the reader knows it.
Telling the DorkOS story
What DorkOS is, who it is for, the message stack, the words we use and the words and claims we never use all live in one place: meta/VOICE.md. Read it before you write a sentence about DorkOS itself. This skill is how to write; that file is what to say. Do not copy its lists into a page or a skill; link to it.
Two things to keep in your head while you write:
- The reader is the founder first, a semi-technical person running a business mostly with agents (
meta/personas/the-ai-native-founder.md). Kai, the developer running many agents, comes second (meta/personas/the-autonomous-builder.md). Write for the founder unless the page is plainly for developers. - Agents are co-workers. Describe an agent by its job: "Scout reviews your pull requests."
The honesty gate
Plain language never means overclaiming. The demo-claim gate in meta/ROADMAP.md lists what may be described as working today; everything else is "coming" or left out. Describe what a person can actually do now.
No hype words ("powerful," "seamless," "effortless"): show the outcome instead.
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.

