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 save. Every rejection the user makes appends to the file with the reason. After ten pieces it knows things no interview would have surfaced.

Keep the mirror too: the anti-voice list, the exact things this user hates.

3. Write

• Sweep the category first when the format competes for attention (posts, landing pages, marketing, launches) or is unfamiliar: read 3–5 strong recent human examples of the format, extract shape and stance, never phrasing. Research answers "what shape wins here", the voice profile answers "how you sound inside it" — different questions, both improve the piece, and one line states whether you swept or went straight in. For non-English culture-bound formats this stops being optional (§7).
• Lead with the payload. The answer is sentence one, not sentence four.
• Cut the setup. Most opening paragraphs are throat-clearing. Delete down to the first real sentence.
• Three openers before the body. The first sentence sets the voice of everything after it, and copy that dies in sentence one never recovers.
• High-stakes single lines get candidates, not a verdict. Tagline, headline, button label, subject line: deliver 2–3 real options and let the user point. One line carrying a whole surface is exactly where their taste beats your judgment.
• Concrete beats abstract. A number, an object, a scene beats an adjective.
• Show the change, not the category. "Agents stop overwriting each other" beats "improved coordination."
• Vary sentence length deliberately. Three same-length sentences in a row is the strongest AI tell there is, stronger than any word choice.
• Explain only what the reader cannot infer. When explanation is genuinely needed, one concrete example does the work of three abstract sentences.
• Calibrate confidence. State opinions as opinions with no cushioning; make real uncertainty visible instead of smoothing it over. Agents invert this by default.
• Scan surfaces scan. README, landing, posts, release notes: short sentences, fragments legal, numerals not words (13 skills, never "thirteen skills"), bullets when items are genuinely parallel. Long woven sentences are for essays and stories. The same detail can almost always be delivered as a strong lead line plus short fragments.
• Stack the hook. One logical unit per line, white space between them as the pacing. Stacked lines read like a poster; the same words in a paragraph read like homework. In Markdown, single newlines merge when rendered — use blank lines so the break survives.
• The first-interface jargon gate. On any first-touch surface, every term must survive a reader with zero context. If a word only makes sense after the product is understood ("claim", "wire", "injected context"), replace it with what it does, or teach it in the same breath.

Brevity is not the goal. Density is. Cut what doesn't earn its place; keep what the reader needs even when it runs long. Warmth costs words sometimes and that's fine. Copy that's been cut to the bone is robotic in the other direction.

4. The audience firewall

End-user text never mentions the machinery that produced it. No rules, no constraints, no process, no "as requested", no "to keep this brief", no apologizing for what isn't included. The reader gets the result, never the making of it.

Same section, same principle: no "in this article we will," no announcing the structure, no telling readers what they just read.

5. Subtract

1. Cut 30%, then look at what broke. What survives is better and the wreckage shows you where the fat lives.
2. Shape tells before word tells. The strongest AI signal now is structure, not vocabulary: bulleted lists with bolded lead-ins, rule-of-three sections, the summary nobody asked for, one emoji per feature. Word-level filters pass all of these straight through. references/tells.md has both, tiered.
3. The obvious-sentence test. Scan for anything a person who actually knew the subject wouldn't have bothered to write down.

6. Review and refine

When auditing existing copy (yours or theirs):

1. Read as the target reader and mark the exact sentence where they'd stop. One mark, worth more than any score. 1b. Trace the eye path. Read only what a scanner sees: headings, bold leads, first lines, stacked hook lines. Does that skeleton alone make the case? Most readers never read anything else — if the skeleton doesn't sell it, the prose never gets the chance.
2. Diagnose on five dimensions, as a reading and not a gate: directness, rhythm, trust, authenticity, density.
3. Rewrite, then show only the 3–5 sentences that changed most, side by side, one line of reasoning each. Never a full diff.
4. Append whatever they reject to the voice profile.
5. Sort each correction: taste or craft. Personal taste ("I hate em dashes") goes to voice.md. Universal craft (a jargon gate, a rendering gotcha, a scan rule) is a bug in this skill — propose adding it here, so every future project inherits the fix instead of relearning it. A correction filed in the wrong place is a lesson that doesn't compound.

7. Language

Compose natively. Never write English and translate. Translation carries English sentence architecture, and that is the single loudest tell in most languages.

Register is a grammatical decision in most languages, not a word choice: settle it in the target language's own system (formality level, keigo, du/Sie, tu/vous) before drafting. Length norms, valued rhythm, and typography are local too, so English brevity dogma and the English tells list do not travel. Density travels. Word counts don't.

Read 3–5 real human examples first when the format is culture-bound (marketing, social, humor) or the register call is load-bearing. Say in one line which path you took, so the reader of your work knows whether it was researched or improvised. If your own command of the target language is shaky, say so and offer research rather than producing fluent-looking mediocrity. Details: references/languages.md.

Code lane

This skill has zero authority over code structure, depth, error handling, or test coverage. It governs only the prose inside code, and "fewer comments" is not the goal. Fewer empty comments is.

• Comments answer why. The what is the code's job.
• Docstrings: one line on what a caller gets. Add the FR-XX reference when one exists, so the trail to the spec exists without copying the spec into the file.
• A non-obvious algorithm, an invariant, or a workaround gets one to four plain sentences, written for a tired engineer at 2am.
• Never delete a comment carrying information the code doesn't: a reason, a link, a gotcha, a license note.

References (load on demand)

file	when
voice-menu.md	choosing or blending a voice, building a profile
formats.md	the physics of a specific format (README, landing page, post, blog, email)
ui-copy.md	microcopy: errors, empty states, buttons, tooltips, onboarding
tells.md	auditing or de-slopping existing text
languages.md	writing in any language other than English

Peers

swarm-design-ui hands over every string in its component inventory · swarm-implement routes user-visible strings here · swarm-review audits shipped copy against voice.md. With no vault present the skill runs unchanged on .writing/voice.md (§2), same as the rest of the catalog.

---

Influences: Wikipedia's "Signs of AI writing" via blader/humanizer; kjmagnan1s/anti-slop (tiered tells, protect-list, scoring); haowjy/creative-writing-skills (llm-writing, reader-reward channels); content-designer/ux-writing-skill; ComposioHQ content-research-writer — see CREDITS.md.