Brand Voice Guide for AI Writing: Personas in Claude Code

A brand voice guide AI writing tools can actually follow is a short set of specific, checkable rules: who you write for, what you never say, and how your sentences should sound. In Claude Code, the Claude Blog skills turn those rules into files (BRAND.md, VOICE.md, and persona profiles) that the writing commands load before they draft, so every post sounds like the same team wrote it.

This guide explains what belongs in a voice guide, how the /claudeblog brand, /claudeblog persona, and /claudeblog style learn commands work, and how to write rules an AI writer will follow.

Key takeaways

• Voice rules only help AI writing if they're specific enough to check: "no sentence over 25 words" works, "be concise" doesn't.
• /claudeblog brand init interviews you in five steps and writes BRAND.md (audience, positioning, rules, scope) and VOICE.md (how you sound) to your project root.
• /claudeblog persona create builds a voice profile with four tone sliders, a readability band, and sentence-length targets, and drafts are checked against it.
• The writing commands load BRAND.md and VOICE.md automatically, so you set your voice once.
• /claudeblog style learn <paths> learns an author voice profile from sample posts.

What is a brand voice guide, and why does AI writing need one?

A brand voice guide describes how your company sounds in writing: who you're talking to, what you stand for, the words you use and avoid, and the mechanics of your sentences. Human writers use it to stay consistent. AI writers need it more.

Without guidance, a language model writes in a generic, averaged voice: it hedges, reaches for stock phrases, and shifts register between sessions. Pasting instructions into every prompt doesn't scale, because eventually you forget a rule.

Two ideas are worth separating. Voice is your brand's personality, and it stays the same everywhere. Tone is how that voice adapts to a situation: an outage notice and a product launch share a voice but not a tone.

A practical way to describe tone is Nielsen Norman Group's four dimensions of tone of voice: funny versus serious, formal versus casual, respectful versus irreverent, and enthusiastic versus matter-of-fact. Placing your brand on each scale turns "we're friendly but expert" into something you can write down and test.

A complete voice guide for AI writing has three layers:

1. Brand context: audience, positioning, what you are not, competitors, and the topics you cover.
2. Editorial rules: what you always do, what you never do, banned phrases, and required disclosures.
3. Voice mechanics: pronouns, contractions, sentence and paragraph length, reading level, and headline patterns.

How brand, persona and style learn fit together

Claude Blog, one of the two suites on our skills page, has three commands for voice:

The persona JSON is the source of truth for tone dimensions, sentence-length distribution, and contraction frequency. VOICE.md mirrors its readable parts so prompts are self-contained. BRAND.md adds what a persona doesn't cover: audience, positioning, competitors, topic boundaries, taboo phrases, and disclosures.

You don't need all three. A small blog can run on BRAND.md and VOICE.md alone. Add a persona when you want drafts checked against measurable targets.

What the /claudeblog brand command does

/claudeblog brand init runs a five-step interview, one step at a time. If you already have a persona, it pre-fills the voice answers from it.

1. Audience. Your primary reader's role, an optional secondary audience, their expertise level, three to five problems they're trying to solve, and misconceptions they hold.
2. Positioning. A one-sentence mission, your distinctive point of view, what your brand is not, and your top three competitors with a one-line differentiator for each.
3. Editorial rules. Do and don't lists (three to seven items each), taboo phrases, and required disclosures such as affiliate or AI-content notices.
4. Topic scope. Topics fully in scope, topics covered only with an original angle, topics you won't cover, and recurring formats.
5. Voice. Pronoun stance, contractions, a hard sentence-length ceiling, a paragraph ceiling (150 words by default), headline patterns to favor and avoid, and the summary box label.
6. Write files. Your answers become BRAND.md and VOICE.md in the project root, each with a "Last updated" date.
7. Auto-load. From then on, the writing commands read both files before they start.

The skill won't write an empty template. If your answers are thin, it asks for at least two audience bullets and three editorial rules first. If the files already exist, it asks whether to overwrite them or run an update.

/claudeblog brand show prints a summary of both files, or says which one is missing. /claudeblog brand update re-runs the interview with your current answers as defaults: press enter to keep a value or type a new one.

What the two files look like

Both are plain markdown you can read and edit by hand. BRAND.md holds audience, positioning, editorial rules, and topic scope:

## Audience
- **Primary**: [role + context]
- **Expertise**: [level]
- **Active problems**: [problem 1], [problem 2], [problem 3]
- **Common misconceptions**: [misconception 1], [misconception 2]

