coroboros/agent-skills / skills/brand-voice
brand-voice
VerifiedCreate, refresh, compare and validate BRAND-VOICE.md from web, Notion, local prose or an interview. Use for brand voice, writing style guide, founder/persona voice and voice.extends inheritance. Preserve manual sections and resolve source conflicts. Applying an existing voice to prose belongs to humanize-en -f.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 19.7 KB |
| evals/evals.json | config | 2.9 KB |
| references/canonical-format.md | markdown | 20.3 KB |
| references/example-chanel.md | markdown | 19.4 KB |
| references/example-multi-voice.md | markdown | 7.9 KB |
| references/interview-questions.md | markdown | 4.4 KB |
| references/schemas.md | markdown | 10.9 KB |
| references/source-resolution.md | markdown | 5.4 KB |
| scripts/extract_rules.py | script | 16.1 KB |
| scripts/lint_all.py | script | 3.9 KB |
| scripts/measure_corpus.py | script | 8.3 KB |
| scripts/utils.py | script | 28.7 KB |
| scripts/voice_lint.py | script | 25.5 KB |
| steps/diff.md | markdown | 6.3 KB |
| steps/extract.md | markdown | 9.7 KB |
| steps/show.md | markdown | 5.7 KB |
| steps/update.md | markdown | 6.5 KB |
| steps/validate.md | markdown | 9.0 KB |
steps/diff.md
View on GitHub# `diff` subcommand
Show what changed between two versions of a `BRAND-VOICE.md`. Read-only.
## Invocation
```bash
/brand-voice diff # working tree vs HEAD
/brand-voice diff HEAD~5 HEAD # 5 commits back vs HEAD
/brand-voice diff old.md new.md # two file paths
/brand-voice diff origin/main HEAD # vs remote main
/brand-voice diff -o ./assets/voice.md # custom file path, working tree vs HEAD
/brand-voice diff BRAND-VOICE-FOUNDER.md # single-arg form: child vs resolved parent (when child has `voice.extends`)
/brand-voice diff old.md new.md --resolved # diff merged outputs (chain-aware) instead of files-as-written
```
## Flags
| Flag | Meaning |
|------|---------|
| `-o <path>` | Target voice doc (default: `./BRAND-VOICE.md`) |
| (positional refs/paths) | One or two — git refs or file paths. **Single arg form** with a child file that declares `voice.extends` diffs the child against its resolved parent. |
| `--resolved` | Diff the merged outputs (after chain resolution and `_replace` / `_remove` overrides) instead of files-as-written. Use when one or both sides have `voice.extends` and you want to compare the *effective* voices. |
## Workflow
### 1. Resolve the two sides
The positional arguments determine what to compare:
| Args | Left | Right |
|------|------|-------|
| (none) | `git show HEAD:<target>` | working tree `<target>` |
| `<ref>` | `git show <ref>:<target>` | working tree `<target>` |
| `<ref-a> <ref-b>` | `git show <ref-a>:<target>` | `git show <ref-b>:<target>` |
| `<path-a> <path-b>` | `Read` `<path-a>` | `Read` `<path-b>` |
| `<child-with-extends>` | resolved parent (from `<child>.voice.extends`) | `<child>` itself |
**Single-arg form** — when the positional resolves to a file path that declares `voice.extends`, the diff treats the resolved parent as left and the child as right. Authors get *"what am I overriding?"* without writing the parent path manually. If the file does not declare `voice.extends`, the single-arg form falls back to the `<ref>` interpretation against `<target>`.
If `<target>` is not under git, error: *"`<target>` is not tracked by git. Pass two file paths to diff."*
### 2. Parse both sides
For each side:
- `split_frontmatter` to separate YAML from prose.
- `parse_yaml_minimal` to load the frontmatter as data.
- `list_h2_sections` to enumerate prose sections.
If parsing one side fails, surface the error and degrade to `git diff --no-prefix` output (raw diff, no semantic interpretation).
When `--resolved` is passed (or the single-arg form is used with a child declaring `voice.extends`), each side is additionally passed through `resolve_extends_chain` + `merge_voice_dicts` + `apply_replace_overrides` + `apply_remove_overrides` before diffing. The diff then reflects the *effective* voice each consumer sees, not the file-as-written. If chain resolution fails on either side (`extends-cycle`, `extends-depth-exceeded`, `extends-parent-not-found`), the diff aborts with the chain error and the user is directed to `/brand-voice validate` for diagnostic detail.
### 3. Compute semantic diff
#### YAML changes
For each frontmatter field:
- **List fields** (`forbidden_lexicon`, `required_lexicon`, `forbidden_patterns`, `voice.source_urls`) — show added (`+`), removed (`-`), unchanged count.
- **Object fields** (`sentence_norms`, `pronouns`, `contexts.*`) — show key-by-key adds, removes, modifications.
- **`rewrite_rules`** — match by `rule_id`. Show:
- `+ rule_id` for new rules
- `- rule_id` for removed rules
- `~ rule_id (reject/accept changed)` for modifications
- **Scalar fields** (`voice.name`, `voice.last_updated`) — show old → new.
#### Prose changes
For each section:
- *unchanged* — bytes-identical (after normalising trailing whitespace).
- *prose changed* — same heading, different content. Show a high-level summary (e.g., "+ 1 row in 'No hedging' table") rather than full unified diff. Full diff goes under a `<details>` collapsible.
- *added* — section present in right, absent in left.
- *removed* — section present in left, absent in right.
- *renamed* — the H2 heading text changed.
#### Manual sections
Manual sections (with `<!-- manual: true -->`) are diffed but flagged as `(manual)` in the output so the reviewer knows they were authored by hand, not synthesised.
### 4. Output format
```
BRAND-VOICE.md — diff <left-ref> → <right-ref>
==============================================
Frontmatter
-----------
+ source_urls: + 1 (https://example.com/v2)
+ last_updated: 2026-04-27 (was: 2026-01-12)
- forbidden_lexicon: - 1 (game-changer); + 3 (utopia, frictionless, holistic)
~ rewrite_rules:
+ no-marketing-cliche (reject: "world-class")
~ specific-over-abstract-speed (accept: changed)
Prose
-----
✓ Section 1 (Core voice attributes) — unchanged
✓ Section 2 (Rewrite rules) — + 1 table row
✓ Section 3 (Forbidden lexicon and patterns) — + 3 lines
✓ Section 10 (Counter-examples) — + 1 entry
✓ Section 12 (Brand mythology, manual) — unchanged
Stats
-----
Lines: 231 → 246 (+15)
Rules: 10 → 11 (+1)
Lexicon: 23 → 26 (+3)
Sections: 11 → 11 (unchanged)
```
### 5. Verdict line
The last line is a single-word verdict for tooling:
- `verdict: clean` — no changes.
- `verdict: minor` — additions only, no removals.
- `verdict: major` — removals or modifications to existing rules. Suggests the user re-test downstream prose.
## Why diff matters
A brand voice that drifts silently produces inconsistent prose. `/brand-voice diff` is the audit trail. Run it before merging a `update` PR. Run it monthly against the previous quarter to spot voice creep. The verdict line is grep-friendly for CI integration.
## Edge cases
- **Both sides identical** — output the verdict line `verdict: clean` and nothing else (above-the-fold UX).
- **Heading reordered** — surface as a *renamed*/*reordered* warning. Section order is normative; reordering changes the doc's contract for downstream consumers.
- **YAML field added** that does not exist in `canonical-format.md` — diff shows the addition with a `(custom field)` annotation; downstream consumers may ignore it.
- **Both sides have YAML parse errors** — fall back to raw `git diff` output. The diff is still informational.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |