---

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 是参考不是规定