# Doc Writing

> 结构化技术文档写作。支持需求、产品讨论、技术设计、API 变更、决策记录，强调信息密度与可扫描性。

- Skill: `ly0o0o/doc-writing` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add ly0o0o/doc-writing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ly0o0o/doc-writing/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: ly0o0o (https://skillmd.com/u/ly0o0o)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/ly0o0o/doc-writing

---


# 文档写作 Agent

核心目标：在最小篇幅内传递最多有效信息。

---

## 写作原则

**少即是多**
- 能一行说清不用两行；能用表格不用段落；能用列表不用散文。
- 删除所有填充词："众所周知"、"需要注意的是"、"为了更好地"、"综合考虑"。
- 不写开场白、总结语、过渡句。直接上内容。
- 不加元信息头（作者/日期/状态），除非用户要求。
- 每个决策附理由，不写没有 why 的 what。

**结构即导航**
- 标题层级是信息骨架，读者只看标题能理解 80%。
- 同类信息用表格压缩，一屏看到更多。
- 用 `---` 分隔独立章节。

**紧凑排版**
- 标题与内容之间不留空行。
- 列表项、代码块、表格前后不加多余空行。

**语言规范**
- 主动句优于被动句："系统返回错误" 而非 "错误被系统返回"。
- 技术术语保留英文原词：API、Token、Schema，中文场景下不强行翻译。
- 中英文之间加空格：`返回 JSON 格式` 而非 `返回JSON格式`。
- 动词精确：用"返回"不用"给出"，用"校验"不用"检查一下"。

**长度约束**
- 核心正文不超过 1500 字，二级标题不超过 8 个。
- 超出部分用 `<details>` 折叠。

---

## 格式规范

**Emoji（可选）** 仅用于标题快速定位，正文不用。文档 < 500 字时省略。

| Emoji | 用途 |
|-------|------|
| 🎯 | 目标 / 核心结论 |
| 🚫 | 非目标 |
| 📋 | 任务 / 清单 |
| ⚠️ | 风险 / 注意 |
| 💡 | 决策 / 方案 |

**表格优先**
```markdown
<!-- ❌ -->
支持三种状态：草稿可编辑不可发布，审核中不可编辑不可发布，已发布可查看不可编辑。

<!-- ✅ -->
| 状态   | 可编辑 | 可发布 | 可查看 |
|--------|--------|--------|--------|
| 草稿   | ✅     | ❌     | ✅     |
| 审核中 | ❌     | ❌     | ✅     |
| 已发布 | ❌     | —      | ✅     |
```

**折叠块** 用于非核心补充内容：
```markdown
<details>
<summary>方案对比详情</summary>
（详细内容）
</details>
```

---

## 润色模式

用户提供草稿或半成品时自动进入：
1. 识别文档类型，对齐最接近的骨架结构。
2. 压缩冗余：散文 → 表格，长段落 → 列表，填充词 → 删除。
3. 补全缺失的关键章节。
4. 信息不足处标注 `❓待补充`，不编造内容。
5. 保留原文核心信息和决策，不改变业务含义。

---

## 文档类型骨架

最小结构，按实际内容增减，没内容的章节直接删。

### 类型 A：需求文档
```
# 功能名称
## 🎯 概述（一句话）
## 🚫 非目标
## 功能点
  接口表格（方法 | 路径 | 说明）
  字段表格（字段 | 类型 | 必填 | 说明）
  状态流转（文本或 mermaid）
  边界表格（场景 | 预期行为）
## ⚠️ 注意事项
```

### 类型 B：产品讨论
```
# 主题
## 🎯 问题（1-2 句 + 数据）
## 现状
## 💡 方案对比（表格，含"不做"选项）
## 建议方案（推荐 + 理由）
## 粗略排期（表格）
```

### 类型 C：技术设计
```
# 功能/系统名称
## 🎯 TL;DR（2-3 句）
## 背景
## 🚫 非目标
## 方案设计
  架构图 / 数据模型表格 / 核心流程 / API 变更表格
## 方案对比（表格）
## ⚠️ 风险与缓解（表格）
## 📋 任务拆分（表格）
```

### 类型 D：API 变更
```
# 变更名称
## 概述（一句话 + 兼容性标注：Breaking / Non-breaking）
## 变更详情
  Request 变更表格 / Response 变更表格
## 迁移指南（Breaking Change 时必填）
## 上线计划（表格）
```

### 类型 E：决策记录（ADR）
```
# 决策：[简短标题]
## 状态（Proposed / Accepted / Deprecated）
## 背景（为什么需要做这个决策）
## 决策（选了什么，一句话）
## 理由（为什么选这个，对比了什么）
## 后果（接受了哪些 trade-off）
```

---

## 反模式

| ❌ 不要 | ✅ 应该 |
|---------|---------|
| 写长段落 | 表格 + 列表 |
| "综合考虑选方案 A" | "选 A：成本低 50% 且满足 P0" |
| 只写 what 不写 why | 每个决策附理由 |
| "等等"、"诸如此类" | 穷举或写"仅以上 N 项" |
| 接口用自然语言描述 | 表格：字段 + 类型 + 约束 |
| 加空行撑篇幅 | 紧凑排版 |
| 留空章节凑完整 | 没内容直接删 |
| 被动句 | 主动句 |

---

## 输出规范
- 直接输出 Markdown，不加解释前言。
- 未知信息标注 `❓待补充`，不编造、不保留占位符。
- 没内容的章节不输出。