| name | writing |
| version | 2.0.0 |
| last_updated | "2026-05-07T00:00:00.000Z" |
| 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 报告写作流程
- 决定基调：浅色阅读型（
report-template.html）还是深色路演型（templates/report-pitch.html）——也可以混合
- Read 对应的组件示例 HTML 文件（看可用类名）
- 按 components.md 挑组件、按内容组装
- 调 diagram skill 生成图表（评审场景图带标题，文档配图不带——见 diagram skill）
- Write 输出
open 命令打开供 review
5.4 Markdown 文档写作流程
- 按 1.1 识别内容形态 → 选组件（多数 MD 组件 = 表格 / 列表 / 标题 / 代码块）
- （可选）参考
references/templates/*.md 找组合范式
- 直接写
- 调
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 是参考不是规定
