---
name: writing
version: 2.0.0
last_updated: 2026-05-07
repository: https://github.com/312362115/claude
description: >
  通用写作技能：以"内容→组件→组合"的方式产出技术文档、产品文档、汇报材料。
  覆盖 spec / plan / PRD / 用户手册 / 项目汇报 / 方案路演 / 调研报告 等所有结构化文档场景。
  核心理念：组件驱动，不预设模板。先看内容形态，再挑能装这种形态的组件，
  组合自然成文——不强制章节结构、不预设"必备模块"。
  组件库（HTML / Markdown / 图示）见 references/components.md，
  常见组合范式（spec / plan / PRD 等）见 references/templates/——但模板是参考不是规定。
  触发词：写文档、写方案、写计划、写 PRD、写汇报、项目总结、写指南、帮我写、文档、方案设计。
  即使用户没有明确说"写"，只要意图是"产出一份结构化的文档/报告/材料"，都应触发此技能。
  本 skill 只负责"写"，不负责"调研"（调研由 deep-research 承担）和"调度"（流程由 task-start 承担）。
---

# 通用写作（Writing）

> 知道了什么，和让别人也知道，是两种完全不同的能力。
> 本 skill 是后者——把已有的知识、决策、进展，变成不同读者能看懂、愿意看的文档。

---

## 核心理念：组件驱动，不预设模板

写作不是"按模板填空"，而是"把内容装进合适的组件、组合成文档"。

```
传统模板派：先选模板（spec / PRD / 汇报）→ 模板说必备 X 章节 → 内容硬塞进去
本 skill：先看内容形态 → 挑能装这种形态的组件 → 自然组合
```

**为什么不再用"模式 → 模板"？**
- 真实内容很少正好匹配某个模板（比如同一份汇报里既有数据又有架构方案）
- 模板的"必备章节"会让简单内容膨胀、复杂内容装不下
- 写作的核心判断是"这段内容长什么样、用什么组件能讲清楚"，模板分类只是干扰

**核心资源**：
- `references/components.md` — **写作组件库**（HTML / Markdown / 图示组件）。这是本 skill 最重要的索引文件
- `references/templates/*.md` — **常见组合范式**（spec / plan / PRD 等）。是参考，不是规定
- `references/report-template.html` — 浅色阅读型 HTML 报告组件示例集
- `references/templates/report-pitch.html` — 深色路演型 HTML 报告组件示例集

---

## 第一步：理解内容

收到写作请求后，**先理解内容长什么样**——不是先选"写哪种文档"。

### 1.1 内容形态分析

问自己以下问题（已知的跳过，模糊的追问用户）：

| 问题 | 影响 |
|------|------|
| **要表达的核心是什么？** | 决定主线（决策？过程？数据？说明？） |
| **读者是谁？** | 决定用词深度和可视化程度（开发者 / 产品 / 用户 / 评审人 / 上级） |
| **读者读完要做什么？** | 理解？决策？执行？检查？追责？ |
| **内容含哪些"形态"？** | 决策？数字？流程？对比？时间线？架构？API 接口？ — 决定调哪些组件 |
| **篇幅预期？** | 简短摘要？完整报告？投屏材料？ |
| **存放位置？** | `docs/` 哪个子目录？（按 CLAUDE.md 规范） |

### 1.2 输出格式判断

| 内容/读者特征 | 推荐格式 |
|-------------|---------|
| 开发者读、能跑能用 | Markdown |
| 内部协作、需要 git 跟踪 | Markdown |
| 需要投屏 / 路演 / 对外宣讲 | HTML（深色路演型） |
| 季度复盘 / 数据汇报 | HTML（浅色阅读型） |
| 内含大量统计图 / 富视觉 | HTML |
| 用户帮助文档 / 用户手册 | Markdown 或 HTML（看用户偏好） |

> HTML 不再硬分"汇报型 vs 路演型"——同一份 HTML 可以混合 Hero（路演风）+ Metric-Card（数据）+ Figure（架构图）。看内容选组件，不看"汇报子模式"。

### 1.3 与用户对齐（仅当模糊时）

把你的理解告诉用户，让用户确认或修正：

```
我的理解：
- 内容核心：xxx
- 读者：xxx
- 形态识别：含决策（3-4 项）/ 架构图（2 张）/ 风险点（5 个）
- 推荐格式：HTML（路演风格 + 数据指标混合）
- 存放：docs/reviews/

确认开始？
```

