Brand Voice in YAML: One Source for Humans and Agents

TL;DR

• YAML carries tone, banned words, and claim limits agents can load without parsing a PDF.
• Nathan voice prevails: 10_Personal/AI/Nathan's profile.md loads first; YAML is guardrails, not generic "brand voice."
• Keep narrative positioning in markdown; put interdependent generation rules in one YAML source both humans and models read.

What brand voice in YAML means

Photo by Thirdman from Pexels: https://www.pexels.com/photo/close-up-photo-of-a-tuning-fork-6194031/ Photo: TBD — Pexels "tuning fork"; credit photographer; Petralian (2026)

Brand voice in YAML means storing tone rules, banned phrases, claim limits, and channel overrides in a structured file both humans and agents load at session start. The PDF style guide can stay for designers. Generation needs a machine-readable source that does not require an agent to interpret twenty pages of narrative.

Who it is for: brand and content ops leads producing blog, email, and social through multiple AI tools who already accept that voice is a governance problem, not a prompting problem.

What you will learn: which fields belong in YAML vs markdown, how this complements (not replaces) the marketing voice playbook, and Path A for a ten-field voice file today.

Why PDF voice guides fail agents

Marketing teams already know the failure mode: a beautiful style guide launches, everyone applauds, nobody opens it during generation. Each chat tab invents adjectives. LinkedIn sounds hype; email sounds corporate; the blog sounds like a third brand.

Marketing and voice at scale maps Define → Enforce → Measure using markdown files, Golden Circle messaging, and editorial gates. That article owns workflow: content-batch routing, channel folders, session bootstrap.

This article owns structure: what to put in YAML so the same rules load in Cursor, a headless API, and a freelancer's ChatGPT project without copy-paste drift.

Use both markdown and YAML. Do not duplicate paragraphs across them. Markdown explains why. YAML states what is allowed.

Fields worth putting in YAML

Start small. Ten explicit fields beat fifty vague bullets.

Numeric ranges should match your parametric file if you have one (data/*.yaml in a repo, or equivalent). When SEO limits live in YAML and an agent cites different numbers in prose, you get the same drift class deliberate file memory warns about.

Example YAML sketch

Screenshot: brand voice YAML fields — Petralian (2026)

1schema_version: 12brand: ExampleCo3tone:4  primary: [direct, specific, constructive]5  avoid: [leverage, delve, robust, moat]6person:7  pronoun: first_person_singular8claims:9  max_superlatives_per_post: 210  require_source_for_stats: true11seo:12  description_chars: { min: 140, max: 160 }13banned_phrases:14  - in today's fast-paced15  - game changer16channels:17  blog:18    format: hybrid19  social:20    max_hashtags: 3

Agents read this in one tool call. Humans diff it in git. Neither has to grep a PDF.

How this relates to the marketing playbook

Read the pair in this order:

1. Knowledge Work Engine Part 3: Marketing for Golden Circle files, editorial folders, content-batch, and Define → Enforce → Measure governance.
2. This post when you are ready to extract enforceable fields into YAML and wire them into rules or API system prompts.

The playbook's voice-guide.md can shrink to narrative examples that point at voice.yaml for hard rules. SEO and GEO publish pipeline covers public-page legibility and metadata; YAML applies to private generation. Both reward explicit limits over hopeful prose.

Nathan voice prevails (not generic "brand voice")

YAML and slop lists are guardrails. They do not replace a named author voice. On Petralian I write as I / my — this is a personal blog. Direct. Concrete. No throat-clearing ("Great question," "Hope this helps," "Let's dive in"). Facts from files and ops, not invented stats.

Canonical source: D:\Obsidian\Obsidian\10_Personal\AI\Nathan's profile.md — short sentences, no em dashes, talk-through tone, operational risk flagging. Supporting layer: Brain System/Nathan/preferences.md (hedge/filler cuts). Fleet workflow: Marketing Copy — Nathan Voice and No Slop convention.

Load order matters. Agents read Nathan's profile first, then preferences, then brand-voice.yaml. If a YAML field and my voice conflict, profile wins and you fix YAML on the next promote pass.

Example implementation: how I run it

Screenshot: agent loading voice YAML — Petralian (2026)

On Petralian I split voice into four layers. Nathan voice sits on top.

Numeric SEO caps stay in data/harness-verify.yaml (seo_limits) so agents do not paraphrase character ranges.

When I direct agents to draft posts, the petralian-writing skill loads Nathan's profile first, then preferences, then YAML, then the Writing Session Guide, then a no-ai-slop detect pass before handoff.

The slop layer (not just YAML lists)

Word bans catch vocabulary drift. They miss structural slop: binary contrasts, colon reveals, fake-profound kickers, summary-recap endings. Peter Yang's no-ai-slop skill (vendored in Brain) handles that edit/detect workflow. YAML states what not to say; no-ai-slop states how not to structure a paragraph.

Pair both. Do not dump the skill's pattern list into YAML unless you want a 200-line file agents ignore.

Reference map (one table — details in linked posts)

Path A: one voice YAML this afternoon

1. Write or maintain your author profile in markdown (I use 10_Personal/AI/Nathan's profile.md). That file prevails over YAML.
2. Copy data/brand-voice.yaml from the Petralian repo (or the sketch above) to your shared drive.
3. Map one Sprinklr-style trait to a YAML row (do/don't → tone.primary / tone.avoid).
4. Vendor no-ai-slop beside it for structural edits.
5. Add five banned_phrases your team already jokes about (include moat if you are as tired of it as I am).
6. Set claims.require_source_for_stats: true if stats have burned you before.
7. Paste profile + YAML into any chat tool: "Nathan's profile wins on conflict; YAML is hard constraints; run no-ai-slop on the draft."
8. After review, add one new ban or limit from the edit. That is the promote step (Starr Measure loop).

No Cursor required. You are testing whether structured voice travels better than "sound like our brand."

Limitations

YAML cannot capture timing, cultural nuance, or legal nuance. High-risk claims still need human review.

Too many fields invite stale config. Review quarterly or when a channel strategy changes.

Freelancers outside your stack may ignore the file. Pair YAML with a one-page markdown example post they can mimic.

FAQ

Why put brand voice in YAML?

YAML is machine-checkable and diff-friendly; agents read the same tone rules humans edit without scraping marketing decks.

What belongs in voice YAML versus markdown guides?

YAML: banned phrases, reading level, pronoun rules, capitalization. Markdown: examples, narrative, and teaching.

Do agents follow voice YAML automatically?

Only if your harness loads it at session start and preflight checks cite the path.

Can voice YAML replace a style guide?

No. It parameterizes enforceable rules; the guide still teaches judgment and examples.

Where does Nathan voice fit?

Above YAML. 10_Personal/AI/Nathan's profile.md loads first (cadence and patterns). Blog body uses I/my — personal blog voice. YAML encodes bans and limits agents must not paraphrase. If they conflict, fix YAML after human review.

What to do next

If you already run the marketing engine playbook, extract ten enforceable rules into YAML this week. Wire them into one generation path (blog or email only). Measure rework minutes for two weeks. Expand fields only when markdown arguments repeat.

If you are starting cold, read Part 0: Engine guide for folder layout, then add voice.yaml beside voice-guide.md before you scale batch content.