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/show.md
View on GitHub# `show` subcommand
Print a flat list of testable rules from the voice doc — no prose, no rationale, no headings. Designed for inclusion in another skill's prompt.
## Invocation
```bash
/brand-voice show # default: --rules, target ./BRAND-VOICE.md
/brand-voice show --rules # only the testable rules
/brand-voice show --examples # only the rewrite_rules examples
/brand-voice show --all # rules + examples + counter-examples
/brand-voice show --raw # child-only — skip extends chain resolution
/brand-voice show --chain # print the resolution chain (root → child)
/brand-voice show --explain # annotate each rule with its origin file
/brand-voice show --legacy # v1 minimal output (back-compat)
/brand-voice show -o ./assets/voice.md # custom target
```
## Flags
| Flag | Meaning |
|------|---------|
| `-o <path>` | Target voice doc (default: `./BRAND-VOICE.md`) |
| `--rules` | Print the testable rule block (default) |
| `--examples` | Print only the `rewrite_rules` `reject → accept` table |
| `--all` | Print rules, rewrite_rules examples, and counter-examples section |
| `--raw` (script flag: `--no-resolve-extends`) | Skip `voice.extends` chain resolution; print child-only rules |
| `--chain` | Print the resolution chain instead of rules: `child.md → parent.md → grandparent.md (depth N)` |
| `--explain` | Annotate each rule with `# from <relpath>` origin file |
| `--explain-json` | Emit structured provenance JSON instead of plain text |
| `--legacy` | Emit the v1 minimal output (no `core_attributes`, `contexts`, `source_urls`) for back-compat consumers |
| `--allow-extends-outside-skill` | Suppress the `extends-path-outside-skill` warning when resolving the chain |
## Workflow
### `--rules` (default)
Run `python3 "$SKILL_DIR"/scripts/extract_rules.py <target>`. Stream stdout directly to the user. Output shape per `references/schemas.md` § extract_rules.py.
This is the same path `humanize-en -f` uses internally. `show --rules` is the human-readable verification: "what rules will downstream skills see?"
By default, when the target declares `voice.extends`, the chain is resolved automatically and the rules block reflects the merged voice. Pass `--raw` to inspect the child file's declarations only.
### `--chain`
Print the resolved inheritance chain, root-first:
```
target: ./BRAND-VOICE-FOUNDER.md
chain (depth 1):
./BRAND-VOICE.md (root)
./BRAND-VOICE-FOUNDER.md (this)
```
Files that declare no `voice.extends` print a single line: *"target has no inheritance chain."*
### `--explain` / `--explain-json`
`--explain` runs `extract_rules.py --explain` and streams the result. Each merged rule gains a `# from <relpath>` suffix so the author sees which file in the chain contributed it. Useful for audit ("why is this rule here?") and review ("did the override land where I wanted?").
`--explain-json` emits structured provenance for tooling. See `references/schemas.md` § extract_rules.py for the schema.
### `--examples`
Read the target file, parse the frontmatter, emit the `rewrite_rules` as a Markdown table:
```
| Rule | Reject | Accept |
|------|--------|--------|
| no-hedging-imperative | It might be worth considering... | Use X. |
| specific-over-abstract-speed | significantly faster | <cite a number — e.g. 3.2× faster> |
| ... | ... | ... |
```
Sorted alphabetically by `rule_id`. No truncation — even long entries print in full.
### `--all`
In order:
1. The `--rules` block.
2. The `--examples` table.
3. The `## 10. Counter-examples` prose section, verbatim.
Concatenated with `---` separators between blocks. Designed for "give me the whole executable contract in one screen."
### Output formatting
- Default: plain text to stdout (no JSON wrapper, no headers).
- The user can redirect to a file (`/brand-voice show > rules.txt`) or pipe to clipboard.
- No `-s` flag — `show` is read-only and ephemeral by design. To save, the user redirects.
## Why `show` is its own subcommand
`humanize-en` calls `extract_rules.py` directly under the hood. `show` exists for the user, not the toolchain:
- **Verification** — *"did my voice doc end up looking like I expected?"* — without scrolling through 230 lines of prose.
- **Sharing** — paste the rules into a Slack thread, a code review, an instructions section.
- **Integration** — drop the rules block into another tool's config (`.eslintrc`, custom linter, AI prompt) without writing a parser.
The output is line-oriented and stable. Tooling can grep it.
## Edge cases
- **Target file missing** — error: *"`<path>` not found. Run `/brand-voice extract` first."*
- **Target frontmatter invalid** — error from `extract_rules.py` (exit 1). Surface the error message to the user and suggest `/brand-voice` lint check (or just re-running `voice_lint.py` directly).
- **`--examples` but `rewrite_rules` is empty** — print *"No rewrite_rules in `<target>`."* and exit 0. Empty is a legal state.
- **`--all` but section 10 is missing** — `voice_lint.py` should have caught this earlier. Print the rules and examples blocks; for section 10 print *"(section 10 missing — re-run `/brand-voice update` or fix manually)"*.
- **Chain resolution fails** (`extends-cycle`, `extends-depth-exceeded`, `extends-parent-not-found`) — `extract_rules.py` exits 1 with the error code on stderr. Surface the error and suggest `/brand-voice validate <target>` for the full diagnostic. `--raw` is the workaround when the user wants to inspect the broken child anyway.
- **`--explain` on a target without `voice.extends`** — equivalent to default `--rules`; no provenance to annotate. Print the rules block as usual.
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 |