简单明确的需求（"帮我写个 spec 改造 session 模块"）跳过对齐，直接进下一步。

---

## 第二步：选组件

根据 1.1 识别出的内容形态，到 `references/components.md` 查找对应组件。

**速查表**（完整版见 `components.md` 的"H. 组合速查"）：

| 内容形态 | 推荐组件 |
|--------|---------|
| 一屏建立全局认知 | Hero + Pill + TOC |
| 章节扫读 | section-head + summary |
| 一张图说清楚 | Figure |
| 并列同质项 | Card-Grid |
| A vs B 二选一 | VS-Block |
| 结构化对照 | 表格 |
| 时间维度 / 阶段 | Timeline |
| 已选/待观察/风险 | Decision-Card 三色 |
| 关键数字 | Metric-Card |
| 0-100% 进度 | Progress-Bar |
| 维度评分 | Score-Bar |
| 重要提示打断 | Callout |
| 行内状态标注 | Badge |
| 嵌入统计图 | Chart-Container |
| ≤ 10 节点的轻量流程 | ` ```flow ` 代码块 |
| CLI 命令演示 | ` ```terminal ` 代码块 |

**组件选择原则**：
- 同样的内容能用更轻的组件就用更轻的（能用列表别用 grid，能用 grid 别用 vs-block）
- 组件存在是为了表达内容，不是为了视觉好看——没有对应内容就别用对应组件
- 单一文档内组件不要堆叠超过 8-10 种，会变成"组件展示馆"

---

## 第三步：参考组合范式（可选）

`references/templates/*.md` 下有几份**常见组合范式**——某些类型的文档历史上常用什么章节顺序。**这是参考不是规定**：

| 文件 | 何时参考 |
|------|---------|
| `spec.md` | 写技术方案——需要"背景 → 调研 → 决策 → 技术方案"骨架时 |
| `plan.md` | 写开发计划——需要"关联方案 + 子任务 checklist"骨架时 |
| `api-doc.md` | 写 API 文档——需要"概览 / 认证 / 接口列表 / 错误码"骨架时 |
| `dev-guide.md` | 写开发指南——需要"前置条件 / 环境搭建 / 操作步骤 / 常见问题"骨架时 |
| `prd.md` | 写 PRD——需要"用户场景 / 功能描述 / 验收标准"骨架时 |
| `operation-plan.md` | 写运营方案——需要"目标 / 策略 / 执行 / 评估"骨架时 |
| `user-guide.md` | 写用户手册——需要"快速开始 / 核心功能 / 操作步骤"骨架时 |

**借鉴方式**：
- 内容跟范式贴合 → 借鉴章节顺序
- 内容只覆盖部分 → **删掉**用不到的章节，不要硬写
- 内容超出范式 → 自由加章节
- 章节存在的理由必须是"内容需要它"，不是"模板要求它"

不参考也行——内容形态清晰时直接进第四步。

---

## 第四步：素材就位

动笔前确认素材是否充足：

| 素材来源 | 获取方式 |
|---------|---------|
| 代码 / 配置 | Read / Grep 读取项目文件 |
| Git 历史 | `git log` 查看变更记录 |
| 已有文档 | 读取 `docs/` 下相关文档 |
| 项目数据 | 用户提供或从 BI/监控获取 |
| 调研结论 | 引用 deep-research 的输出 |
| 复盘记录 | 读取 `docs/decisions/` |

**素材不足时**：主动告知用户缺少什么信息，不要编造。如果需要调研，引导用户使用 `deep-research` skill。

---

## 第五步：撰写

按"组件 + 内容"组合输出。**遵循以下通用准则**：

### 5.1 通用写作准则

