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/validate.md
View on GitHub# `validate` subcommand (aliases: `lint`, `check`)
Lint a `BRAND-VOICE.md` against the canonical format. Read-only. Use to verify a hand-edited doc, a doc imported from another repo, or to check existing files when the canonical format evolves.
## Invocation
```bash
/brand-voice validate # check ./BRAND-VOICE.md
/brand-voice validate path/to/voice.md # check a specific file
/brand-voice lint ./assets/voice.md # alias
/brand-voice check # alias
/brand-voice validate --json # raw JSON output (CI)
/brand-voice validate -o ./assets/voice.md # explicit -o path
```
## Flags
| Flag | Meaning |
|------|---------|
| `[path]` positional | Target voice doc (default: `-o` value, else `./BRAND-VOICE.md`) |
| `-o <path>` | Same target as the positional, kebab-aligned with the rest of the skill |
| `--json` | Emit raw JSON per `references/schemas.md` § voice_lint.py instead of the human-readable report |
| `--allow-extends-outside-skill` | Suppress the `extends-path-outside-skill` warning when the chain references files outside the linted file's directory tree |
## Workflow
### 1. Resolve target path
In order of precedence: positional argument, `-o <path>` flag, `./BRAND-VOICE.md`. If the resolved path does not exist, exit with a clear error: *"`<path>` not found. Run `/brand-voice extract` first."*
### 2. Run the linter
```bash
python3 "$SKILL_DIR"/scripts/voice_lint.py <path>
```
The script returns JSON per [`references/schemas.md`](../references/schemas.md) § voice_lint.py. Three verdicts: `GREEN` (zero errors, zero warnings), `YELLOW` (warnings only), `RED` (errors).
### 3. Format the report
If `--json` was passed, stream the raw JSON to stdout and exit with the script's exit code (0 for GREEN/YELLOW, 1 for RED).
Otherwise, format human-readably:
```
BRAND-VOICE.md — validation report
==================================
Verdict: GREEN | YELLOW | RED
Path: <resolved path>
Stats: <N> sections (<N> required, <N> recommended), <N> rules, <N> forbidden lexicon
Errors (<N>):
✗ <code> [<field>] — <message>
line: <N>
Warnings (<N>):
⚠ <code> [<field>] — <message>
line: <N>
```
Sort errors before warnings. Within each, sort by line number ascending. Cap the report at 30 errors + 30 warnings; if exceeded, append a final line *"… and N more (run with `--json` for the full list)"*.
### 4. Surface fix suggestions
For each error code, append a one-line suggested fix per [`references/schemas.md`](../references/schemas.md) § "Error codes — fix strategy":
| Code | Suggested fix |
|---|---|
| `frontmatter-invalid-yaml` | Fix YAML syntax at the line cited. |
| `missing-required-field` | Add the missing field to the frontmatter. |
| `invalid-field-value` | Update the value to satisfy the constraint. |
| `duplicate-rule-id` | Rename one of the duplicates (rule_ids must be unique). |
| `missing-section` | Add the required H2 section. |
| `section-out-of-order` | Reorder the sections to canonical order. |
| `duplicate-section` | Merge or rename duplicate H2 headings. |
| `extends-cycle` | Break the cycle: a parent file references a descendant. Use `--chain` in `show` to inspect. |
| `extends-depth-exceeded` | Flatten the chain (max depth: 5) or restructure. |
| `extends-parent-not-found` | Fix `voice.extends` path; relative paths resolve against the child file's directory. |
| `extends-parent-invalid` | Fix the parent file (its errors are nested under `parent_errors`). Run `/brand-voice validate <parent>` for detail. |
| `replace-without-extends` / `remove-without-extends` | Remove the suffix key, or set `voice.extends` if inheritance is intended. |
| `replace-conflict-with-extending` | Pick one of the canonical field, `<field>_replace`, or `<field>_remove`. |
| `replace-on-unsupported-field` / `remove-on-unsupported-field` | The field is not on the inheritance whitelist. See `references/canonical-format.md` § Inheritance. |
| `core-attribute-missing-id` | Add `attribute_id: <kebab-case>` to the entry. Required on every `core_attributes` entry as the stable merge key. |
For warnings, no suggested fix (warnings are informational). The user decides whether to address them. The `rewrite-rule-overridden-by-child` warning suggests adding `override: true` to the entry if the override is intentional.
### Chain awareness
When the target declares `voice.extends`, the linter walks the chain (`resolve_extends_chain`), recursively lints each parent, and lints the merged result. The output gains:
- `chain` — root-first list of resolved file paths.
- `merged_stats` — aggregate stats after inheritance is applied.
- Each error/warning carries `source` (`"child"`, `"parent:<relpath>"`, or `"merged"`) and `source_path` (when the origin is outside the linted file).
`extends-parent-invalid` errors carry a nested `parent_errors` array with the actual parent failures so authors trace cascade failures to their origin.
### 5. Exit code
- `0` if verdict is GREEN or YELLOW.
- `1` if verdict is RED.
- `2` if the file does not exist or is not readable.
CI-friendly: a pre-commit hook can run `/brand-voice validate` and fail the commit if exit > 0.
## Use cases
- **Hand-edits** — the user added a section by hand and wants to confirm the doc still parses.
- **Spec evolution** — the canonical format moved from 11 to 4-required-7-recommended sections; an existing strict-format doc still passes validation; a future format change can be detected by re-running validate.
- **Cross-repo import** — pulling a `BRAND-VOICE.md` from a sister repo (per the cross-repo distribution patterns in `SKILL.md`); validate confirms the file is compatible.
- **Pre-commit hook** — CI runs `/brand-voice validate --json` on every PR that touches `BRAND-VOICE.md`. Exit code gates merge.
- **Drift detection over time** — pair with `/brand-voice diff <ref> HEAD` to see what changed; pair with `/brand-voice validate` to see if the changes still parse.
## Output examples
### GREEN
```
BRAND-VOICE.md — validation report
==================================
Verdict: GREEN
Path: ./BRAND-VOICE.md
Stats: 11 sections (4 required, 7 recommended), 12 rules, 27 forbidden lexicon
(no errors, no warnings)
```
### YELLOW (minimal doc — 4 required sections only)
```
BRAND-VOICE.md — validation report
==================================
Verdict: YELLOW
Path: ./BRAND-VOICE.md
Stats: 4 sections (4 required, 0 recommended), 1 rule, 2 forbidden lexicon
(no errors)
Warnings (7):
⚠ recommended-section-missing [section:tone by context] — recommended H2 section is missing
⚠ recommended-section-missing [section:pronouns and self-reference]
⚠ recommended-section-missing [section:format conventions]
⚠ recommended-section-missing [section:visual pairing]
⚠ recommended-section-missing [section:quick diagnostic]
⚠ recommended-section-missing [section:counter-examples]
⚠ recommended-section-missing [section:reference texts]
Verdict YELLOW: doc is valid but missing 7 recommended sections. To address, run /brand-voice update with new sources, or hand-edit the missing sections.
```
### RED (broken doc)
```
BRAND-VOICE.md — validation report
==================================
Verdict: RED
Path: ./BRAND-VOICE.md
Stats: 8 sections (3 required, 5 recommended), 11 rules, 0 forbidden lexicon
Errors (3):
✗ missing-required-field [forbidden_lexicon] — required frontmatter field 'forbidden_lexicon' is missing or wrong type
Fix: Add the missing field to the frontmatter.
✗ duplicate-rule-id [rewrite_rules[3].rule_id] — rule_id 'no-hedging' duplicates rewrite_rules[1]
Fix: Rename one of the duplicates (rule_ids must be unique).
✗ missing-section [section:rewrite rules — do/don't] — required H2 section is missing
Fix: Add the required H2 section.
Warnings (1):
⚠ recommended-section-missing [section:visual pairing]
Verdict RED: 3 errors block the doc from being considered valid. Fix the errors before running /humanize-en -f against this file.
```
## Edge cases
- **Empty file** — exit 2 with *"`<path>` is empty"*. Don't lint, don't crash.
- **File is not UTF-8** — exit 2 per `voice_lint.py` exit code spec. Surface the encoding error.
- **YAML parses but is not a mapping** (e.g., it's a list) — `frontmatter-invalid-yaml` error. Reported by the script.
- **No frontmatter at all** — `frontmatter-invalid-yaml` error with line 1 ("file must start with `---`"). Reported by the script.
- **Path does not exist** — exit 2 with the suggestion to run `/brand-voice extract`.
- **`--json` and human-format both requested** — `--json` wins. The flag toggles output mode.
- **Child syntactically RED, chain not resolved** — the linter returns early with child-only errors (the Validation order steps in `canonical-format.md`). Authors fix the child first; chain failures surface on the next pass.
- **Parent on the chain is RED** — child gets one wrapping `extends-parent-invalid` error per failing ancestor, with the ancestor's actual errors nested in `parent_errors`. Run `/brand-voice validate <ancestor>` to focus on a single layer.
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 |