agentleFS
dork-labsdork-labs/dorkos/.agents/skills/writing-to-users/SKILL.md

writing-to-users

Skill11 starsChanged 51 days agoMITView on GitHub

Writes a direct reply to one person about their own report or question: GitHub issue replies, feedback receipt, decision and shipped emails, discussion answers, decline notes. Use when a named person is waiting to hear back from DorkOS in any channel. Builds on writing-for-humans; the standard it enforces is meta/user-care.md.

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 4 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Do not use it for a changelog entry, release notes, or a docs page.

    line 19
  2. Very specific:

    Every report gets these three, in order, per meta/user-care.md.

    line 23
  3. Distinctive:

    When they hear next. A day, not "soon."

    line 32
  4. Distinctive:

    Never give a date for the fix.

    line 46
  5. Distinctive:

    Write like one person writing to another.

    line 68
  6. Distinctive:

    Run these in order. Any miss means rewrite.

    line 89

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

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

Writing to Users

One person wrote to us. This skill is how we write back. It covers every one-to-one reply: a comment on a GitHub issue, the receipt and shipped emails, a decline, an answer in a discussion, a reply on social media. (There is no DorkOS Discord; the official Community Space is coming.)

It builds on writing-for-humans, which owns everything published for everyone (docs, changelog, UI copy). Read that first if you have not. This skill adds what a reply to a specific person needs: the standard in meta/user-care.md, the three reply shapes, and the checks before anything posts.

When to use

  • Someone opened a GitHub issue or discussion and has not been answered
  • A feedback report needs its receipt, decision, or shipped note
  • We are declining a request or closing a report
  • Any time a named person is waiting on us

Do not use it for a changelog entry, release notes, or a docs page. That is writing-for-humans and writing-changelogs.

The three replies

Every report gets these three, in order, per meta/user-care.md. Each one is short. Each one names something real.

1. Heard (within one business day)

Four parts, in this order, usually four to six sentences total:

  1. Their name and thanks. "Thanks, Karl."
  2. One specific detail from their report that proves a person read it. Quote or paraphrase something only their report contains.
  3. What we are doing right now. "I've filed it and I'm reading through the log you attached."
  4. When they hear next. A day, not "soon."

Example:

Thanks, Karl. The part where a heartbeat from the old page resets the failure count is the key detail, and it explains why the ladder never climbs past a plain reload. I've filed this and I'm reproducing it on a slow machine. You'll hear from me by Wednesday with what we're going to do.

2. Decided (within five business days)

Three parts:

  1. The decision in the first sentence. "We're fixing this." or "We're not going to change this."
  2. One sentence of why, in their terms, not ours.
  3. What happens next. For a fix: "I'll comment here when it's in a release." For a no: what they can do instead, if anything, and thanks anyway.

Never give a date for the fix. Give the next update instead.

Example of a no:

We're not going to add a setting for this. The panel is meant to show one state, and a second mode would make the common case harder to read. If the delay is the real problem for you, the fix in #1840 should remove it. Thanks for writing it up so carefully.

3. Shipped (the day of the release)

Three parts:

  1. The version and the release link.
  2. One plain line on what changed for them. Not the commit, the outcome.
  3. Thanks that names what they contributed.

Then close the issue. On GitHub, comment first and close second, so the close is never silent.

Example:

This is in v0.75.0: https://github.com/dork-labs/dorkos/releases/tag/v0.75.0. The app now waits for the new page's own heartbeat before it counts a boot as healthy, so a slow start can't loop. Your write-up of the reset was exactly right and saved us most of a day. Thank you.

Tone

Write like one person writing to another. Plain words. Short sentences. Say "I" when you did it and "we" when the team did.

  • Warm, not gushing. One thank-you per reply.
  • Specific, not vague. "The log line at 14:02" beats "the details you provided."
  • Honest, not reassuring. If we do not know yet, say we do not know yet.
  • Calm about bad news. A "no" is one sentence, not a paragraph of apology.

Never write

  • "We'll look into it." Say what you are doing instead.
  • "Sorry for any inconvenience." Say what went wrong and what you did.
  • "Great question!" or "Thanks for reaching out!" as an opener. Start with their name.
  • A fix date. Only a next-update date.
  • Anything about a fix being done before it is in a release someone can install.
  • Anything that blames their setup, skills, or reading of the docs.
  • Em dashes, bullet lists, headers, or bold in a reply. A reply is a note, not a document.
  • Filler that reads like a template: "I hope this helps," "Please don't hesitate," "Feel free to."
  • A raw id, like a chat id 48f74bb4. Name the thing by the title they see, and link it when they can open it (writing-for-humans, "Name things people can find").

Before it posts

Run these in order. Any miss means rewrite.

  1. Does the reply name one thing only their report contains?
  2. Does it say when they hear next, with a day?
  3. Could a smart 9th grader read every sentence?
  4. Is every claim true today? (writing-for-humans honesty gate)
  5. Would you be glad to receive it if you had written the report?
  6. Is the agent:provenance line at the end if an agent drafted it?
  7. Has a person approved this exact text? An agent never posts to a reporter on its own.

Where the replies go

Reply in the channel the person used. A GitHub issue gets a GitHub comment. A "Send feedback" report gets the receipt and shipped emails from the pipeline, and a decline email when needed (/feedback:triage). Never ask a person to move channels.

Related: meta/user-care.md (the standard), writing-for-humans (the base rules), /feedback:triage (the queue and its checks), meta/agent-etiquette.md (how agents behave in shared rooms; the same restraint applies here).

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.