brand-voice-generate

Files (3)

• SKILL.md
• confidence-scoring.md · references/
• guideline-template.md · references/

SKILL.md (first lines)

# Brand Voice Guideline Generation

Turn discovered signal into a single source of truth for the brand's voice, then express it as
Bolta writer parameters so it's operational, not just a document.

## When to use
After `brand-voice-discover`, or whenever the user wants a formal voice guide. If no discovery
report exists in the session, run discovery first (or gather at least DNA + published posts).

## Tools this skill uses
| Tool | Why |
|-|-|
| `get-voice-context` | Anchor the guideline to Bolta's existing compiled voice, if any. |
| `list-business-dna` / `get-business-dna` | Confirm industry / audience / positioning for the mapping. |
| `extract-business-dna` | Optional — seed Business DNA by scraping the brand's website (needs a `url`; reaches the internet + uses credits). **Pass `set_as_default=false`** — it defaults to true and silently demotes the workspace's existing default DNA. |
| `update-business-dna` | **Edit** an existing DNA record — safe partial merge: pass only the changed keys in `fields`; omitted fields are preserved server-side. Covers tagline, colors/fonts/aesthetics, overview, local identity (city, service area, owner/staff), story, and image settings (logo placement, custom image instructions). |
| `list-voice-profiles` | Check whether a profile already exists (create new vs. evolve existing). |
| `create-voice-profile` | **Persist** the guideline as a native Bolta Voice Profile every agent then consumes. |
| `update-voice-profile` | **Evolve** an existing profile in place (partial update — omitted fields preserved). |
| `voice-generate` | Produce ONE sample draft to validate the mapping works end-to-end. |

Synthesis structure comes from `references/guideline-template.md`; scoring from
`references/confidence-scoring.md`. QA is done inline (Step 5).

## Prerequisites
- A discovery report (from `brand-voice-discover`) or equivalent gathered signal.
- `workspace_id` — reuse from discovery (resolve once via `list-workspaces`). Auth is automatic
  via the Bolta connector's OAuth grant — never ask for an API key. Default new content to
  Draft; confirm before persisting/overwriting a profile.
- `references/guideline-template.md` — output structure.
- `references/confidence-scoring.md` — how to score each section.

## Workflow

### 1. Assemble inputs
Take the discovery report. If thin, pull `get-voice-context` and `list-business-dna` /
`get-business-dna` to fill industry, audience, and positioning before synthesizing.

### 2. Synthesize the guideline
Following `references/guideline-template.md`, produce every section:
- **We Are / We Are Not** — at least 4 rows, each attribute paired with its opposite boundary,
  each backed by evidence from discovery.
- **Brand personality, messaging framework, terminology** (must-use / preferred / avoid / never).
- **Tone-by-context matrix** — at least 3 contexts (e.g. LinkedIn, X, cold email, proposal),
  each scored on formality / energy / technical depth.
- **Content examples** — before/after showing the voice applied.

### 3. Score confidence
Per `references/confidence-scoring.md`, assign High / Medium / Low to each section based on
evidence strength, volume, and source reliability (published posts and transcripts count as
behavioral evidence). Produce a confidence table and an aggregate weighted score.

### 4. Surface open questions — each WITH a recommendation
For every gap or conflict, write an open question AND a recommended default the brand can
accept as-is. Never leave a decision hanging without a recommendation.

### 5. QA
Guard the guideline before shipping it: verify all sections populated, 4+ We Are / We Are Not
rows, tone matrix covering 3+ contexts, 3+ attributes each with quoted evidence, confidence
assigned per section, every open question carrying a recommended default, sources attributed,
no PII, and the `voice-generate` parameter mapping present and faithful. Return pass or a
specific list of gaps and revise on them — never ship a partial guideline.

### 6. Express as `voice-generate` parameters — the operational half
Map the guideline onto Bolta's writer params so it drives generation immediately (see the
"voice-generate parameter mapping" section of `references/guideline-template.md`):
- `tone` ← the dominant register from the We-Are attributes + default tone-matrix row, as a
  short **string** (e.g. `"professional, direct"`) — `voice-generate` takes a string here;
  the 0-100 dials object belongs to `create-voice-profile`/`update-voice-profile` only.
- `dos[]` ← the "We Are" attributes and must-use / preferred terminology, as imperative rules.
- `donts[]` ← the "We Are Not" boundaries and avoid / never terminology.
- `custom_rules` ← nuanced rules that don't fit dos/donts (structural, formatting, tone flexes).
- `context` ← positioning + audience summary.
- `business_name` / `niche` ← from Business DNA.
Present this block as copy-ready — it's what makes the guideline enforceable.

### 7. Validate the mapping with one sample
Call `voice-generate` once with the mapped params (a single, low-`max_posts` sample on a
representative topic) to confirm the mapping yields on-brand output. Show the sample; if it
misses, tune the mapping and note what changed. Do not publish the sample.

### 8. Persist into Bolta — the durable half
Write the guideline back into Bolta so it drives the writer AND every autonomous agent, not
just this session. Confirm with the user before creating/overwriting, then:
- `list-voice-profiles` → decide **create** vs **evolve**.
- **New brand:** `create-voice-profile(workspace_id, name, tone={…dials…} OR writing_sample=<a
  strong on-brand excerpt>, tone_of_voice=[…], target_audience, dos, donts, content_size,
  pacing)`. Provide **either** a `tone` dials object **or** a `writing_sample` (≥50 chars) — the
  server extracts tone from the sample. Map the guideline's We-Are/We-Are-Not into `dos`/`donts`.
- **Evolving brand:** `update-voice-profile(workspace_id, profile_id, …only changed fields…)`.
  This is a partial update — omitted fields are preserved, so voice refines safely over time.
  Know its limits: it accepts only the structured fields (`name`, `tone` dials,
  `tone_of_voice`, `target_audience`, `dos`, `donts`, `content_size`, `pacing`,
  `speaker_mode`, `default_post_intent`, `business_dna_id`, `is_default`). The profile's
  prose fields (brand persona, custom rules, description) also drive the writer prompt but
  are NOT editable through this tool — if the drift you're correcting lives in that prose,
  say so honestly and point the user at the Bolta app to edit it; don't imply the evolve
  call fixed it.
- Optional: `extract-business-dna(workspace_id, url=<brand site>, set_as_default=false)`
  first to seed Business DNA, then reference it when generating. `set_as_default` defaults
  to **true** and silently demotes the existing default Business DNA — only omit it (or set
  true) when the user explicitly wants the new record as the workspace default; confirm
  first if a default already exists.
- If the guideline surfaced corrections to the brand identity itself — a sharper tagline,
  updated positioning/overview, brand colors, local identity details, or image styling — apply
  them with `update-business-dna(workspace_id, dna_id, fields={…only the changed keys…})`.
  It's a safe partial merge (omitted fields preserved), so users can just say "change our
  tagline to X" or "our brand colors are navy and sky blue" and you edit exactly that. Call
  `get-business-dna` first to show current values, and confirm before writing.

This is what makes brand voice foundational: the persisted profile flows into `voice-generate`,
ad-hoc drafts, and every hired agent automatically.

### 9. Save the document and hand off
Also save the human-readable guideline (session artifact) so `brand-voice-enforce` and
`brand-voice-validate` can consume it. Tell the user which profile was created/updated and that
every agent in this workspace now inherits the voice.

## Failure handling

From boltaai/bolta-skills, MIT.

More from boltaai/bolta-skills