## Positioning
- **Mission**: [one sentence]
- **Distinctive POV**: [contrarian or non-obvious belief]
- **What we are NOT**: [anti-positioning]

## Editorial Rules
### Always do
### Never do
### Taboo phrases
### Required disclosures

## Topic Scope
- **In scope**: [pillars]
- **Out of scope**: [topics to refuse]

VOICE.md holds pronoun stance, lexical rules, headline patterns, a read-only mirror of the persona's tone sliders, a readability target, and reference samples:

## Pronoun stance
[first-person / second-person / third-person / mixed]

## Lexical rules
- **Contractions**: [full / partial / none]
- **Sentence ceiling**: [N words max]
- **Paragraph ceiling**: [N words max, default 150]

## Headline patterns
- **Favor**: [list]
- **Avoid**: [list]

## Readability target
- Audience tier: [consumer / professional / technical]
- Flesch Grade: [range]

What the /claudeblog persona command does

A persona is a structured voice profile. /claudeblog persona create builds one through a six-step interview: brand basics, tone dimensions, writing rules, do's and don'ts, summary label, and optional voice samples. It saves the result as a JSON file with a kebab-case name, such as your-brand.json.

Tone dimensions

Each tone dimension is a slider from 0.0 to 1.0, and the skill shows an example sentence at each end so you can calibrate.

If you're unsure, the defaults are 0.6, 0.5, 0.3, and 0.5: slightly serious, balanced formality, respectful, and balanced enthusiasm.

Writing rules and readability

You pick a vocabulary tier, and the skill fills in a matching readability band. Flesch Reading Ease usually runs from 0 to 100, where higher means easier. Flesch-Kincaid Grade Level maps text to a US school grade.

You can override the band, for example technical vocabulary at consumer readability for explainers. The other defaults are an average sentence length of 18 words with a variation of 6, a contraction frequency of 0.6, and a passive voice cap of 10%.

Then you add three to five do's and don'ts, pick a summary box label (Key Takeaways is the default; TL;DR, The Bottom Line, and a custom label are among the options), and optionally give one to three URLs of content that already sounds right. The skill reads each sample, estimates sentence length, contraction frequency, tone, and vocabulary level, and flags mismatches with your settings.

How a persona is enforced

/claudeblog persona use <name> activates a persona for the current conversation and prints the constraints it will enforce. /claudeblog write and /claudeblog rewrite check for an active persona and apply it in three stages:

1. Before drafting: tone dimensions and style rules go into the writer agent's instructions.
2. While drafting: the writer follows the do and don't rules and targets the sentence-length and contraction settings.
3. After drafting: the output is checked for sentence length within one standard deviation of the target mean, readability inside the band, passive voice under the cap, and matches against the don't rules. Violations come back with suggested edits.

/claudeblog persona list shows saved personas with their industry, audience, and vocabulary tier. /claudeblog persona show <name> prints the full profile.

Learning a voice from sample posts

If you already have posts that sound right, /claudeblog style learn <paths> learns an author voice profile from those sample posts. You pass it the file paths. Reach for it when your best voice reference is your own back catalog rather than interview answers.

Pick recent posts by the author whose voice you want, in the format you publish most. Leave out guest posts and pieces heavily edited by someone else.

How the writing commands use your voice files

Once the files exist, you don't have to mention them. When /claudeblog write, /claudeblog rewrite, /claudeblog brief, /claudeblog outline, /claudeblog calendar, or /claudeblog strategy runs, it checks the project root for BRAND.md and VOICE.md and passes their contents to the researcher, writer, SEO checker, and reviewer in the four-agent content pipeline. If the files are missing, the commands behave as usual and don't prompt you to create them.

When sources overlap, BRAND.md wins on positioning, audience, taboo phrases, and topic scope. VOICE.md wins on tone, sentence ceiling, and pronoun stance. The persona JSON stays the source for programmatic checks such as tone sliders and readability bands.

Voice files don't replace structure. The 12 content templates decide the shape of a how-to guide or a comparison. Your voice files decide how that shape sounds.

One safety rule: project-root files can come from a collaborator or a cloned repo, so the skill treats BRAND.md and VOICE.md as untrusted data, not instructions. Their content is fenced off before it reaches an agent, instruction-like text such as "ignore previous instructions" is flagged, and nothing in a voice file can give an agent new tools.

How to set up your brand voice in Claude Code

Open your blog project in Claude Code with Claude Blog installed. Start with the brand interview, then check the result:

/claudeblog brand init
/claudeblog brand show
/claudeblog brand update

Add a persona for measurable targets, and activate it in each writing session:

