writing
Installation
SKILL.md
通用写作（Writing）
知道了什么，和让别人也知道，是两种完全不同的能力。 本 skill 是后者——把已有的知识、决策、进展，变成不同读者能看懂、愿意看的文档。
第一步：识别写作模式
收到写作请求后，先判断属于哪种模式：
写作请求
│
├─ 读者是开发者？写的是技术内容？
│ └─ YES → 技术文档模式
│
├─ 读者是产品/运营/用户？写的是业务内容？
│ └─ YES → 产品文档模式
│
└─ 读者是上级/跨团队？需要汇报/总结？
└─ YES → 汇报模式
模式速查表
| 模式 | 读者 | 典型产出 | 输出格式 | 风格 |
|---|---|---|---|---|
| 技术文档 | 开发者 | spec、plan、API 文档、开发指南 | Markdown | 准确、完整、可执行 |
| 产品文档 | 产品/运营/用户 | PRD、用户故事、运营方案、帮助文档 | Markdown | 清晰、面向场景、非技术语言 |
| 汇报 | 上级/跨团队/利益相关方 | 项目汇报、里程碑总结、OKR 复盘 | 精排 HTML | 精炼、结论先行、数据可视化 |
快速判断信号
| 用户说 | 模式 |
|---|---|
| "写个方案""出个 spec""写个 plan" | 技术文档 |
| "API 文档""接口文档""开发指南" | 技术文档 |
| "写个 PRD""用户故事""运营方案" | 产品文档 |
| "帮助文档""使用说明""用户手册" | 产品文档 |
| "项目汇报""里程碑总结""OKR 复盘" | 汇报 |
| "给老板看""跨团队同步""方案评审" | 汇报 |
第二步：对齐写作要素
不管哪种模式，动笔前先确认以下要素（已知的跳过，模糊的追问）：
| 要素 | 为什么重要 |
|---|---|
| 读者是谁 | 决定用词深度和解释粒度 |
| 核心目的 | 这份文档要帮读者做什么？理解？决策？执行？ |
| 关键信息 | 必须包含哪些内容？有没有现成的素材/数据？ |
| 篇幅预期 | 简短概要还是完整文档？ |
| 存放位置 | 存 docs/ 的哪个子目录？（按 CLAUDE.md 文档规范） |
对齐方式：和 task-start 一样，给出你的理解让用户确认，不要空泛地问"你想写什么"。
技术文档模式
文档类型与模板
技术方案（spec）
存放：docs/specs/YYYY-MM-DD-<模块名>-<主题>.md
模板详见 references/templates/spec.md。
核心结构：
背景与动机 → 现状分析 → 调研与备选方案 → 决策与取舍 → 技术方案 → 风险与边界
关键要求：
- 背景不能省——没有背景的方案是空中楼阁
- 每个备选方案要有调研内容、验证方式、验证结果
- 决策必须写明核心理由和取舍说明
- 调研中的 PoC 代码/命令/数据一并记录
开发计划（plan）
存放：docs/plans/YYYY-MM-DD-<模块名>-plan.md
模板详见 references/templates/plan.md。
核心结构：
关联方案 → 子任务列表（checklist）→ 每个子任务的做什么/涉及文件/验收标准
关键要求：
- 必须关联对应的 spec 文件
- 每个子任务有明确的交付物和验收标准
- 用 checklist 跟踪进度，实时更新
API 文档
存放：docs/guides/<服务名>-api.md
模板详见 references/templates/api-doc.md。
核心结构：
概览 → 认证方式 → 接口列表 → 每个接口（路径/方法/参数/响应/示例/错误码）
关键要求：
- 每个接口必须有可直接复制执行的请求示例（curl 或代码）
- 响应示例用真实的数据结构，不用 placeholder
- 错误码说明要包含"什么情况下会返回"和"客户端该怎么处理"
开发指南
存放：docs/guides/<主题>.md
模板详见 references/templates/dev-guide.md。
核心结构：
前置条件 → 环境搭建 → 核心概念 → 操作步骤 → 常见问题
关键要求：
- 步骤可直接照做，不跳步
- 命令可直接复制执行
- 常见问题来自真实踩坑经验
技术文档写作准则
- 准确 > 优美：技术文档的第一要求是正确，不是好看
- 可执行 > 可读：读者拿着文档能直接干活，不需要再问人
- 代码即示例：能给代码片段的不用文字描述
- 版本敏感：涉及版本号、API 路径时必须和当前代码一致
- 不假设读者知道：专有术语首次出现时简要解释
产品文档模式
文档类型与模板
PRD（产品需求文档）
存放：docs/prds/YYYY-MM-DD-<功能名>.md
模板详见 references/templates/prd.md。
核心结构：
背景与目标 → 用户场景 → 功能描述 → 信息架构 → 交互说明 → 验收标准 → 排期与优先级
关键要求：
- 用户场景用"谁在什么情况下要做什么"的格式
- 功能描述从用户视角写，不从实现视角写
- 验收标准可量化、可测试
运营方案
存放：docs/prds/YYYY-MM-DD-<方案名>.md 或独立目录
模板详见 references/templates/operation-plan.md。
核心结构：
背景与目标 → 目标用户 → 方案策略 → 执行计划 → 资源需求 → 效果评估 → 风险预案
帮助文档 / 用户手册
存放：docs/guides/<功能名>-user-guide.md
模板详见 references/templates/user-guide.md。
核心结构：
快速开始 → 核心功能 → 操作步骤（截图/示意图）→ 常见问题 → 联系支持
关键要求：
- 零技术术语，或首次出现时用日常语言解释
- 步骤配图（可调 diagram skill 生成流程示意图）
- 常见问题按频率排序
产品文档写作准则
- 用户语言 > 技术语言："点击保存按钮"而非"调用 save 方法"
- 场景驱动：每个功能点都绑定一个用户场景
- 不遗漏边界：空状态、错误状态、极端情况都要提及
- 可视化辅助：流程图、信息架构图可调 diagram skill 生成
汇报模式
汇报的核心不是"我做了什么"，而是"这件事的价值/风险/进展对你意味着什么"。
汇报类型
| 类型 | 场景 | 重点 |
|---|---|---|
| 项目进展汇报 | 周会/月会/里程碑 | 进度、风险、下一步 |
| 方案评审汇报 | 技术评审/业务评审 | 问题→方案→为什么选这个 |
| OKR / 目标复盘 | 季度复盘 | 目标达成度、关键产出、经验教训 |
| 专项汇报 | 事故复盘/竞品分析/调研总结 | 结论→依据→建议 |
输出格式：精排 HTML
汇报模式必须输出精排 HTML，可浏览器直接打开，效果接近演示文稿。
HTML 模板：references/report-template.html
写作流程：
- Read 模板
references/report-template.html - 按模板结构填充内容
- 需要图表时调 diagram skill 生成，以 HTML/SVG 内嵌
- Write 输出到目标路径
open命令在浏览器中打开供用户 review
可用组件（复用 deep-research HTML 组件体系并扩展）：
| 组件 | 类名 | 适用场景 |
|---|---|---|
| 指标卡片 | .metric-card |
关键数字展示（完成率、收入、用户数） |
| 进度条 | .progress-bar |
项目进度、目标达成度 |
| 卡片网格 | .card-grid + .card |
关键发现、成果并列展示 |
| 时间轴 | .timeline + .tl-item |
项目里程碑、事件时间线 |
| 对比块 | .vs-block |
计划 vs 实际、本期 vs 上期 |
| 状态徽章 | .badge |
进度状态（已完成/进行中/延期/风险） |
| 图表容器 | .chart-container |
嵌入 diagram skill 生成的图表 |
| 提示框 | .callout |
关键风险、重要结论高亮 |
| 评分条 | .score-bar |
量化评估展示 |
汇报写作准则
- 结论先行：第一屏就让读者知道核心结论，详细论据往后放
- 数据驱动：每个结论配数据支撑，能用图表不用文字
- 精炼不啰嗦：每页/每段只传达一个核心信息
- 风险前置：坏消息比好消息重要，风险项醒目标注
- 行动明确：不只是"汇报了"，要有明确的"需要什么支持""下一步做什么"
- 视觉层次：用字号、颜色、间距引导阅读顺序，重点突出
汇报模板结构
封面（标题 + 汇报人 + 日期）
↓
核心摘要（指标卡片 + 一句话结论）
↓
正文章节（按汇报类型选择）
├─ 项目进展：进度总览 → 本期完成 → 风险与阻塞 → 下期计划
├─ 方案评审：问题背景 → 方案对比 → 推荐方案 → 实施计划
├─ OKR 复盘：目标回顾 → 关键结果达成 → 亮点与不足 → 下季度方向
└─ 专项汇报：结论 → 分析过程 → 建议
↓
行动项（明确责任人、时间节点）
第三步：写作执行
3.1 收集素材
动笔前确认素材是否充足：
| 素材来源 | 获取方式 |
|---|---|
| 代码/配置 | Read / Grep 读取项目文件 |
| Git 历史 | git log 查看变更记录 |
| 已有文档 | 读取 docs/ 下相关文档 |
| 项目数据 | 用户提供或从 BI/监控获取 |
| 调研结论 | 引用 deep-research 的输出 |
| 复盘记录 | 读取 docs/decisions/ |
素材不足时：主动告知用户缺少什么信息，不要编造。如果需要调研，引导用户使用 deep-research skill。
3.2 拟定大纲
正式撰写前，先输出大纲让用户确认：
## 文档大纲：<标题>
### 结构
1. <章节 1> — 要写什么
2. <章节 2> — 要写什么
3. ...
### 关键决策
- <要在文档中表达的核心观点/结论>
### 待确认
- <需要用户补充的信息>
用户确认后再开始正文撰写。小型文档（如更新已有 spec 的一个章节）可跳过大纲直接写。
3.3 撰写正文
按确认后的大纲和对应模式的模板撰写。遵循以下通用写作要求：
- 中文为主：正文用中文，代码/命令/专有名词保留英文
- 措辞精确：避免"大概""好像""可能"等模糊用语
- 数据优先：能用数据说明的不用形容词
- 结构清晰：善用表格、列表、对比矩阵呈现结构化信息
- 篇幅自适应：根据内容复杂度自然决定篇幅，不人为压缩也不注水
- 图表辅助：需要图表时调 diagram skill 生成（不带标题，标题由文档章节承担），不硬用文字描述复杂关系
- 轻量图示优先：简单流程/命令行步骤不调 diagram，用 preview-md 的
```flow/```terminal代码块，preview-md 会渲染为带样式的流程图/终端窗口：```flow：方案中的执行步骤、简单决策树、阶段串联（≤ 10 个节点）。复杂多分叉流程仍调 diagram```terminal：CLI 操作、安装/启动步骤、命令输出示例。单条命令仍用普通```bash- 完整语法和示例见 preview-md SKILL.md "扩展语法"章节
3.4 质量自检
文档写完后，自动执行以下检查：
| # | 检查项 | 说明 |
|---|---|---|
| 1 | 结构完整 | 是否包含模板要求的所有必备章节？ |
| 2 | 读者适配 | 用词和解释深度是否匹配目标读者？技术文档不废话，产品文档不用术语 |
| 3 | 信息准确 | 引用的文件路径、版本号、数据是否和当前代码/事实一致？ |
| 4 | 可操作性 | 技术文档中的步骤能否直接执行？汇报中的行动项是否明确？ |
| 5 | 无遗漏 | 对齐阶段确认的关键信息是否都覆盖到了？ |
| 6 | 格式规范 | 文件命名、存放位置是否符合 CLAUDE.md 文档规范？ |
自检发现问题直接修复，不需要告知用户。
第四步：输出与交付
| 模式 | 输出路径 | 交付方式 |
|---|---|---|
| 技术文档 | docs/specs/ docs/plans/ docs/guides/ |
写完后调 preview-md 预览 |
| 产品文档 | docs/prds/ docs/guides/ |
写完后调 preview-md 预览 |
| 汇报 | 用户指定或 docs/reports/ |
写完后 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 负责"怎么写好"（写作质量）。
Related skills