# Doc Style

> 结构化编写、重构、润色和验收 Markdown / MDC 文档。 只要用户要创建、编辑、润色、改写、评审或整理任何 `.md` / `.mdc` 文件， 或需要整理规则文档、普通说明文档、PR review 评论、GitHub 评论、零散草稿，就应使用这个 skill。

- Skill: `zhuozhuocrayon/doc-style` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add zhuozhuocrayon/doc-style`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zhuozhuocrayon/doc-style/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: zhuozhuocrayon (https://skillmd.com/u/zhuozhuocrayon)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zhuozhuocrayon/doc-style

---


# Doc Style

## 0x01 定位

`doc-style` 负责 Markdown / MDC 文档的结构设计、表达压缩与交付前润色。

适用范围：

- 文件范围：所有 `.md` / `.mdc` 文档编辑、重构、润色与验收。
- 其他文档类型：规则文档、普通说明文档。
- 短交付：PR review 评论、GitHub 评论、零散草稿的结构化压缩。

职责边界：

- 只处理文档内容、结构和表达。
- 不负责外部资产定位、元数据治理或发布流程。

## 0x02 通用必读

【CRITICAL（必须执行，不可协商）】无论文档类型是什么，都必须先读 `references/common/` 下全部 `5` 个文件：

- [Title](references/common/title.md)
- [Text](references/common/text.md)
- [Paragraph](references/common/paragraph.md)
- [Number](references/common/number.md)
- [Marks](references/common/marks.md)

## 0x03 第一性原理

文档的价值是让读者准确复原事实、决策、关系和边界。不能改变读者理解或行动的信息不应保留。

1. **信息必须有增量**：每句话至少补充事实、结论、原因、边界、例外或动作中的一项。
2. **关系优先交给结构**：表格、图、协议示例和核心伪代码负责表达字段、映射、层级、流程和协作关系。
3. **文字只补结构的语义缺口**：说明结构无法直接表达的原因、约束、兼容策略、异常语义和决策后果。
4. **职责必须可定位**：句子应能识别谁在什么条件下对什么对象执行什么动作，不把多个角色或层级的职责写在一起。
5. **稳定文档使用现在时**：正文描述当前事实和目标契约。历史过程只在影响决策、兼容性或迁移方式时保留。

结构已经表达某项信息时，删除复述性文字。不要用一段话解释读者可以直接从类图、字段表或伪代码中读出的内容。

## 0x04 写作流程

1. **判定目标**：明确目标读者、交付形态和读者需要拿到的结论。
2. **读取规范**：完整阅读 `common/` 全部 `5` 个文件。
3. **拆分信息**：列出事实、决策、关系、边界和动作，删除没有信息增量的内容。
4. **选择载体**：先用结构承载关系，再为结构无法表达的信息补充文字。
5. **完成初稿**：句子使用明确主语，不混写职责，不把过程状态写成稳定规则。
6. **润色与自检**：按 `0x05` 检查并交付修订后的版本。

## 0x05 润色与自检

### a. 润色

1. **读取规范**：完整阅读 `0x02` 提及的全部文档和 [Humanizer](references/humanizer.md)。
2. **检查载体**：确认表格、图、协议示例和伪代码已经承载的关系，删除文字复述，按载体规则组织补充语义。
3. **逐句检查**：识别空泛引导、历史语气、模糊主语、职责混写和抽象结论。
4. **重写违例**：保留原意和必要上下文，用明确的主体、动作、对象和条件重写。
5. **呈现版本**：交付修订后的完整版本，不只列问题清单。

修订后的文本必须满足：

- 大声朗读时听起来自然
- 自然地改变句子结构
- 使用具体主体、动作、对象和条件，不用模糊主张
- 为上下文保持适当的语气
- 适当时使用简单的结构（是/有）
- 结构负责表达关系，文字只补充结构未表达的语义

### b. 输出闸门

【CRITICAL（必须执行，不可协商）】审稿自检不能用自动检查替代，低于 `90` 分时，回到 `0x05.a` 重新润色。

| 维度 | 评估标准 | 得分 |
| --- | --- | --- |
| **直接性** | 是否直接陈述事实、决策或动作，删除“下面介绍”“需要说明”等空泛引导 | /8 |
| **具体性** | 是否写清主体、动作、对象、条件和结果，避免“相关处理”“进一步优化”等模糊表达 | /8 |
| **职责边界** | 每项职责是否归属明确，同一句或同一列表项是否混入多个角色或层级 | /8 |
| **结构承载** | 载体是否匹配信息关系，附属表达是否符合对应的载体规则 | /8 |
| **时间稳定性** | 稳定正文是否使用当前事实和目标契约，历史过程是否只保留必要的决策影响 | /8 |
| **清晰度** | 是否存在黑话、术语堆叠、被动嵌套、长定语或不明确指代 | /8 |
| **精炼度** | 是否删除过程叙述、跨节重述、结构复述和无信息量的衔接句 | /8 |
| **自然度** | 句式和节奏是否自然，是否避免机械排比、公式结构和过度解释 | /8 |
| **文档审美** | 结构、信息层级、行文节奏、留白和对齐是否支持快速阅读 | /8 |
| **common 规范** | 按 `0x02` 的 `5` 个 common 文件检查。不满足一点扣 `2` 分，扣分上限为 `28` 分 | /28 |