Writing

通用写作（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 是参考不是规定

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: 312362115
• Source: 312362115/claude
• License: MIT

Install and usage instructions live in the source repository linked above.