Zed Brand Writer：一个开发者品牌写作 Agent Skill 的完整设计与工作流

本文以 Zed 仓库中 brand-writer 技能定义 为主体，完整拆解这套"品牌写作技能"（brand-writer）的定位、核心声音准则、八项评分细则与四阶段写作工作流，并结合 crates/agent_skills 与 crates/agent 的源码，说明 Zed 是如何加载、渲染和防护这类 SKILL.md 技能的。读完本文，你既能掌握一套可直接复用的"事实优先"文案写作体系，也能理解 Zed Agent Skill 从发现、目录注册到激活授权的全链路实现。

一、brand-writer 是什么：技能目录与文件构成

brand-writer 是 Zed 官方内置的一个 Agent Skill（智能体技能），其目标是：

以 Zed 的品牌声音写作：面向开发者、以事实开头、立足于手艺本身。听起来像一个为其他开发者构建并解释工具的开发者，写出来像 zed.dev 上的内容——清晰、内省、围绕原则而非说服。

它不是一个孤立文件，而是一个技能目录 docs/.conventions/brand-writer/，包含四个文件，各司其职：

文件	职责
SKILL.md	核心声音原则与完整工作流（本文主体）
rubric.md	8 项评分标准，用于验证文案质量
taboo-phrases.md	需要清除的 AI 味 / 营销味模式清单
voice-examples.md	10 组 before/after 改写范例与事实保留规则

仓库的文档规范 docs/.conventions/CONVENTIONS.md 明确引用了该目录，将其定义为 Zed 文档体系中"声音、语气与写作风格"的权威出处，并把"通过品牌声音评分"列为文档发布前质量清单的一项（"Passes brand voice rubric (see brand-writer/rubric.md)"）。也就是说，这套技能既是对外文案的写作指南，也是 Zed 自身文档的质检标准。

SKILL.md 的 frontmatter 与加载约束

SKILL.md 的开头是 YAML frontmatter：

---
name: brand-writer
description: Write clear, developer-first copy for Zed — leading with facts, grounded in craft.
allowed-tools: Read, Write, Edit, Glob, Grep, AskUserQuestion, WebFetch
user-invocable: true
---

结合 crates/agent_skills/agent_skills.rs 的解析源码，这些字段的实际约束是：

• name：必须匹配 [a-z0-9-]{1,64}——仅小写字母、数字、连字符，最长 64 字节，不能以连字符开头或结尾（见 validate_name）。校验失败会直接拒绝加载该技能，这在 crates/agent_skills/README.md 中被明确称为"永久性设计决策"（strict validation is a permanent design decision）。
• description：非空且不超过 1024 字节（MAX_SKILL_DESCRIPTION_LEN）。description 是模型在系统提示中看到的唯一"目录项"，因此要短、且把关键词前置。
• 文件大小：单个 SKILL.md 上限 100KB（MAX_SKILL_FILE_SIZE），读取前会先检查文件元数据，防止超大文件拖垮应用。
• allowed-tools / user-invocable：这两个是规范中的实验性字段。从源码结构看，Zed 目前只在 frontmatter 中强制支持 name、description 以及扩展字段 disable-model-invocation，未知字段会被静默忽略（标准 YAML 行为），因此 allowed-tools: Read, Write, ... 在此更多是声明性的作者意图表达。

一个值得注意的设计细节：加载阶段只解析 frontmatter，正文（body）被刻意丢弃、不驻留内存；只有当技能真正被激活时，才通过 read_skill_body 按需重读正文。这样 N 个技能的目录只付出"名称 + 描述"的成本，正文成本在使用时才支付。

二、如何调用 brand-writer

SKILL.md 定义了三种调用方式：

/brand-writer                           # 开始一个写作会话
/brand-writer "homepage hero copy"      # 指定要写什么
/brand-writer --review "paste copy"     # 审查现有文案是否符合品牌

