defining-a-voice
Skill3 starsChanged 3 days agoMITView on GitHub
Use when a brand needs its voice written down, or when copy is being written or reviewed for one: before writing any interface, marketing or web copy for a brand, to find its voice guide and apply it; when starting a new client or product; when copy sounds "off-brand", "not us", too jokey, too stiff, robotic or like every other SaaS; when a line jokes in an error, celebrates a routine task, shouts with exclamation marks or ALL CAPS, drifts between "we" and "you", or uses a word the brand avoids; when two surfaces of one product sound like different companies; or when someone asks for a tone of voice, brand voice, voice and tone guide, VOICE.md or BRAND.md. Owns the precedence rule: the brand's guide sets tone, the clarity rules hold regardless. Not for the wording rules themselves (writing-interface-copy, writing-marketing-copy).
In this repository71 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- clud-bug-collaborationSkill
- critical-issues-onlySkill
- evidence-based-reviewSkill
- respect-existing-conventionsSkill
- skill-frontmatter-qualitySkill
- apca-contrastSkill
- api-contract-enforcementSkill
- brand-voice-reviewSkill
- chroma-harmonizationSkill
- clud-bug-collaborationSkill
- component-sizing-principlesSkill
- component-sizingSkill
- composing-a-screenSkill
- consuming-a-design-systemSkill
- conventions-templateSkill
- critical-issues-onlySkill
- curating-a-skill-catalogSkill
- designing-a-design-systemSkill
- designing-elite-uiSkill
- design-system-consistencySkill
- design-token-namingSkill
- dtcg-formatSkill
- empirical-design-principlesSkill
- evidence-based-reviewSkill
- finding-a-catalog-skillSkill
- frontend-a11ySkill
- guarding-a-regressionSkill
- ios-safari-surfacesSkill
- line-height-gridSkill
- logmindSkill
- making-decision-artifactsSkill
- motion-continuitySkill
- oklch-color-spaceSkill
- orchestrating-agent-delegationSkill
- orchestrating-a-multi-agent-runSkill
- orchestrating-elite-agent-qaSkill
- palette-relationshipsSkill
- pii-and-complianceSkill
- proving-an-absenceSkill
- respect-existing-conventionsSkill
- retiring-a-superseded-decisionSkill
- reviewing-design-workSkill
- semver-design-tokensSkill
- session-heartbeatSkill
- skillforgeSkill
- skill-frontmatter-qualitySkill
- spacing-systemSkill
- technical-writingSkill
- test-disciplineSkill
- thrill-designSkill
- token-frugal-toolingSkill
- token-naming-conventionsSkill
- type-scaleSkill
- udts-component-sizing-laddersSkill
- udts-dtcg-extensionsSkill
- udts-linter-rulesSkill
- udts-naming-conventionSkill
- udts-reviewSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 6 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 28
Before writing copy for any brand: find its guide first.
- Distinctive: line 48
Every section of voice-template, in that order.
- Distinctive: line 60
Look in this order and use the first guide found:
- Distinctive: line 68
Applying it: read the traits and the tone-map row for this moment, write, pass the clarity skill's checks, then the checks below.
- Distinctive: line 77
Avoid list: No word from the guide's avoid list.
- Distinctive: line 92
Every trait has a "not" and both examples.
≈ “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.
Files
Defining a voice
A voice guide says how one brand sounds. This skill says what a guide must contain, where it lives, how a writer finds it, and what wins when it collides with clarity. The fill-in scaffold is voice-template. Why we hold these: references/sources.md.
When to use
- Writing or revising a brand's voice guide, or starting a client.
- Before writing copy for any brand: find its guide first.
- Reviewing copy for tone, register, shouting or pronoun drift.
When NOT to use
- Wording rules — interface strings are writing-interface-copy; pages, decks and taglines are writing-marketing-copy. Docs are technical-writing.
- A house's own filled guide — read it from that house's L2 stance.
Precedence
The brand's guide sets tone. The clarity rules hold regardless. The clarity rules are the two writing skills above plus accessibility. A guide may tighten one of them and never loosen it; where a guide is silent, the generic rule applies. When a trait, joke or flourish makes the meaning, the next step or a label less clear, cut the flourish. As Mailchimp's guide has it, "it’s always more important to be clear than entertaining."
So the calls that vary by brand (whether to say "we", whether to apologise, how much emotion to show) are made in its guide, inside the clarity rules. Holds when: no line of copy keeps a voice choice that breaks a clarity rule, and a review that finds one cites the clarity rule.
Voice and tone
Voice is who the brand is, and it does not change between screens. Tone is how far each trait comes through in one moment. Key tone to the situation (an error, a first run, a milestone), with the reader's likely state as a note, not a guess at their feelings. The more serious the moment, the more neutral the tone.
What a guide contains
Every section of voice-template, in that order. The ones that fail silently when skipped:
- Traits: three to five, each "X, not Y", with one do and one don't example. The "not Y" is the part a reviewer can cite; "friendly" alone licenses anything. Fix: give every trait its boundary.
- A tone map, one row per situation or channel — everyday UI, onboarding, success, celebration, minor and severe errors, bad news, legal, marketing, support — each setting how loud each trait is, with an example line. Fix: a guide with no error row has not been tested on the moment that matters.
- A baseline on four scales — formal to casual, serious to funny, respectful to irreverent, matter-of-fact to enthusiastic — plus a few target tone words and their anti-words. Stay off the extremes. Lean conversational but credible: when friendliness and trust pull apart, choose trust.
- Humour: off unless the guide turns it on, for named channels. "Humor is extremely risky, because when it fails, you annoy and alienate your users" (Kate Moran, NN/g). Never in an error that blocks a task, a failure, money or health trouble, legal, security or support; on a page like a 404, only beside the way out, never in place of it. When on: one light touch, with the reader, never at them; cut it if the line repeats often or won't survive translation.
- Person and pronouns, stated outright: who "we" is, whether the brand says "I", how it addresses the reader. Brands differ on "we", so a silent guide leaves every writer guessing.
- Vocabulary: words used, words avoided (the team's jargon and the industry's buzzwords), and names that never vary.
- Exceptions and owners: legal, security, incidents, vulnerable customers — how far each drifts from the voice and who signs it off.
Where the guide lives, and how a writer finds it
Look in this order and use the first guide found:
- The house's or brand's L2 stance, if loaded, and the guide it links.
- A voice skill copied from the template:
.claude/skills/voice-<brand>/SKILL.md(or.agents/skills/). VOICE.mdorBRAND.mdat the repo root, ordocs/voice.md.
Prefer 2 in any repo reviewed in CI: it loads like any skill. Found two? Say so and ask; don't merge them. Found none? Write in a neutral register — plain, conversational, serious, no humour, no exclamation marks — and say in the change that no voice guide exists. Never invent a voice.
Applying it: read the traits and the tone-map row for this moment, write, pass the clarity skill's checks, then the checks below.
Voice checks
These hold under any guide unless it says otherwise, and none can loosen a clarity rule.
- Shouting. No exclamation marks in errors, warnings or routine confirmations ("Saved!" → "Saved."); save them for a real milestone, if the guide allows them at all. No ALL CAPS for running text: it is hard to read. Acronyms and codes (USD, API) are fine. Test:
grep -nE '!|\b[A-Z]{4,}\b|\b[A-Z]{2,}( [A-Z]{2,})+\b' strings(an exclamation, a long capitalised word, or a run of them); read each hit. - Pronoun drift. One stance per message. "We need you to confirm before you can continue, and then we'll send you a code" → "Confirm your phone number. You'll get a code by SMS." Test: in each message, list the pronouns; "we" and "you" may both appear only as the guide's person rule allows.
- Register. Each line matches its tone-map row: no joke or "Oops!" in an error, no "Hurray!" for a routine task. Test: tag each string with its situation and read it against that row.
- Avoid list. No word from the guide's avoid list. Test: grep the list.
Reviewing copy
Report a voice finding as writing-interface-copy reports any copy finding — string quoted, file and line, a replacement — naming the trait or tone-map row it breaks. "Could be more on-brand" is not a finding.
Silent failures
- The guide the reviewer never reads. A CI reviewer that reads only
SKILL.mdnever sees aVOICE.mdor areferences/file: the review goes green and tone is never checked. Ship the guide as a skill, or state the rules a reviewer must hold in the stance's ownSKILL.md. - Voice everywhere. Personality in an error or a legal notice reads as flippant, and costs trust. The serious rows of the map turn it down.
- The invented voice. With no guide, an agent drifts to a generic "friendly, playful" voice. Use the neutral register and report the gap.
Verification
- The guide was found by the order above, or its absence was reported.
- Every trait has a "not" and both examples; the tone map has error and serious rows.
- Copy passed the clarity skill first, then its tone-map row and the voice checks.
- A new guide was tried on readers: give them samples and ask which tone words fit.
Cross-references
- Owns precedence for: writing-interface-copy, writing-marketing-copy.
- Scaffold: voice-template. One filled guide: thrill-design.
- Inside another system: consuming-a-design-system — obey its guide.
- Review route: reviewing-design-work copy lens.
Sources
Why we hold these: references/sources.md.
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.

