The voice.md convention

Why this file exists

This proposed convention stands on the shoulders of repos already doing the work: Vercel Labs, Auth0, MetaMask, Sentry, NousResearch, Chakra UI / Ark, dxw, and adjacent standards such as AGENTS.md, llms.txt, brand.md, and CLAUDE.md.

Every team that lets an AI write on its behalf rediscovers the same problem: the AI sounds generic until you hand it a style guide, and there is no standard place to put one. Today that knowledge is scattered across brand-voice.md, tone-of-voice.md, TONE_OF_VOICE.md, editorial-voice.md, custom GPT instructions, Cursor rules, Notion docs, and Slack screenshots.

A single filename solves three problems at once:

1. Agents know where to look. A skill, a Cursor rule, or an MCP server can resolve voice.md deterministically — no configuration, no guessing.
2. Humans know where to put it. No more "which folder does the brand voice live in" tax on every new repo.
3. Tools can compose. A linter can check it. A test can enforce it. A CLI can scaffold it. A SaaS (hi, VoicePort) can deliver one.

voice.md is already in the wild — Vercel Labs, Auth0, MetaMask, Sentry, NousResearch, and 50+ other repos ship some form of it inside references/voice.md, .cursor/rules/voice.mdc, or root VOICE.md. This spec consolidates the convention so the next 5,000 repos do it the same way.

Prior art

This spec stands on the shoulders of repos already doing the work:

• Vercel Labs — agent-skills/skills/vercel-optimize/references/voice.md + a voice-drift.test.mjs linter
• Auth0 — agent-skills/plugins/auth0/skills/auth0-branding/references/capability-voice.md
• MetaMask / Consensys — .cursor/rules/editorial-voice.mdc
• Sentry — content-and-voice.mdx in their design system
• NousResearch — autonovel/voice.md
• Chakra UI / Ark — TONE_OF_VOICE.md
• dxw — playbook/tone-of-voice.md

Adjacent standards this spec deliberately complements:

• AGENTS.md — agent instructions, build commands (Linux Foundation Agentic AI Foundation)
• llms.txt — site context for LLMs (Answer.AI)
• brand.md — broader brand identity spec (thebrand.md)
• CLAUDE.md — Claude Code project instructions (Anthropic)

voice.md is the narrow, load-bearing piece those broader specs reach for when the task is write something that sounds like us.

File contract

A spec-compliant voice.md is:

• A single UTF-8 Markdown file
• Named exactly voice.md (lowercase), VOICE.md, or voice.mdc (Cursor variant). Resolvers MUST accept all three, case-insensitive on macOS/Windows filesystems.
• Self-contained - readable in isolation without external context
• Model-neutral - no syntax specific to one LLM, no system-prompt boilerplate
• Optionally front-mattered with YAML

That is the entire hard contract. Everything below is the recommended structure.

Resolution order

Agents and tools SHOULD look for voice.md in this order and use the first hit:

1. ./voice.md (project root)
2. ./.voice.md
3. ./docs/voice.md
4. ./references/voice.md (Anthropic Skills convention)
5. ./.cursor/rules/voice.mdc (Cursor convention)
6. ./.agents/<skill-name>/references/voice.md
7. ~/voice.md (user-global fallback)
8. $XDG_CONFIG_HOME/voice/voice.md

A tool MAY narrow this list. A tool MUST NOT invent additional locations without flagging the deviation to the user.

Recommended structure

---
voice_version: 0.1
subject: "Acme Co"                     # person, brand, character, persona
subject_type: brand                    # person | brand | character | persona
last_updated: 2026-05-27
---

# Voice

One paragraph: who is speaking, to whom, with what intent. Plain English.

## Pillars

Three to five short descriptors that define the voice.
- Confident, not cocky
- Plain-spoken, not folksy
- Specific, not vague

## Cadence and shape

How sentences and paragraphs move. Length, rhythm, structural tics.
- Short sentences first. Longer sentences earn their length.
- One idea per paragraph.
- Lists when comparing, prose when persuading.

## Vocabulary

### Use
Words and phrases that sound like us.

### Avoid
Words and phrases that do not.
- No "delighted", "thrilled", "journey", "leverage" (verb), "unlock", "robust"
- No em-dashes if the brand prefers commas. Pick a side.

## Anti-examples

Three to five short snippets that sound wrong, with a one-line note on why.

> "We are delighted to announce our new robust solution that unlocks growth."
> Why it fails: stacked AI tells, zero specifics.

## Examples

Three to five short snippets that sound right.

> "New feature. Two clicks. Ship faster."
> Why it works: matches the pillars, uses preferred cadence.

## Tone modes (optional)

Named variants for different contexts.
- `default` - house voice
- `support` - warmer, slower, no jokes
- `launch` - sharper, declarative, ends on a hook

## Checklist

A short list a writer or agent can run against a draft before publishing.
- [ ] No banned words
- [ ] First sentence under 12 words
- [ ] At least one specific noun in the opener
- [ ] Reads aloud without stumbling

The structural skeleton that ~80% of in-the-wild voice.md files already share: pillars → preferred/banned vocab → anti-examples → checklist. This spec just names it.

Frontmatter fields

All optional, all recommended.

Tools MAY add their own fields under a x_ prefix without breaking compatibility.

How agents should use voice.md

A spec-compliant agent SHOULD:

1. Resolve voice.md using the order above at the start of any content-generation task.
2. Load it into the context window before user instructions.
3. Treat the ## Avoid list as a hard constraint, not a suggestion.
4. Run the ## Checklist as a self-review pass before returning a draft.
5. If a tone_modes value is requested by the user (tone: support), apply that variant on top of the default.

An agent SHOULD NOT:

• Paraphrase or summarize voice.md into the prompt. Pass the file through.
• Mix multiple voice.md files in one task without telling the user.
• Edit voice.md without explicit user instruction.

Related files (the canonical trio)

voice.md works best alongside two siblings, also at the project root or inside the same skill folder:

• about-me.md — who the writer is, role, context, what they are working on
• audience.md — who the writing is for, their world, what they care about

Together: voice (how) + writer (who from) + audience (who to). Anthropic Skills, Resonance, charlie947, and digital-brain repos have all independently converged on this trio.

Conformance

A repo is voice.md-compliant if:

1. It contains a file matching the resolution order above.
2. The file is valid Markdown and renders without errors.
3. It contains at least one of: a ## Pillars section, an ## Avoid list, or named tone_modes.

A tool is voice.md-compliant if it implements the resolution order and the agent rules in the section above.

Self-certification is the only certification. There is no logo, no foundation, no dues.

Versioning

This spec uses single-digit semantic versions. 0.x is a draft window. 1.0 lands when:

• Three independent tools implement the resolver
• Three independent brands ship a voice.md referenced from this spec
• The conformance section has not changed for 60 days

Until then, expect movement. Pin a voice_version in your frontmatter if stability matters to you.

Contributing

This spec lives at https://voiceport.co/spec/voice-md (canonical) and is mirrored in the VoicePort repo. PRs welcome. The bar to land a change: at least one shipping implementation and at least one repo already doing it that way.