在 Zed 中的实际执行机制（源码佐证）：

1. 技能发现：Zed 在两个位置扁平扫描技能——全局 ~/.agents/skills/ 和项目级 <worktree>/.agents/skills/，每个技能的直接子目录下的 SKILL.md 即一个技能（load_skills_from_directory、find_skill_files）。品牌技能随仓库维护在 docs/.conventions/ 下，若要作为可调用技能使用，需将其安装到上述两个目录之一。
2. 斜杠命令：用户输入 /brand-writer 时，技能正文被注入对话，等价于模型调用 skill { name: "brand-writer" } 工具——两条路径共用同一个 render_skill_envelope 渲染器，模型看到的是完全相同的结构。
3. 优先级：同名技能按 ProjectLocal > Global > BuiltIn 覆盖（SkillSource::precedence，并有单元测试 test_skill_source_precedence_is_total_and_ordered 固定这一层级）。
4. 授权：模型自主调用 skill 工具时走标准工具权限流程（默认 Confirm，可选 Allow Once / Always Allow / Reject，且可按技能名细分授权）；而用户手敲斜杠命令不再提示——因为用户已显式发起。
5. 激活信封：模型拿到的正文被包在 <skill_content> 中，包含 name、source（global / project-local）、directory（技能绝对路径）三段元信息。SKILL.md 中"加载参考文件"一步依赖的正是这一点：正文里提到的 rubric.md、taboo-phrases.md、voice-examples.md 都是相对技能目录的路径，模型依据信封中的 <directory> 拼接后用 read_file 读取。从源码结构看，Zed 不会自动预载这些捆绑资源，SKILL.md 本身才是"模型该读什么"的事实来源。

三、核心声音（Core Voice）与核心信息（Core Messages）

声音基调

SKILL.md 对"声音"的总要求是：用赢得信任的写作来表达 Zed 的理念、能力与哲学。从不推销。陈述事实、解释工作原理、让读者自己下结论。以社区成员的身份对社区说话。

具体语气规则（Tone）：

• 流畅、平静、直接（Fluent, calm, direct）。句子语法完整、自然流动；
• 不写破碎的短语，不用节奏化的营销腔；
• 不过度使用 em dash（—），不使用 "it's not X, it's Y"（不是 X，而是 Y）句式；
• 每一行读起来都应像一位资深开发者在对话中会说的话。

五条核心信息

SKILL.md 规定了 Zed 对外叙事必须反复传达的五个事实性支柱：

核心信息	内容
Code as craft（代码即手艺）	从零构建，带着意图制作。每个功能都各司其职，一切都有它的位置。
Made for multiplayer（为多人协作而生）	代码是协作的。但今天，我们的对话发生在代码库之外。在 Zed 中，你的团队与你的 AI 智能体在同一个空间、实时共事。
Performance you can feel（可感知的性能）	Zed 用 Rust 编写，每一帧都有 GPU 加速。你打字或移动光标时，像素立即响应。这种响应速度让你保持在心流中。
Always shipping（持续交付）	Zed 为今天而建，每周改进。每个版本都让这门手艺前进一步。
A true passion project（真正的热情项目）	Zed 是开源的、公开构建的，由一个极度关心质量的社区驱动。来自 Atom 和 Tree-sitter 背后的团队。

注意这些表述与仓库事实严格对应：Rust 代码库（整个 crates/ 目录）、GPU 渲染（crates/gpui_wgpu、crates/gpui_apple 等平台渲染后端）、多人协作（crates/collab、crates/call、crates/livekit_client）、开源双协议（LICENSE-APACHE 与 LICENSE-GPL）——这正是"事实优先"原则在品牌叙事层面的落地：每条核心信息都指向代码库中可验证的实现。

四、写作原则、结构与禁区

六条写作原则