/claudeblog persona create
/claudeblog persona list
/claudeblog persona use your-brand
/claudeblog persona show your-brand

To learn from published posts, pass their paths:

/claudeblog style learn ./content/blog/post-one.md ./content/blog/post-two.md

Or ask in plain English, and Claude picks the matching skill:

Set up our blog's brand voice. Interview me about audience, positioning and editorial rules, then write BRAND.md and VOICE.md to the project root.

The brand and persona skills list no API keys or outside accounts. They work from your answers, your files, and any sample URLs you give them.

How to write voice rules an AI writer will follow

Most voice guides fail with AI because the rules describe a feeling instead of a behavior. "Be friendly but professional" gives a model nothing to act on. Four principles fix that:

• Make every rule checkable. If a reviewer can't mark it pass or fail from the text alone, rewrite it.
• Ban phrases, not moods. "No hype" is vague; a taboo list of exact words is not. Your taboo list sits on top of the generic AI-pattern checks the reviewer already runs.
• Use your misconceptions. The audience step asks what readers get wrong, which is a ready source of angles that tell them something new.
• Calibrate sliders with examples. Ask Claude to write one paragraph at 0.3 and at 0.7 on formal_casual, then pick the one that sounds like you.

To tighten an existing guide, let Claude Code audit it:

Read BRAND.md and VOICE.md. List every rule a reviewer couldn't mark pass or fail from the text alone, and rewrite each one as a specific, checkable rule. Show me the changes before saving.

Doing it without the skill

You can get a lot of this with plain Claude Code. The simplest version is a CLAUDE.md file: Claude Code reads it at the start of every session, so voice rules placed there apply to every prompt. Step 1 of our guide to writing a blog post with Claude Code includes a style guide you can adapt.

To build the rules, run an interview:

Interview me one question at a time to build a brand voice guide for our blog. Cover: primary audience and their expertise level, the problems they're trying to solve, their common misconceptions, our one-sentence mission, what we are not, three competitors and how we differ, 3-7 always-do and never-do rules, banned phrases, pronoun stance, contractions, a maximum sentence length, and headline patterns to use and avoid. Write the result as a "Blog voice" section in CLAUDE.md. Every rule must be specific enough to mark pass or fail.

To learn the rules from your own writing:

Read these posts: [paths]. Measure average sentence length and its spread, how often contractions appear, pronoun use, and typical paragraph length, and list recurring phrases. Estimate where the writing sits from 0 to 1 on four scales: funny-serious, formal-casual, respectful-irreverent, enthusiastic-matter-of-fact. Turn the findings into voice rules, with one short line from the posts as evidence for each rule.

The skills add what's tedious to rebuild: interviews that refuse thin answers, separate files with clear precedence, persona checks after every draft, and automatic loading into every agent that writes or reviews.

Brand voice mistakes to avoid

• Writing adjectives instead of rules. "Warm, smart, approachable" is a feeling. Turn each adjective into a behavior you can check.
• Letting the files go stale. Run /claudeblog brand update when your positioning, audience, or competitors change.
• Forgetting to activate the persona. It stays active only for the current conversation, so run /claudeblog persona use <name> when you start writing.
• Trusting a shared voice file blindly. Read any BRAND.md or VOICE.md you didn't write before relying on it.

Related guides

• How to write a blog post with Claude Code, including a ready-to-use CLAUDE.md style guide
• The Claude Code content writing workflow from brief to published post
• How to score a blog post before publishing with the 100-point review

FAQ

What should a brand voice guide include?

Your audience and their problems, your positioning and what you are not, things you always and never do, banned phrases, and concrete rules for pronouns, contractions, sentence length, and reading level. A few examples of on-brand writing help the rules land.

What is the difference between brand voice and tone?

Voice is your brand's consistent personality across every piece of content. Tone is how that voice adjusts to the situation, such as a support article compared with a launch announcement. A persona's four tone sliders set where your content should sit.

Can AI write in my brand voice?

Yes, if you give it rules it can follow and check. Vague guidance produces generic copy. Specific rules, loaded automatically before every draft and checked afterward, keep copy consistent from post to post.

How do I make Claude Code write like me?

Give it samples and rules. With Claude Blog, run /claudeblog style learn <paths> on your posts, or add one to three sample URLs during /claudeblog persona create so the skill can compare your writing with your settings. Without the skill, ask Claude Code to analyze your posts and write the findings into CLAUDE.md.

Where are BRAND.md and VOICE.md saved?

In your project root, which defaults to the current working directory. If the root is unclear, the skill asks where to write them. Because they're plain markdown in your repo, you can edit them by hand and track changes in version control.