From c7537bdf463a998e7ec636adff33b198891e69ed Mon Sep 17 00:00:00 2001 From: Bechor Simhaev <48318320+bechor25@users.noreply.github.com> Date: Tue, 11 Aug 2026 16:11:36 +0000 Subject: [PATCH] docs: Rename brand-voice to brand-writer skill (#62384) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## What `docs/.conventions/brand-voice/SKILL.md` declares: ```yaml name: brand-writer ``` while sitting in a directory called `brand-voice`. The Agent Skills specification requires the two to be identical: > The required `name` field: … **Must match the parent directory name** > — So this skill fails `skills-ref validate` today. ## Which side is wrong The directory — and this repository settles it three separate ways, with no outside context needed. **1. The sibling copy already uses the matching name.** `.factory/skills/brand-writer/` holds the same four files (`SKILL.md`, `rubric.md`, `taboo-phrases.md`, `voice-examples.md`) under `brand-writer`. **2. `crates/agent_skills/README.md` documents the skill system using this exact skill, and the name it documents is `brand-writer`:** ``` line 107: brand-writer line 149: the model … calls `skill { name: "brand-writer" }` line 151: when the user types `/brand-writer` line 158: ``` That name is load-bearing — it is what the skill tool invokes and what the slash command types. The directory name is referenced twice, both inside `docs/.conventions/CONVENTIONS.md`. **3. Six of the repository's seven skills already match their directory:** | skill | matches? | | --- | --- | | `.agents/skills/gpui-test` | ✅ | | `.agents/skills/lint-creator` | ✅ | | `.agents/skills/zed-cherry-pick` | ✅ | | `.factory/skills/brand-writer` | ✅ | | `.factory/skills/humanizer` | ✅ | | `crates/agent_skills/builtin/create-skill` | ✅ | | **`docs/.conventions/brand-voice`** | ❌ the only one | ## The change The frontmatter is untouched. Only the directory moves, plus the two references to it: - `docs/.conventions/brand-voice/` → `docs/.conventions/brand-writer/` (4 files, pure rename) - `CONVENTIONS.md:5` — `[brand-voice/](./brand-voice/)` → `[brand-writer/](./brand-writer/)` - `CONVENTIONS.md:368` — `` `brand-voice/rubric.md` `` → `` `brand-writer/rubric.md` `` `git grep brand-voice` returns nothing afterwards. If you would rather keep the directory name and rename the field to `brand-voice`, that is a one-line change instead and I am happy to switch it — but it would give the two copies of one skill two different names, and it would diverge from the name `crates/agent_skills/README.md` documents. ## One thing I noticed but did not touch The two copies have drifted. `.factory/skills/brand-writer/SKILL.md` is 279 lines and includes a *"Phase 4: Humanizer Pass"* section; `docs/.conventions/`'s copy is 265 lines, lacks that section, and renumbers Validation from Phase 5 to Phase 4. That is a separate question about which copy is canonical, so it is left alone here. --- Found with [AgentCompass](https://github.com/YoavLax/agent-compass), an offline static analyzer for AI-agent repo readiness. Verified by hand against the spec before opening. Release Notes: - N/A --- docs/.conventions/CONVENTIONS.md | 4 ++-- docs/.conventions/{brand-voice => brand-writer}/SKILL.md | 0 docs/.conventions/{brand-voice => brand-writer}/rubric.md | 0 .../{brand-voice => brand-writer}/taboo-phrases.md | 0 .../{brand-voice => brand-writer}/voice-examples.md | 0 5 files changed, 2 insertions(+), 2 deletions(-) rename docs/.conventions/{brand-voice => brand-writer}/SKILL.md (100%) rename docs/.conventions/{brand-voice => brand-writer}/rubric.md (100%) rename docs/.conventions/{brand-voice => brand-writer}/taboo-phrases.md (100%) rename docs/.conventions/{brand-voice => brand-writer}/voice-examples.md (100%) diff --git a/docs/.conventions/CONVENTIONS.md b/docs/.conventions/CONVENTIONS.md index d9d822e347b..aeba1de2e40 100644 --- a/docs/.conventions/CONVENTIONS.md +++ b/docs/.conventions/CONVENTIONS.md @@ -2,7 +2,7 @@ This document covers structural conventions for Zed documentation: what to document, how to organize it, and when to create new pages. -For voice, tone, and writing style, see the [brand-voice/](./brand-voice/) directory, which contains: +For voice, tone, and writing style, see the [brand-writer/](./brand-writer/) directory, which contains: - `SKILL.md` — Core voice principles and workflow - `rubric.md` — 8-point scoring criteria for quality @@ -365,7 +365,7 @@ Before finalizing documentation: - [ ] Non-reference pages include at least 3 useful internal docs links - [ ] Main feature pages include a relevant `zed.dev` marketing link - [ ] Passes Prettier formatting check -- [ ] Passes brand voice rubric (see `brand-voice/rubric.md`) +- [ ] Passes brand voice rubric (see `brand-writer/rubric.md`) --- diff --git a/docs/.conventions/brand-voice/SKILL.md b/docs/.conventions/brand-writer/SKILL.md similarity index 100% rename from docs/.conventions/brand-voice/SKILL.md rename to docs/.conventions/brand-writer/SKILL.md diff --git a/docs/.conventions/brand-voice/rubric.md b/docs/.conventions/brand-writer/rubric.md similarity index 100% rename from docs/.conventions/brand-voice/rubric.md rename to docs/.conventions/brand-writer/rubric.md diff --git a/docs/.conventions/brand-voice/taboo-phrases.md b/docs/.conventions/brand-writer/taboo-phrases.md similarity index 100% rename from docs/.conventions/brand-voice/taboo-phrases.md rename to docs/.conventions/brand-writer/taboo-phrases.md diff --git a/docs/.conventions/brand-voice/voice-examples.md b/docs/.conventions/brand-writer/voice-examples.md similarity index 100% rename from docs/.conventions/brand-voice/voice-examples.md rename to docs/.conventions/brand-writer/voice-examples.md