# Docs Writer

> 撰写或修改 README、技术教程、API 说明与变更日志。局部修改保留现有结构；新建 README 或明确要求时处理头部与徽章。不因仅提到文档名称而触发。

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

---


# 技术文档写作（docs-writer）

按五原则与四类文档最小结构，产出可扫描、带可运行示例的 Markdown 文档。规则与模板见 [references/style-guide.md](references/style-guide.md) 与 [references/templates.md](references/templates.md)。

## 何时使用

- 撰写或修订 README、项目说明、安装与快速上手
- 文档化 API、函数、CLI 参数、配置项
- 编写教程、上手指南、分步教学
- 撰写变更日志、发布说明、迁移指引
- 解释架构、设计决策、复杂技术概念

## 何时不使用

- 写业务代码注释、commit message、PR 描述 → 直接写，不用此 skill
- 接口契约的强约束规范 → 用 api-docs
- PRD / 需求文档 → 用 prd-creator

## 写作五原则

| 原则 | 要点 | 反例 |
| --- | --- | --- |
| **目标先行** | 先答"为什么用"，再讲"怎么用" | 开头堆功能列表 |
| **示例胜过描述** | 操作性概念按需配可运行代码与预期输出 | 关键操作缺少示例 |
| **渐进披露** | Quick Start 在前，深潜在后；复杂主题用链接隔离 | 一上来铺全部配置 |
| **可扫描** | 描述性标题、3 项以上用列表、代码加语言标签 | 大段无层级散文 |
| **主动 + 现在时** | "运行 X 返回 Y"，不是"X 被运行后 Y 被返回" | 被动语态连串 |

## 文档类型选择

按读者意图选型，而非按内容罗列：

| 读者想… | 文档类型 | 最小结构见 |
| --- | --- | --- |
| 评估/上手项目 | README | [README 模板](references/templates.md#readme) |
| 调用接口/函数 | API 文档 | [API 文档模板](references/templates.md#api-文档) |
| 跟着做完成一个任务 | 教程 | [教程模板](references/templates.md#教程) |
| 了解版本变化 | 变更日志 | [变更日志模板](references/templates.md#变更日志) |
| 理解概念/设计 | 解释性文档 | 用 README 或独立文章，遵循同样五原则 |

## README 专用规则

仅在新建 README，或用户明确要求调整头部与徽章时，读取 [README 模板](references/templates.md#readme) 和 [README 头部与徽章](references/style-guide.md#readme-头部与徽章)，执行与请求相关的步骤。其他 README 修改保留现有版式，不自动添加或统一徽章：

1. **检查头部**：识别第一个 H1、简介、Logo、导航、已有居中容器和全部 `img.shields.io` 图片 URL。
2. **补充徽章**：没有 Shields.io 徽章时，从仓库文件提取可靠事实，默认添加 2–4 枚技术栈、许可证、CI 或版本徽章；信息不足时减少数量，不虚构状态。
3. **统一样式**：将所有 Shields.io URL 的 `style` 参数新增或替换为 `for-the-badge`，保留其他参数、图片文本和链接目标。
4. **居中头部**：居中显示 Logo、项目主标题、简介和徽章区；复用已有 `<div align="center">`，避免嵌套或重复元素。
5. **保护正文**：在第一个 H2 前结束居中区域，不重排后续章节，不修改非 Shields 图片。
6. **核对事实**：许可证、CI、版本、覆盖率和下载量等徽章必须能从仓库或可信发布源验证；无法确认时不添加并说明缺失依据。

README 以外的文档不自动应用上述徽章规则，除非用户明确要求。

## 工作流程

1. **定类型与读者**：确认上述哪类文档，读者是新手/中级/专家。
2. **套最小结构**：新建文档从 [templates.md](references/templates.md) 取必要章节；局部修改保留结构，只更新相关内容。README 专用规则仅按其适用条件执行。
3. **填示例**：相关操作需要演示时，提供可运行代码与预期输出；不为纯文字修改补造示例。
4. **风格校对**：按 [style-guide.md](references/style-guide.md) 逐项过（语态、格式、术语、反模式）。
5. **链接检查**：检查新增或修改的链接与受影响锚点；不因局部修改重新检查无关外链。

## 验收（Gate）

按明确标准自检；复杂或高风险文档按需独立审查，不强制另找 Agent。

| 角色 | 说明 |
| --- | --- |
| 执行 | 主 Agent 按工作流程产出 |
| 验收 | 对照 [style-guide.md 的反模式清单](references/style-guide.md#常见反模式校对清单) 检查相关项；新增或修改可执行示例时抽检代表性示例，无代码时跳过 |

验收不通过时：带着具体错误信息修正，进入下一轮（见下方停止条件）。

## 停止条件

| 类型 | 上限 |
| --- | --- |
| 自修订迭代 | 单文档最多 3 轮 |
| Token / 成本 / 时间 | 仅采用用户或工具已明确配置的上限，不自行编造 |

检查通过即结束，不为凑轮数重复修订。触达适用上限或同一外部阻塞重复出现时，停止该部分重试，说明未完成项，继续不受影响的工作。

## 参考文件

- **[references/templates.md](references/templates.md)** — README、API 文档、教程、变更日志的最小结构与示例
- **[references/style-guide.md](references/style-guide.md)** — 语态人称、格式约定、代码示例规范与常见反模式