/swarm-write

name: swarm-write
description: Writing for humans — any end-user-facing text, in any language. READMEs, landing pages, blog posts, social posts, marketing copy, release notes, docs, and UI microcopy (tooltips, buttons, empty states, error messages). Use when asked to write, rewrite, polish, or humanize copy, when text sounds robotic or AI-generated, when defining a voice or tone, and — unprompted — whenever you are about to produce any string a real user will read.

swarm-write — writing for humans

Most agent-written copy fails the same way: no voice, even rhythm, filler detail, and the machinery showing through. This skill is not a banned-word filter. Filters date fast and flatten every voice into one texture. Write from a stance, then subtract.

Jurisdiction (check this first)

| lane | reader | what applies | |---|---|---| | **end-user text** | humans who did not ask for it | all of this skill | | agent-facing (prompts, tickets, queue, skill files) | models | machine lane, unchanged | | project docs (SRS, ADRs, specs) | owner + future agents | clear and complete, no voice work, no marketing | | code and the prose inside it | engineers | §Code lane only |

Outside the first row, stop reading and write as you normally would.

1. Name the reader before writing a word

One line, not an interview: **who reads this, what they do next, what they already know, what makes them quit.** Most agent copy is bad because it was written for whoever asked, not whoever reads.

Write to **one person**, not an audience. "A backend dev at a 20-person startup who just got paged" produces sharper prose than "developers," every time. Specificity in the reader creates specificity in the writing.

2. Voice

**First: whose voice is it?** The surface decides, and getting this wrong personalizes what shouldn't be personal:

• **Personal** (the user's posts, portfolio, personal brand, a project that *is* them) → the

user's voice. Profile, menu candidates, samples — everything below applies.

• **Product** (an app, tool, or service built for an audience) → the **product's** voice,

derived from audience + category + brand direction, not from the user's persona. If `swarm-design-ui` chose a brand direction, that choice *is* the voice input — derive from it, don't re-interview. Store as the project's `voice.md` with `owner: product`. The user approves it once like any design decision; nobody's personal taste is mined for it.

• **UI microcopy** (tooltips, errors, buttons, empty states) → automatic, always. Product

voice + the reader's emotional state (`references/ui-copy.md`) set the register. Never run voice candidates for a tooltip.

When unsure, one question: "is this you talking, or the product?"

Three layers. Load `references/voice-menu.md` for the named profiles, dials, and samples.

• **Identity** (stable): stance toward the reader, words in and out, commit-vs-hedge posture.
• **Register** (per piece): formality, warmth, humor, energy, person, rhythm, technicality.
• **Move set** (the craft): how it opens, whether it lists, whether it admits uncertainty,

whether it sets up a payoff or leads with it. This layer is what makes a voice recognizable. Two voices can both be "warm and direct" and sound nothing alike.

**Register moves within a piece.** One document is not one register: the opening of a README is a hook and may sell; the mechanics section explains like a colleague; the FAQ talks like a person answering a question. Identity and move set stay constant across the whole piece; the dials shift by **zone** (see the zoning section of `references/voice-menu.md`). Applying one flat register everywhere produces text that is consistent and dead. Marketing register is legitimate *in the zones built for it*: a hook, a landing headline, a launch post. It becomes slop only when it leaks into explanation.

**Where voice comes from, in order:**

1. **An existing profile** (§Storage). Found one? Use it, skip to §3. Never re-derive. 2. **Menu candidates on the real content.** Pick 2–3 profiles that fit the job, write **the real opening** in each (~50 words, never filler — comparing filler teaches nothing), show them side by side. User points, or says "this one, less X." Save the result. 3. **The user's own writing — opt-in, offered exactly once** while building the first profile: links to posts, docs they wrote, anything they're proud of. If they skip, don't ask again; the rejection log converges on their voice anyway. If they *ask* ("write it like me"), collect in fidelity order per the table below, fetching public posts only from URLs they give you. 4. `"just write it"` is always a valid answer: use the global default plus the anti-voice list, show the draft, offer to refine.

Samples are an accelerator, never a dependency — recognition beats description, and a few rounds of rejections beat both.

**Learning from what they already wrote** (when offered samples, posts, or their own prompts), in fidelity order:

| source | extract | |---|---| | text they wrote and edited | everything | | text they wrote unedited (prompts, messages, commits) | **signal** only | | text they admire but did not write | shape and stance only, never phrasing |

**Signal vs artifact.** Signal is voice: rhythm, how they open, what they emphasize, directness, humor, how frustration reads. Artifact is the medium: typos, run-ons, dropped punctuation, the fragmentary syntax of typing fast. Only signal transfers.

**Grammar.** Output is always grammatical in the target language. But some "errors" are voice: fragments for emphasis, sentences opening with And, comma splices for pace. Frequency decides. **Once is a slip and gets fixed. Consistent across samples is a choice and gets kept.**

**Storage** — global default, per-project override, degrading gracefully: `voice.md` in the vault (`10 Projects/<P>/voice.md`, plus a global one) → `.writing/voice.md` in the project → in-session, offering to