agentleFS
dork-labsdork-labs/dorkos/.agents/skills/writing-for-humans/SKILL.md

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

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.
  • AWSSkill

    retro

    Conduct a retrospective on a coding session.

    Also in 3 projects that use this

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
  1. Very specific:

    Every word a user reads should be plain enough for a smart 9th grader who does not write code.

    line 8
  2. Distinctive:

    Aim for a 9th-grade reading level: If a sentence needs a second read, rewrite it.

    line 14
  3. Very specific:

    Governs: every surface a user reads: changelog fragments, release notes, READMEs, npm package copy, the GitHub repo description, docs/ …

    line 24
  4. Very specific:

    When a page mixes both (a user guide with a developer-reference tail), split it with a clear heading like ## Reference and a framing …

    line 36
  5. Distinctive:

    Before: "per-turn context (git status, UI state, queued-message notes) travels alongside them instead of being injected into the text." …

    line 45
  6. Distinctive:

    After: "Your notes to the agent (like git status) now arrive as context, so the agent never mistakes them for something you typed."

    line 46
  7. Distinctive:

    Before: "Batch 9 — browser acceptance PASS.

    line 49
  8. Distinctive:

    After: "Fix the chat losing your place when you switch between two running sessions (DOR-73)." The ID is a footnote.

    line 50
  9. Distinctive:

    Before: "A ULID is assigned, providing a unique, time-ordered identifier." After: "Each agent gets an ID that also records when it was …

    line 53
  10. Distinctive:

    After: "Each agent gets an ID that also records when it was created, so lists stay in order." Name the concept, not the acronym.

    line 54
  11. Distinctive:

    Before: "SDK-native breakdown via held-open prompt (A1)." Can you tell what the user got?

    line 57
  12. Distinctive:

    Before: a single 68-word highlight making four separate claims.

    line 61
  13. Distinctive:

    After: one idea per sentence.

    line 62
  14. Distinctive:

    Before: a flags table dropped in with no lead-in.

    line 65
  15. Distinctive:

    After: "Most people never change these.

    line 66
  16. Very specific:

    Before: "An AgentManifest is assembled from discovery hints merged with any overrides you provide." After: "DorkOS builds each agent's …

    line 78
  17. Very specific:

    After: "DorkOS builds each agent's profile from what it finds on disk, plus any details you add."

    line 79
  18. Distinctive:

    Run all five on the finished prose:

    line 87
  19. Distinctive:

    So what?: Ask "so what?" after each sentence.

    line 89
  20. Distinctive:

    Read aloud: If you have to inhale in the middle of a sentence, split it.

    line 92
  21. Distinctive:

    No hype words ("powerful," "seamless," "effortless"): show the outcome instead.

    line 118

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

  1. Aim for a 9th-grade reading level. If a sentence needs a second read, rewrite it.
  2. Keep sentences short. Aim under 20 words. Never pack two big ideas into one sentence. Split them.
  3. Use active voice with a clear actor. Say who does what: "DorkOS opens your browser," not "the browser is opened."
  4. 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.
  5. 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.