1. 最重要的信息放最前——先给开发者当下需要知道的：变了什么、能做什么、怎么工作。品牌叙事或哲学背景放在其后，视篇幅而定。
2. 深思而非表演——像你正在解释一件你在乎的事，而不是在路演。
3. 解释性的精确——在重要处给出技术细节。"GPU 加速""按键粒度"（keystroke granularity）这类术语展示专业度与尊重。
4. 哲学先行，产品其次——从"开发者如何工作、他们应得什么"这样的观点出发，再描述 Zed 如何支撑这一点。
5. 自然节奏——句子长短变化，让想法呼吸。避免营销口号与强行对仗。
6. 不做情感操纵——永远不用炒作、感叹号或 "we're excited"。不告诉读者他们应该感觉如何。

解释功能或想法时的四步结构

1. 以一个开发者必须知道的最基本事实或变化开头；
2. 解释 Zed 如何应对它；
3. 补充品牌哲学或背景以加深理解；
4. 让读者自己推断收益——绝不夸大。

Avoid 清单与 Litmus Test（试金石）

SKILL.md 给出的避免清单：

• AI / 营销套话（em dash 链、镜像句式、"it's not X, it's Y"）；
• 行业黑话（"revolutionary"、"cutting-edge"、"game-changing"）；
• 企业腔或初创公司腔；
• 碎片化文案与口号；
• 感叹号；
• "We're excited to announce..."（我们激动地宣布……）。

定稿前用四条试金石检验：

• 一位资深开发者会尊重这段文字吗？
• 听起来像 zed.dev 上的内容吗？
• 大声读出来是否清晰自然？
• 它解释得多，还是推销得多？

任何一条不满足，重写。

五、质量验证体系：八项评分细则

rubric.md 定义了 8 项 1–5 分的评分标准，全部达到 4 分及以上才算通过（总分 32/40）：

标准	考察点	5 分表现
Technical Grounding（技术根基）	是否做具体、可验证的技术断言	精确到可核查的规格、架构、可测量结果
Natural Syntax（自然句法）	是否像深思的开发者自然说话	句式多样、节奏自然、朗读顺畅
Quiet Confidence（安静自信）	是否以事实陈述代替炒作与情感操纵	事实自己说话，读者自下结论
Developer Respect（开发者尊重）	是否把读者当同行而非潜在客户	对等对话，默认技术能力
Information Priority（信息优先级）	最重要信息是否在最前	关键事实领先，背景自然跟随
Specificity（具体性）	断言是否具体可测	每个断言都可被验证
Voice Consistency（声音一致性）	语气是否全程统一	从头到尾单一连贯的声音
Earned Claims（挣得的断言）	主张是否有支撑	每个主张都能被演示或验证

决策规则（Decision Rules）：

• 全部 4+：通过，可做少量润色；
• 任一 3 分：重写被标记部分，重新评分；
• 任一 2 分或更低：需要完全重构；
• 多项不达标：换一种方法从头开始。

每条标准都配有正反例锚定评分，例如 Developer Respect 的 5 分范例是 "Tree-sitter provides incremental parsing, so syntax highlighting updates as you type."（Tree-sitter 提供增量解析，所以语法高亮随你的输入更新），反例是 "Don't worry about the technical details — just know it's fast!"（别担心技术细节——只要知道它很快！）。

禁忌短语体系（taboo-phrases.md）

taboo-phrases.md 把"AI 生成感 / 营销味"分解为可扫描的类别：