- **中文为主**：正文中文，代码 / 命令 / 专有名词保留英文
- **措辞精确**：避免"大概""好像""可能"等模糊用语
- **数据优先**：能用数据说明的不用形容词
- **结构服务内容**：表格 / 列表 / 卡片是为了表达更清楚，不是为了好看
- **篇幅自适应**：根据内容复杂度自然决定篇幅，不人为压缩也不注水
- **图表有效**：需要图表调 `diagram` skill 生成；简单流程用 ` ```flow ` 代码块；调用关系超过 5 个节点才考虑流程图

### 5.2 按读者类型微调

| 读者 | 关键点 |
|------|------|
| **开发者** | 准确 > 优美；可执行 > 可读；命令 / 代码 / API 路径精确到版本 |
| **产品 / 运营** | 用户语言 > 技术语言；场景驱动；不遗漏边界（空状态、错误状态） |
| **用户 / 客户** | 零术语；步骤可照做；常见问题按频率排序 |
| **评审人 / 上级** | 结论先行；图为主、文字为注脚；风险前置；行动明确 |

### 5.3 HTML 报告写作流程

1. 决定基调：浅色阅读型（`report-template.html`）还是深色路演型（`templates/report-pitch.html`）——也可以混合
2. Read 对应的组件示例 HTML 文件（看可用类名）
3. 按 components.md 挑组件、按内容组装
4. 调 diagram skill 生成图表（评审场景图带标题，文档配图不带——见 diagram skill）
5. Write 输出
6. `open` 命令打开供 review

### 5.4 Markdown 文档写作流程

1. 按 1.1 识别内容形态 → 选组件（多数 MD 组件 = 表格 / 列表 / 标题 / 代码块）
2. （可选）参考 `references/templates/*.md` 找组合范式
3. 直接写
4. 调 `preview-md` skill 在浏览器预览

---

## 第六步：质量自检

写完后自动执行以下检查：

| # | 检查项 | 说明 |
|---|--------|------|
| 1 | **内容覆盖** | 1.1 识别出的所有形态都有对应组件承载？没有"忘记装的内容"？ |
| 2 | **组件适配** | 用的组件是否真适合内容（不是为了好看硬塞）？ |
| 3 | **读者适配** | 用词和深度匹配目标读者？技术文档不废话，产品文档不用术语 |
| 4 | **信息准确** | 引用的文件路径、版本号、数据是否和当前代码 / 事实一致？ |
| 5 | **可操作性** | 技术文档中的步骤能否直接执行？汇报中的行动项是否明确？ |
| 6 | **格式规范** | 文件命名、存放位置是否符合 CLAUDE.md 文档规范？ |
| 7 | **组件克制** | 是否堆叠了过多组件让文档变成"展示馆"？该删的删 |

自检发现问题直接修复，不需要告知用户。

---

## 第七步：交付

| 内容类型 | 输出路径 | 交付方式 |
|---------|---------|---------|
| 技术方案 / 计划 / 指南 | `docs/specs/` `docs/plans/` `docs/guides/` | 写完后调 `preview-md` 预览 |
| 产品文档 | `docs/prds/` `docs/guides/` | 写完后调 `preview-md` 预览 |
| 汇报 / 路演 / 评审 HTML | 用户指定或 `docs/reports/` `docs/reviews/` | 同级建 `assets/` 存图，写完后 `open` 打开 HTML |

---

## 与其他 skill 的关系

```
deep-research → 调研结论 → writing（把调研写成文档）
tech-evaluation → 选型结论 → writing（把选型写成方案）
task-start → 对焦结论 → writing（写 spec / plan）
task-finish → 复盘结论 → writing（写 decisions / 汇报）

writing 调用：
  ← diagram skill（生成图表嵌入文档）
  ← preview-md skill（Markdown 文档预览）
```

**边界划分**：
- **writing vs deep-research**：deep-research 负责"搞清楚"（调研过程），writing 负责"写清楚"（文档产出）。deep-research 内部的报告撰写是调研流程的一部分，writing 不接管
- **writing vs task-start**：task-start 负责"什么时候需要写 spec/plan"（流程调度），writing 负责"怎么写好"（写作质量）

---

## 反模式

- ❌ 先选"写哪种文档"再填模板——应该先看内容形态再选组件
- ❌ 因为模板说"必备章节"就硬写——章节存在的理由是内容需要它
- ❌ 因为有 hero 组件就给所有 HTML 加 hero——内部 spec 不需要 hero
- ❌ 因为有 decision-card 三色就把普通结论包成 decision——decision 是为"已决/未决/风险"三态信号化设计的
- ❌ 因为有 metric-card 就编数字凑指标——没数字就别用
- ❌ 单一文档堆叠 ≥ 10 种组件——变成"组件展示馆"
- ❌ 把"组合范式"误读为"必备模板"——templates/*.md 是参考不是规定