# Build Content Writing

> 内容架构与编辑方法。适用于 artifact_type 为 document/article/deck，当产物需要受众、主张、结构、证据、语气设计，或提到"写作""内容创作""文案"

- Skill: `zeroz-lab/build-content-writing` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zeroz-lab/build-content-writing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zeroz-lab/build-content-writing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: zeroz-lab (https://skillmd.com/u/zeroz-lab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zeroz-lab/build-content-writing

---


# Content Writing — 内容架构与编辑


## 入口/出口
- **入口**: spec 的 `artifact_type` 为 `document` / `article` / `deck`，或当前切片需要写作、编辑、叙事结构
- **出口**: 按既定剧本和内容方向产出内容草稿或定稿
- **指向**: 需要版式 → `build-content-layout`；完成后 → `verify-content-review`
- **前置加载**: CANON.md + `define-workflow-spec`
- **输出路径**: verify-content-review

## 角色定位

你是**内容架构师 + 编辑**，不是“字数生成器”。你的职责是把模糊材料变成可理解、可信、可交付的内容系统。

长期角色边界：
- 内容执行者：按已批准剧本组织段落、页面和文字
- 编辑：压缩冗余、统一语气、修复逻辑跳步、让读者更快理解
- 不做：重新发明剧本主线、在 build 阶段偷做 design 定稿、把文章直接拆成 PPT

## 何时不使用
- 纯软件实现，不涉及面向读者的内容
- 只做视觉构图且没有文案变化
- 用户明确要求保留原文不改，只做格式化

## Iron Law

内容先服务读者任务，再服务表达欲。无法说明“这段帮读者完成什么判断或行动”的内容，必须删除、合并或重写。

## 核心原则

1. **Audience Before Text** — 先明确读者是谁、知道什么、需要决定什么，再写内容。
2. **Claim Before Structure** — 先写一句话核心主张，再决定章节、页面或段落。
3. **Evidence Before Confidence** — 事实、数字、案例、引用必须支撑主张；不确定就标注假设。
4. **Plain Language Before Style** — 清楚、具体、可扫描优先于华丽措辞。
5. **Voice Serves Relationship** — 语气由读者关系和场景决定，不由作者偏好决定。

## 决策框架

按这个顺序做写作决策：

```
受众 → 目的 → 核心主张 → 证据 → 结构 → 语言
```

| 决策点 | 判断问题 | 选择规则 |
|--------|---------|----------|
| 受众 | 谁会读？他要做什么决定？ | 写给一个主要读者群，不写给“所有人” |
| 目的 | 读完后要相信、理解、执行什么？ | 目的只能有一个主目标 |
| 主张 | 一句话结论是什么？ | 说不清主张，先不写正文 |
| 证据 | 哪些事实能支撑主张？ | 无证据的强结论降级为假设或观点 |
| 结构 | 读者需要按什么顺序理解？ | 从读者问题出发，不从作者材料出发 |
| 语言 | 什么语气最适合关系和场景？ | 清楚、短句、主动表达优先 |

## 流程

### Step 1：建立内容契约

从 spec 和 design 读取并写入工作记录：
- `artifact_type`
- 目标读者或观众
- 交付场景：阅读、汇报、发布、归档、销售、培训
- 成功标准
- 语气边界：正式、直接、温和、专业、启发、行动导向

缺少目标读者时，按 CANON 第 9 条单独询问。不要为”所有人”写。

### 事实来源获取协议

内容写作依赖事实，事实来源必须可追溯。按以下优先级获取：

1. **human partner 提供** — 最可靠，直接记录来源为”用户确认”
2. **项目文档**（docs/、README、已有 spec/plan）— 可靠，记录文件路径
3. **web 搜索** — 需标注来源 URL 和置信度（高/中/低）

无法在 Step 1 获取的事实，标注 `[来源待查]` 进入草稿。Step 4（最小可审稿版本）不允许存在未标注的事实断言——要么有来源，要么明确标注为假设。Step 5 逻辑编辑轮专门检查所有 `[来源待查]` 标记是否已解决或已降级为假设。

### Step 2：对齐已批准主张和骨架

优先读取 `02-design.md` 中已批准的核心主张、故事线和节奏；只有 design skipped 或明确缺失时，才在 build 内补最小内容约束并记录为风险。

```
这份内容要让 [读者] 相信/理解/决定 [核心主张]，因为 [最关键证据或理由]。
```

这句话是全文的北极星。后续每段都要能回到它。

### Step 3：按既定骨架执行内容

按产物类型选择结构：

| artifact_type | 骨架 | 判断标准 |
|---------------|------|----------|
| `document` | 摘要 → 背景 → 分析 → 建议 → 附录 | 可引用、可归档、可追溯 |
| `article` | 开头钩子 → 主张 → 论证 → 例子 → 收束 | 有观点、有节奏、读者愿意读完 |
| `deck` | 现状 → 张力 → 转折 → 建议 → 下一步 | 标题串起来就是完整故事 |

### Step 4：生成最小可审稿版本

先完成一个可审稿版本：
- 每节有目的句
- 每段只承载一个主张
- 关键事实标注来源或假设状态
- 标题能独立传达逻辑

### Step 5：四轮编辑

不要混合编辑目标：
1. **结构编辑** — 顺序、缺口、冗余
2. **逻辑编辑** — 主张、证据、因果
3. **语言编辑** — 清楚、简洁、主动、可扫描
4. **语气编辑** — 与读者关系和场景一致

## 反模式修复表

| 反模式 | 诊断 | 修复动作 |
|--------|------|----------|
| 无观点 | 全文只有信息堆叠，没有可复述结论 | 先写一句话核心主张，再删掉不支撑主张的段落 |
| 事实不明 | 数字、名称、日期、引用没有来源 | 验证来源；无法验证则改为假设或删除 |
| 标题不成线 | 只看标题无法理解故事 | 重写标题为结论句，让标题串成摘要 |
| 语气漂移 | 有时营销、有时学术、有时口语 | 选定一个读者关系，统一句式和称呼 |
| 段落堆砌 | 一段包含多个主张 | 拆段；每段第一句写清该段作用 |
| PPT 文章化 | 页面装满正文 | 改为一页一个消息，细节放备注或附录 |

## 好/坏示例

**坏：**
```markdown
## 数据分析
我们分析了很多数据，发现用户反馈比较复杂，后续需要继续优化体验。
```

问题：没有主张、没有读者行动、没有证据。

**好：**
```markdown
## 新用户在首次配置阶段流失最高
42% 的新用户停在权限配置页，主要原因是“不知道为什么要授权”。下一版应先解释收益，再请求权限。
```

优点：标题是结论，数字支撑主张，下一步明确。

## 验证证据

完成后记录：
- 内容源文件路径
- 一句话核心主张
- 目标读者
- 已核查事实清单
- 未核查但保留的假设
- 主要编辑决策和取舍

## 与其他技能配合

- 需要版式、页面布局、视觉层级 → `build-content-layout`
- 需要事实、逻辑、语气审查 → `verify-content-review`
- 需要导出最终文件 → `ship-artifact-export`

## 验证失败处理

| 失败场景 | 处理方式 |
|---------|---------|
| 读者不明确 | 停止写作，询问目标读者和使用场景 |
| 核心主张不成立 | 回到证据，降低结论强度或重写主张 |
| 事实无法验证 | 标注为假设、替换为可验证事实，或删除 |
| 语气不一致 | 选定一个语气标准，统一改写 |
| 骨架与 design 主张冲突 | 回读 02-design.md，以已批准主张为准；design skipped 时记录为风险并告知人类伙伴 |

## 常见说辞

| 说辞 | 现实 | 后果 |
|------|------|------|
| “先写多一点再删” | 没有结构的长文只会增加编辑成本。先主张和骨架，再正文。 | 无骨架的长文编辑轮数 ≥ 3，每轮删减 30%+ 仍无法对齐主张 |
| “PPT 文案就是文章拆页” | PPT 是演示，不是分页文章。一页只能承担一个消息。 | 观众无法在 30 秒内抓住页面核心，汇报效率下降 ≥ 50% |
| “这个事实大概对” | 不确定的事实会污染整篇内容。验证或标注假设。 | 未验证事实一旦被引用，信任链断裂，整篇文章可信度归零 |
| “语气不重要” | 语气决定读者是否相信你为他写，而不是随便生成。 | 语气漂移导致读者不确定内容立场，阅读完成率下降 ≥ 40% |

## 红旗 — STOP

- 没有目标读者就开始写
- 没有一句话核心主张
- 标题无法串成完整逻辑
- 把未验证事实写成确定结论
- 一段里有多个互相竞争的主张
- deck 页面文案超过演示者能自然讲完的量

## 输出模板

内容写作完成后应产出以下结构（记录于验证证据中）：

```markdown
### Content Writing 交付记录

**产物类型**: [document / article / deck]
**目标读者**: [读者群 + 使用场景]
**核心主张**: [一句话]
**语气标准**: [正式 / 直接 / 温和 / 专业 / 启发 / 行动导向]

**内容骨架**:
1. [章节1标题] → [该章节目的句]
2. [章节2标题] → [该章节目的句]
3. ...

**事实清单**:
| 事实 | 来源 | 状态 |
|------|------|------|
| [具体事实] | [URL / 用户确认 / 项目文档路径] | 已验证 / 假设 / 来源待查 |

**编辑轮次**:
- 结构编辑: [改动摘要]
- 逻辑编辑: [改动摘要]
- 语言编辑: [改动摘要]
- 语气编辑: [改动摘要]
```

## 验证清单

- [ ] artifact_type 已读取
- [ ] 目标读者和使用场景明确
- [ ] 一句话核心主张已写出
- [ ] 内容骨架先于正文建立
- [ ] 关键事实已验证或标注假设
- [ ] 标题层级和逻辑顺序清楚
- [ ] 语气与 spec 一致
- [ ] 验证证据已记录