1. 炒作词（Hype Words）：revolutionary、game-changing、cutting-edge、blazingly fast、seamless、frictionless、leverage、unlock 等 22 个词，每个都标注了失败原因（未挣得的最高级、无上下文即无意义、几乎永远不成立……）；
2. AI 结构模式：em dash 链（"Zed is fast — really fast — and it shows"）、"It's not X, it's Y"、三段式平行排比（"Fast. Focused. Collaborative."）、正文中冒号引导的列举、以反问句开头，每类都给出修正后的正确写法；
3. 空洞热情："We're excited to announce..."、"You'll love..."、"Get ready to..."、"Say goodbye to..." 等 10 个模式及其问题；
4. 模糊收益：如 "enhanced productivity" 要追问"快多少？在什么任务上？"，"optimized performance" 要追问"哪个指标提升了？"；
5. 禁用标点：感叹号永远为零；不用戏剧性省略号；不大写强调；反问句不能做开头；每段最多一个 em dash；
6. 企业委婉语：move the needle、synergy、paradigm shift、utilize（用 use 代替）、empower……
7. 填充短语：直接在无替换的情况下删除，如 "In today's fast-paced world..."、"Let's face it..."。

文末给出两级检测清单：红灯（出现即自动失败）——任何感叹号、"We're excited/thrilled"、"revolutionary"/"game-changing"、一段内 2 次以上 em dash、"It's not X, it's Y"；黄灯（需仔细审查）——炒作词表中任意词、以 And/But 开头的句子、标题中的问句、恰好三项的列表。总规则一句话："If you can't prove it or measure it, rewrite it."（如果你无法证明或度量它，就重写它。）

十组声音转换范例（voice-examples.md）

voice-examples.md 提供 10 组 before/after 校准样本，覆盖：炒作到具体（blazingly fast → "Keystrokes register in under 8ms. Scrolling stays at 120fps"）、营销到技术（"Zed handles it all" → "language servers run in separate processes with automatic crash recovery"）、抽象到具体（"seamless collaborative experience" → "Share your workspace with cmd+shift+c"）、em dash 链到自然句流、热情到自信（"We're thrilled to announce Zed 1.0!" → "Zed 1.0 is available today. This release includes GPU text rendering, multi-buffer editing, and native collaboration."）等。每组都附"转换注记"说明每个词被替换或删除的具体理由。

该文件还定义了事实保留规则：改写时技术规格（"120fps"）、专有名词（"Tree-sitter"）、版本号（"Zed 1.0"）、快捷键（"cmd+shift+c"）、URL、署名与日期、引语都必须原样存活；重构完成后要与原始 [FACT] 标记逐一 diff 核对。文末的转换模式汇总表：

问题	解法
炒作词	用测量值替换
em dash 链	拆成句子
"It's not X, it's Y"	正面陈述它是什么
热情	删掉，加入实质内容
模糊收益	点名具体功能
被埋没的导语	以新闻本身开头
反问句	改为陈述句
抽象断言	加机制或测量值

六、四阶段写作工作流

SKILL.md 的主体是一套可执行的写作流水线。

Phase 1: Understand the Ask（理解需求）

先提澄清问题：

• 这是给什么用的？（主页、发布说明、文档、社交、产品页）
• 受众是谁？（潜在用户、现有用户、一般开发者）
• 要传达的关键信息或功能是什么？
• 有什么具体约束？（字符上限、格式要求）

Phase 2: Gather Context（收集上下文）

1. 加载参考文件（技能目录下）：rubric.md（8 项验证评分标准）、taboo-phrases.md（要清除的模式）、voice-examples.md（转换模式与事实保留规则）；
2. 搜索相关上下文（如需要）：官方站现有文案（语气参照）、来自文档或代码的功能技术细节、相关公告与既往信息。

Phase 3: Draft（两遍草稿系统）

Pass 1：带事实标记的初稿。 写初稿时，把所有事实性断言打上 [FACT] 标签，覆盖五类内容：技术规格、专有名词与产品名、版本号与日期、快捷键与 URL、署名与引语。示例：

Zed is [FACT: written in Rust] with [FACT: GPU-accelerated rendering at 120fps]. Built by [FACT: the team behind Atom and Tree-sitter].

Pass 2：诊断。 按 8 项 rubric 标准给草稿逐项打分，记录问题：

