# docs: Rename brand-voice to brand-writer skill \(\#62384\) · gitcafe/zed

[View on GitCafe](https://git.cafe/gitcafe/zed/commit/c7537bdf463a998e7ec636adff33b198891e69ed)

Repository: [gitcafe/zed](https://git.cafe/gitcafe/zed)

Visibility: public

Requested revision: c7537bdf463a998e7ec636adff33b198891e69ed

Requested commit: c7537bdf463a998e7ec636adff33b198891e69ed

Commit: c7537bdf463a998e7ec636adff33b198891e69ed

Tree: 03af85c00f2bcd68331460e3ec8637760866ee7e

Author: Bechor Simhaev

Committer: GitHub

## Message

````
docs: Rename brand-voice to brand-writer skill (#62384)

## 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**
> — <https://agentskills.io/specification#name-field>

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:  <name>brand-writer</name>
line 149:  the model … calls `skill { name: "brand-writer" }`
line 151:  when the user types `/brand-writer`
line 158:  <skill_content name="brand-writer">
```

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
````

## Parents

- [c0979ee084f218c35342148d9272800f123efe9c](https://git.cafe/gitcafe/zed/commit/c0979ee084f218c35342148d9272800f123efe9c?format=markdown)

[Source at this commit](https://git.cafe/gitcafe/zed/tree/c7537bdf463a998e7ec636adff33b198891e69ed?format=markdown)