# Docs Voice > Write project documentation in a direct, human voice. Strip AI tells, ban em-dashes, and keep emojis to a small functional set. Applies to all docs of record (README, docs/, .github/agents/, .squad/templates/, .squad/decisions.md, .squad/skills/*/SKILL.md, agent histories, copilot-instructions.md). Does not apply to historical artifacts under .squad/orchestration-log/ and .squad/log/. Use when this capability is needed. - Skill: `tomevault-io/docs-voice-2` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/docs-voice-2` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/docs-voice-2/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/docs-voice-2 --- ## Context This skill governs how the squad writes prose. It applies whenever an agent edits or creates a document of record in this repo. It does not govern code comments inside `.py`, `.yml`, or `.sh` files (that is a separate code-style concern), and it does not govern README badge conventions. Apply this skill to: - `README.md` - everything under `docs/` - everything under `.github/agents/` and `.github/copilot-instructions.md` - `.squad/templates/` - `.squad/decisions.md` and files under `.squad/decisions/inbox/` - `.squad/skills/*/SKILL.md` - per-agent `history.md`, `charter.md`, `skills.md`, and identity files - PR descriptions and issue bodies authored by squad members Do not apply this skill to: - `.squad/orchestration-log/` and `.squad/log/`. Those are historical artifacts, leave them alone. - inline code comments. Use the language's normal style there. - third-party content quoted verbatim with attribution. ## Patterns ### 1. Open with the point State the position or the fact in the first sentence. Skip warm-up phrases like "In today's world", "As we all know", or "I'm excited to share". Give the conclusion before the reasoning. ### 2. Use concrete nouns Name the file, the function, the rule ID, the YAML key, the workflow. Abstract sentences read as filler. If a paragraph could be pasted into any other repo without editing, rewrite it. ### 3. Imperative or third-person, not first-person personal Docs are written, not spoken. Prefer "the loader rejects unknown keys" over "I think the loader should reject unknown keys". For instructions, use the imperative: "run `pytest` before opening a PR", not "you might want to consider running `pytest`". ### 4. Short paragraphs, varied length Two or three sentences per paragraph is the default. Mix in a one-line statement when a point lands harder alone. Do not stack four paragraphs of the same shape. ### 5. Active voice, concrete verbs Use `update`, `replace`, `drop`, `add`, `reject`, `enforce`. Avoid `leverage`, `enable`, `facilitate`, `utilise`, `drive`. ### 6. Closers state, do not invite Docs do not ask "what do you think?" End on a fact, a rule, or a pointer to the next file. Leave open invitations for issue threads and PR conversations. ## Operational rules (binding for this repo) These four rules encode the scope decisions Martin made on issue #53. Yuki applies them mechanically in the next sweep. ### Rule A. Emoji policy: pragmatic, keep role badges Permitted emojis across all docs of record: - `โœ…` and `โŒ` for binary status. - The squad role badges, because they are functional UI in routing tables and team rosters: `๐Ÿ—๏ธ` `โš›๏ธ` `๐Ÿ”ง` `๐Ÿงช` `๐Ÿ“‹` `๐Ÿ”„`. - The capability traffic-light glyphs where they are load-bearing labels in routing (`๐ŸŸข` `๐ŸŸก` `๐Ÿ”ด` inside `.squad/team.md`, `.squad/routing.md`, and the capability columns they feed). Outside those routing surfaces, strip them. Strip every other emoji on sight. Common offenders to remove: `` `` `` `` `` `` `` `` `` `` `` `` `` `` `` `` `` ``. ### Rule B. Em-dash policy: full sweep, except historical logs Remove every em-dash and en-dash from docs of record. Replace with a comma, a period, or the word "and", picking whichever fits the sentence: - list-style aside, use a comma. Example: "the loader rejects unknown keys, including typos". - two independent clauses, use a period. Example: "the loader rejects unknown keys. Typos fail loudly." - joining two parallel ideas, use "and". Example: "the loader validates keys and surfaces typos". Skip the sweep for files under `.squad/orchestration-log/` and `.squad/log/`. Those are dated artifacts, rewriting them rewrites history. Hyphens (`-`) inside compound words (`read-only`, `single-duck`, `frontier-model`) are unaffected. ### Rule C. AI-language blacklist Reject these words and phrases in any doc of record. The list is not exhaustive, the test is "does it sound like a model wrote it": - abstract verbs: `leverage`, `unlock`, `unleash`, `harness`, `empower`, `elevate`, `streamline`, `embark`, `navigate` (when used about a system, not a UI), `delve`, `dive into`, `deep dive`. - vague qualifiers: `comprehensive`, `robust`, `cutting-edge`, `seamless`, `holistic`, `paradigm`, `lightweight` (when used as a vague compliment), `game-changer`, `next-generation`. - transition tells: `furthermore`, `moreover`, `additionally`, `on the other hand`, `in conclusion`, `to sum up`, `in fact`, `it is worth noting`, `it should be noted`, `aforementioned`, `hereinafter`, `notwithstanding`, `nonetheless`. - framing tells: "In today's world", "In today's landscape", "Let's explore", "Let's dive in", three-point bulleted intros, hedging openers ("It is important to note that"). - career or product romance: `journey` (for a process or a roadmap), "at the end of the day", "it goes without saying". - AI-tell sign-offs: "feel free to connect", "if you found this helpful", "drop a comment". Replace with the concrete word. `comprehensive testing` becomes `tests cover X, Y, Z`. `leverage Pydantic` becomes `use Pydantic`. `robust validation` becomes `validation that rejects unknown keys and fails on type drift`. If the abstract word is doing real work, the sentence is hiding what it actually means. ### Rule D. Voice profile location: skill only This SKILL is the only canonical location for the docs voice. Do not duplicate it under `docs/voice/`, `docs/style.md`, or anywhere else. Agents read this file at session start through the normal skill-loading path. If a future agent wants to extend the voice rules, edit this file in a tracked PR, do not fork it. ## Examples ### Before and after, abstract verb Before: > The loader leverages Pydantic to provide robust validation across the catalogue. After: > The loader uses Pydantic v2 with `extra="forbid"`. Unknown keys fail at parse time. ### Before and after, em-dash sweep Before (with an em-dash joining two clauses): > The duck pass is mandatory for code PRs, post draft PRs are exempt. After (period and a fresh sentence): > The duck pass is mandatory for code PRs. Post draft PRs are exempt. ### Before and after, transition tell Before: > Furthermore, the validator hard-fails at publish time. Moreover, soft warnings surface during drafting. After: > The validator hard-fails at publish time. Soft warnings surface during drafting. ### Before and after, hedging opener Before: > It is important to note that the cloud agent cannot self-merge. After: > The cloud agent cannot self-merge. ### Before and after, emoji strip Before: > New rule: never push secrets to the repo. Use OIDC instead. After: > New rule: never push secrets to the repo. Use OIDC instead. ### Before and after, role-badge keep Keep: > | Member | Role | > |---|---| > | Maya | ๐Ÿ“‹ Lead | > | Diego | ๐Ÿ—๏ธ Architect | The badges are functional UI in the team roster, so they stay. ## Anti-patterns - rewriting historical logs under `.squad/orchestration-log/` or `.squad/log/`. Those files capture what happened on a given date. Editing them for voice destroys the record. - stripping `๐ŸŸข` `๐ŸŸก` `๐Ÿ”ด` from `.squad/routing.md` capability columns. Those glyphs are load-bearing labels, removing them breaks the routing table contract. - replacing every em-dash with a comma reflexively. Pick the punctuation that fits the sentence. Two independent clauses want a period, not a comma splice. - adding a CTA to a docs page. Docs are not posts. No "what do you think?" closers. - swapping one banned abstract verb for another (`leverage` to `utilise`, `robust` to `comprehensive`). The fix is a concrete noun or verb, not a synonym from the same family. - writing a "voice section" in another file. This SKILL is the source. Other docs reference it by path, they do not restate it. - treating this skill as a hard lint. The blacklist is a guide for human and agent judgement. A word on the list can appear in a quoted source, an issue title from outside the squad, or a code identifier. Sweep prose, not quotes or code. --- > Source: [martinopedal/FinOps-assessment](https://github.com/martinopedal/FinOps-assessment) โ€” distributed by [TomeVault](https://tomevault.io).