Criterion	Score	Issues
Technical Grounding	/5
Natural Syntax	/5
Quiet Confidence	/5
Developer Respect	/5
Information Priority	/5
Specificity	/5
Voice Consistency	/5
Earned Claims	/5

同时扫描禁忌短语，逐条标注行号。

Pass 3：重构。 任何标准低于 4 分、或发现任何禁忌短语时：识别具体问题 → 重写被标记的段落 → 验证 [FACT] 标记是否幸存 → 对重写部分重新评分。循环直至所有标准 4 分以上。

Phase 4: Validation（验证与交付）

最终输出"成品 + 记分卡"，格式固定：

## Final Copy

[The copy here]

## Scorecard

| Criterion           | Score |
|---------------------|-------|
| Technical Grounding |   5   |
| Natural Syntax      |   4   |
| Quiet Confidence    |   5   |
| Developer Respect   |   5   |
| Information Priority|   4   |
| Specificity         |   5   |
| Voice Consistency   |   4   |
| Earned Claims       |   5   |
| **TOTAL**           | 37/40 |

✅ All criteria 4+
✅ Zero taboo phrases
✅ All facts preserved

## Facts Verified
- [FACT: Rust] ✓
- [FACT: GPU-accelerated] ✓
- [FACT: 120fps] ✓

并按投放场景选择输出形态：

场景	格式
Homepage（主页）	H1 + H2 + 支撑段落
Product page（产品页）	带解释性文案的节标题
Release notes（发布说明）	变了什么、怎么工作、为什么重要
Docs intro（文档引言）	清晰说明这是什么、何时使用
Social（社交）	简洁、无话题标签、附深入了解链接

七、Review 模式：对既有文案做品牌体检

以 --review 调用时，工作流切换为审查已有文案，五步执行：

1. 加载参考文件（rubric、禁忌短语、声音范例）；

2. 评分：对提供的文案按全部 8 项标准打分；

3. 扫描禁忌短语，逐条附行号，例如：

   Line 2: "revolutionary" (hype word)
   Line 5: "—" used 3 times (em dash overuse)
   Line 7: "We're excited" (empty enthusiasm)
   

4. 呈现诊断，例如：

   ## Review: [Copy Title]
   
   | Criterion           | Score | Issues |
   |---------------------|-------|--------|
   | Technical Grounding |   3   | Vague claims about "performance" |
   | Natural Syntax      |   2   | Triple em dash chain in P2 |
   | ...                 |       |        |
   
   ### Taboo Phrases Found
   - Line 2: "revolutionary"
   - Line 5: "seamless experience"
   
   ### Verdict
   ❌ Does not pass (3 criteria below threshold)
   

5. 若任何标准低于 4 分，提供重写：应用 voice-examples.md 中的转换模式，保留原文所有事实，并附上新版本与新分数。

八、文档自带的示例：Good / Bad / Fixed

SKILL.md 末尾给出三组对照，是整套原则的最小完整演示：

Good：

Zed is written in Rust with GPU acceleration for every frame. When you type or move the cursor, pixels respond instantly. That responsiveness keeps you in flow.

Bad：

We're excited to announce our revolutionary new editor that will change the way you code forever! Say goodbye to slow, clunky IDEs — Zed is here to transform your workflow.

Fixed：

Zed is a new kind of editor, built from scratch for speed. It's written in Rust with a GPU-accelerated UI, so every keystroke feels immediate. We designed it for developers who notice when their tools get in the way.

Bad 版本集齐了所有自动失败项：感叹号、"We're excited to announce"、"revolutionary"、"Say goodbye to" 陈词滥调开头、em dash；Fixed 版本则每条断言都对应代码库中的事实，且没有任何情感指令——这正是 Litmus Test 四条标准的直观体现。

九、源码视角：Zed 如何加载、注册与保护这类技能

brand-writer 的 SKILL.md 只是"被加载者"，而 crates/agent_skills/README.md 系统阐述了 Zed 侧的实现决策，理解它们能解释上文工作流的每个环节为何如此设计。

