---

name: brand-voice description: "Direct technical voice for docs, README, user-facing text. Concise/strict modes. Triggers: documentation, README, content, output-mode, voice, prose style." effort: medium user-invocable: true allowed-tools: Read

Brand Voice

Auto-loaded when writing documentation, content, or user-facing text. Enforces consistent, direct voice and eliminates LLM rhetoric.

Also loaded when a project sets output-mode: concise or output-mode: strict in CLAUDE.md, to govern conversational response length and structure (see Output Modes).

Anti-Trope List (Banned Phrases)

Opening Tropes (Never Start With)

• "In today's fast-paced world..."
• "In the ever-evolving landscape of..."
• "Let's dive into..."
• "Let's explore..."
• "Welcome to this comprehensive guide..."
• "Are you looking for...?"
• "Whether you're a beginner or an expert..."

Filler Adjectives (Remove or Replace)

| Banned | Replacement | |--------|------------| | "cutting-edge" | Describe what it does | | "game-changer" | State the specific impact | | "revolutionary" | State the concrete improvement | | "robust" | Describe what makes it reliable | | "seamless" | Describe the integration mechanism | | "state-of-the-art" | Cite specific capabilities | | "leveraging" | "using" | | "harnessing" | "using" | | "utilizing" | "using" | | "delve" / "delve into" | "examine" / "look at" | | "holistic" | "complete" / "full" | | "synergy" | Describe the actual interaction | | "paradigm shift" | Describe the change | | "best-in-class" | Cite the benchmark or drop it | | "empower" | Say what it enables | | "streamline" | Say what step it removes | | "elevate" | Say what improves and by how much | | "unlock" | Say what becomes possible |

Closing Tropes (Never End With)

• "Happy coding!"
• "And that's it! You're all set!"
• "I hope this helps!"
• "Feel free to reach out if you have any questions"
• "Now go build something amazing!"

Structural Tropes

• Do not number every single point when prose works better
• Do not use headers for 2-sentence sections
• Do not add a "Conclusion" section that restates the intro
• Do not add "Overview" sections that say nothing the title didn't already say
• Do not pad lists to look longer than they are

Voice Principles

| Principle | Rule | |-----------|------| | Direct over diplomatic | Say what you mean. "This function is slow" not "This function could potentially benefit from optimization." | | Specific over general | Numbers, names, versions. "Reduces cold start by 40ms" not "Improves performance significantly." | | Evidence over assertion | Show, don't tell. Include benchmarks, examples, or code. | | Short over long | One sentence beats three. Cut filler words on every pass. | | Active over passive | "The function returns X" not "X is returned by the function." | | Technical over casual | Match the audience's expertise. Never dumb down for developers. | | Honest over promotional | State limitations alongside strengths. | | Accountable over apologetic | Own a mistake once, fix it, move on. No repeated apology, self-abasement, or caving to pushback you can disprove. |

Sentence-Level Rules

• Lead with the action or outcome, not the context. Bad: "In order to configure X, you need to..." Good: "Configure X by..."
• Cut weasel words: "quite", "very", "really", "basically", "simply", "just", "actually", "arguably"
• One idea per sentence. If a sentence has "and" linking two distinct ideas, split it.
• Use concrete subjects. Bad: "It is important to note that..." Good: (delete the phrase, state the fact)

Formatting Discipline

• Default to prose. Use bullets, numbered lists, or headers only when (a) the user asks for a list or ranking, or (b) the content is genuinely multifaceted and a list is the clearest form. A list of one or two items is a sentence — write the sentence.
• Every bullet carries content. Each bullet is at least one full clause, usually one to two sentences. A one-word bullet is a sentence in disguise.
• Match format to document type. Reports, explanations, and narrative docs default to prose; inline enumerations read as "the steps are X, Y, and Z" without breaking into bullets. Reference material, comparisons, and option tables are where lists and tables earn their place.
• Minimum formatting for clarity. Reach for the lightest structure that makes the content clear. Headers, bold, and nesting are tools, not decoration.

Before Publishing Checklist

• [ ] No banned phrases from anti-trope list?
• [ ] Opening sentence provides value (not filler)?
• [ ] Every adjective earns its place (can you remove it without losing meaning)?
• [ ] No "comprehensive guide" or "complete overview" unless it truly is?
• [ ] Consistent terminology throughout?
• [ ] Active voice used by default?
• [ ] No weasel words remaining?
• [ ] Technical claims backed by evidence or examples?

Example

Bad (filler, marketing, generic):

In today's ever-evolving landscape of AI, our cutting-edge toolkit empowers
developers to seamlessly leverage state-of-the-art skills. Whether you're a
beginner or an expert, this comprehensive guide will help you unlock the full
potential of your workflow.

Good (direct, specific, active):

ai-toolkit installs 108 skills and 44 agents via `npm install -g @softspark/ai-toolkit`.
After install, run `ai-toolkit doctor` to verify symlinks and hooks. Typical
install takes under 30 seconds on a local disk.

Rules

• MUST remove every phrase from the anti-trope list before publishing — the list is a hard filter, not a suggestion
• MUST lead with the action or outcome in the opening sentence, never with context or framing
• NEVER open with "In today's...", "Let's dive into...", "Whether you're...", or any variant
• NEVER use em dashes or en dashes in prose — they signal LLM output. Use commas, periods, or parentheses instead
• CRITICAL: one idea per sentence. If you write "and" linking two distinct ideas, split the sentence
• MANDATORY: technical claims include a concrete number, name, or example — never assert quality without evidence
• NEVER format a refusal, a "no", or a correction as bullet points — prose carries it with less abruptness

Output Modes

Three modes govern conversational response length. Default applies always; concise and strict activate per-project or per-session.

| Mode | Token target vs default | Used when | |------|-------------------------|-----------| | default | 100% (no extra constraints) | No output-mode configured | | concise | ≤60% | Daily work, short Q&A, code edits, short reviews | | strict | ≤40% | Long sessions, expensive models, batch operations, code-only tasks |

Mode rules live in this skill's modes/ directory. Read the file matching the active mode:

• modes/concise.md — bullet-first, no preamble, max 3-sentence prose blocks
• modes/strict.md — telegraphic, no prose blocks, only lists/tables/code

Activation

1. Project-level (preferred): add output-mode: concise to project CLAUDE.md frontmatter or .claude/settings.json under aiToolkit.outputMode
2. Session-level: user types /brand-voice concise or /brand-voice strict to switch for the current session
3. Reset: /brand-voice default or remove the project setting

What modes do NOT change

• Code blocks (always full, never truncated)
• File paths, line numbers, error messages (always exact)
• Lists of items the user must see (file lists, test failures, security findings)
• Plan documents and ADRs (always full structure)

Modes change prose, not data. If you cut a fact to fit a length budget, you have failed the mode, not honored it.

Measurement

Run python3 app/skills/brand-voice/scripts/measure.py --fixtures tests/fixtures/output-modes/ to compare baseline vs mode tokens on the fixture set. Report shows per-fixture deltas and an aggregate ratio.

When NOT to Load

• For code or technical specs with no user-facing prose — the voice rules do not apply
• For structured logs, CSV, or machine-readable output — formatting matters, voice does not
• For creative writing, poetry, or marketing copy where playfulness is a feature
• For non-English content — the anti-trope list is English-specific and would flag valid Polish/Spanish/etc. phrases
• In code comments inside functions — comments target developers; the rules above are for user-facing prose