/brand-voice

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](#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 parenthe