目录（catalog）与渐进披露。 模型在系统提示中只看到每个技能的 name + description + SKILL.md 绝对路径，包裹在 <available_skills> XML 结构中（渲染模板见 crates/agent/src/templates/system_prompt.hbs，类型见 crates/prompt_store/src/prompts.rs）。全部插值都经过 XML 转义——这是对恶意技能作者的防御：一个把 </available_skills> 写进 description 的文件无法逃逸标签去注入系统提示。全目录 name + description 总量有 50KB 硬预算（MAX_SKILL_DESCRIPTIONS_SIZE），超出的技能按迭代顺序被丢弃并产生 UI 可见的加载警告。

Prompt cache 经济学。 技能目录是系统提示的一部分，Anthropic 兼容的 prompt caching 按字节相同前缀匹配，因此：只改 SKILL.md 正文时，maintain_project_context（crates/agent/src/agent.rs）会比较新旧 ProjectContext，判定目录未变即不刷新系统提示——技能作者反复迭代正文对 API 成本是"免费"的；而改 name/description、移动文件、增删技能都会使缓存失效。这与 brand-writer 要求"短而关键词前置的 description"形成呼应。

安全闸门。 与 brand-writer 这类技能相关的安全设计包括：

• 项目级技能要求工作区信任：<worktree>/.agents/skills/ 只在用户标记为 trusted 的 worktree 中加载，防止恶意仓库借技能描述在系统提示里植入提示注入指令；信任授予后无需重启会话即可生效；
• 技能文件是敏感路径：Agent 的编辑工具写入 SKILL.md 及其捆绑资源需要显式用户授权（敏感路径分类在 crates/agent/src/tools/tool_permissions.rs），威胁模型是"通过技能自我修改持久化提示注入"；读取则不拦截；
• disable-model-invocation: true 会把技能从模型目录中完全隐藏（模型连"not found"错误信息里都看不到它），但用户仍可通过斜杠命令调用——这正是 brand-writer 这类技能与 /deploy 类工作流技能共用的能力开关；
• 全局技能快速通道：read_file/list_directory 对规范化后位于 ~/.agents/skills/ 下的路径放行，使模型能读取 rubric.md、taboo-phrases.md 等捆绑资源，同时 .. 与符号链接无法逃逸技能树。

热加载与继承。 运行中增删改 SKILL.md 立即生效（全局目录有 watcher，项目级走 worktree 变更事件），技能作者无需重启会话即可看到模型目录更新；子智能体（task 工具派生）继承父代理的完整技能列表与目录。

十、把 brand-writer 用起来

结合上述机制，实际使用路径是：

1. 查看：技能定义与三个参考文件在 docs/.conventions/brand-writer/ 下，可直接阅读全文；
2. 安装为可调用技能：将该目录放入全局技能目录 ~/.agents/skills/brand-writer/，或放入项目根目录 <worktree>/.agents/skills/brand-writer/（需先信任该工作区），Zed 会自动发现并热加载；
3. 调用：在 Agent 面板中输入 /brand-writer "release notes for vX.Y" 开始写作会话，或 /brand-writer --review "待审文案" 触发审查模式；
4. 验证：按 rubric 的 32/40 通过线与 taboo-phrases 的自动失败清单自检，任何一项不达标即回到 Pass 3 重构循环。

这套技能的价值在于把"品牌声音"从不可言说的品味问题，工程化为一组可加载（SKILL.md 格式）、可评分（8 项 rubric）、可检测（禁忌短语清单）、可回归（[FACT] 标记与 diff 验证）的确定性流程。对任何需要维护统一对外声音的团队，它提供了一个可直接参照的 Agent Skill 编写范式：主体规则写进 SKILL.md 正文，评分标准与反例清单作为同目录捆绑资源按需加载，frontmatter 只保留一句关键词前置的 description。