document

输出风格（使用朴素措辞，不用破折号或连字符）

这项技能生成的所有内容，包括文件和消息，都请使用简单直白的语言。以 you 称呼读者，语气亲切直接，就像同事交流一样。请将每个步骤都写成建议，让读者可以选择执行或跳过，而不是命令。保留有实际含义的技术术语，并用浅显的语言解释每个术语。标点中绝不使用破折号或连字符：不使用 em dash、en dash，也不使用带连字符的复合词。写作时用 read only，不要写 read-only。请用简单的词语表达，或改写句子。其他技能会匹配的代码、文件路径、命令标志和取值，请保留其中的连字符。使用短句、逗号或括号。清晰胜过巧妙。

这项技能的作用

你的角色： 技术写作者，依据记录写作，而不是凭空想象；为读者写作，而不是为作者写作。每句话都必须能追溯到实际发生的事情（提交、差异，或提供给你的事件事实），每份文档都要面向需要据此采取行动的人（见下方的受众栏）。绝不编造来源中没有的时间线条目、原因或改动。

根据真实的变更历史生成四种文档之一。主线程负责撰写文档本身；它唯一可以委派的工作是阅读，而且仅限于差异非常大时，委派给使用最便宜模型的 read only scout 子 Agent（Claude Code：haiku）：

类型	来源	受众	输出
pr	分支提交 + 相对于基准的差异	审查者	PR 标题 + 正文（聊天；可选择使用 gh pr 创建或编辑）
changelog	已合并的变更	开发者	附加到 CHANGELOG.md 的条目（Keep a Changelog）
release-note	标签或版本范围	最终用户	docs/releases/<version>.md（或聊天）
postmortem	事件（由工程师描述，另加任何 /debug 记录）	团队	docs/postmortems/<date>-<slug>.md

执行操作。无法推断文档类型时，最多只问一个问题（询问类型）；对于事后分析，还要询问无法从 git 读取的事件事实。

工件归属

PR 文本、CHANGELOG.md、docs/releases/、docs/postmortems/（由此技能负责）。除此之外不写入任何内容。

---

可移植性（适用于任何操作系统和 Agent）

适用于 macOS、Linux 或 Windows 上的任何 Agent Skills 客户端：

• 命令：唯一使用的 CLI 是 git（以及可选的 gh），它们在所有操作系统上的行为相同，请按展示的内容运行 git 命令行。其他 shell 代码片段仅供 POSIX 参考，不是可直接运行的脚本：不要假设存在 find、grep、sed、cat、test/[ ]、command -v 或 node -e。请使用 Agent 自带的跨平台文件工具（读取、搜索或 glob、写入）完成这些操作，并自行应用分支逻辑，不要通过 shell 的 if、变量或重定向来实现。
• 随附文件：所引用的路径相对于此技能的文件夹。主线程会将此技能的文件夹解析为绝对路径（它已经解析了这些相对路径，因此知道该文件夹的位置），并在写入时（步骤 3）自行读取 agent-prompt.md 和所选类型对应的模板文件。
• 不支持交互式提问？ 文档类型选择会使用交互式选择器（若 Agent 提供）。若没有，则以纯文本提出文档类型问题，并提供相同选项。

执行

1. 确定文档类型

• 如果作为参数传入（pr、changelog、release-note、postmortem）：使用该类型。
• 否则在上下文明显时进行推断（例如，功能分支领先于基准分支时 → pr；刚刚打好版本标签时 → release-note），然后用一个问题确认或询问。请将推断出的类型标记为 (推荐)；选择器会自动在最后添加一个可填写文本的自定义选项。请使用 Agent 的交互式选项选择器（Claude Code 上为 AskUserQuestion）；若没有选择器，则以纯文本提供相同选项，并将自定义选项放在最后：

"What should I write?"
  header: "Doc type"
  options:
    - label: "PR description"        → pr           # mark (recommended) if inferred
    - label: "Changelog entry"      → changelog
    - label: "Release notes"        → release-note
    - label: "Postmortem"           → postmortem

2. 收集源材料

收集下面的轻量级历史记录，然后在撰写时自行阅读差异和文件（对于非常大的差异，可让 scout 子 Agent 负责阅读）。

按如下所示运行这些 git/gh 命令；非命令步骤请使用你自己的文件工具和分支逻辑完成。

# base branch: use `main` if it exists, otherwise `master`
git rev-parse --verify main
# current branch
git rev-parse --abbrev-ref HEAD

# pr / changelog: the branch change set (BASE = the base branch above)
git log --oneline "BASE..HEAD"
git diff --name-only "BASE...HEAD"

# release-note: needs tags. List them; if there are none, fall back gracefully (treat as NO_TAGS).
git tag --sort=-creatordate

• “原因”的背景：列出 docs/specs/ 下文件名以数字开头的规格文件，并使用文件/通配符工具选出最近修改的 3 个（仅路径）。
• 仅限 pr：三项检查（记录每项结果，供步骤 2 处理边界情况）：
  • 此系统上是否有 gh？（GH_INSTALLED）
  • 仓库是否有 git 远程？运行 git remote；输出非空即表示 HAS_REMOTE。
  • 是否已存在 PR？运行 gh pr view --json number -q .number。如果输出 PR 编号，则视为 PR_EXISTS；如果命令报错或无输出，则不存在 PR。

按类型处理边界情况，由主线程在撰写前解决：

• release-note 范围：如果存在标签，范围为 <previous-tag>..<latest-tag>（或工程师指定的范围）。如果 NO_TAGS，不要猜测，应询问：“未找到版本标签。请提供版本名称和范围（例如 v1.0.0，涵盖 <commit>..HEAD），或者我将涵盖自首个提交以来的所有提交。”将已确定的范围/版本传给子 Agent。
• pr + gh：仅当 GH_INSTALLED 和 HAS_REMOTE 时，才可提出通过 gh 创建/更新 PR。如果 PR_EXISTS，操作应为 gh pr edit（更新正文），而不是 gh pr create。如果 gh 不可用或没有远程，PR 文本仅在聊天中提供，不要尝试运行 gh。运行 gh 和推送前务必征得确认（创建/更新 PR 属于对外操作）：先展示正文，再询问。无论 AGENTS.md 中的 ## Git 设置如何，这条规则都适用；该设置决定工作流是否会处理 PR（integration: off → 仅提供文本，除非工程师在此处提出要求，否则绝不推送或创建 PR）。
• postmortem：git 中不会包含事故经过。如果尚未提供，请向工程师询问必要信息：发生了什么故障、发生时间（含时区）、用户影响、如何发现，以及根本原因/修复措施（如有 /debug 输出，可请其提供）。将工程师提供的说明作为事故事实传递。子 Agent 不得编造他们未提供的时间线条目或原因。

3. 撰写文档（主线程）

将此技能的文件夹解析为绝对路径（你已经解析过这些相对路径，因此知道该文件夹的位置），然后在撰写时（仅此时）读取 agent-prompt.md 和所选类型的一个模板 templates/<type>.md。遵循 agent-prompt.md 并自行撰写文档。不要启动写作 Agent；对于 postmortem，根因综合分析由你在主线程上仔细推理完成。

需要应用的输入：

1. 文档类型及其模板（只读取所选模板）
2. 源：提交列表、差异命令，以及（postmortem）事故事实。自行阅读差异；对于非常大的差异（例如超过 25 个文件），将阅读工作交给 scout 子 Agent（haiku），让其按文件组/功能返回精简摘要，并据此撰写
3. 项目背景内容（项目名称、约定），读取 AGENTS.md；如果没有，则回退读取 CLAUDE.md，再加上用于了解“原因”的近期规格路径
4. 该类型的输出目标和今天的日期
5. pr：gh 操作，none (chat-only) | gh pr create | gh pr edit（根据 GH_INSTALLED/HAS_REMOTE/PR_EXISTS 检查结果）
6. changelog：如果存在 CHANGELOG.md 文件，匹配其现有格式（不要用 Keep a Changelog 强行替换已有的其他格式）
7. release-note：已确定的版本和范围

4. 传达结果

开头先说明类型和结果的存放位置；对于 pr，正文就是交付物，因此要完整展示（遵循 docs/conventions.md）。模板：

## /document <pr | changelog | release-note | postmortem> · <PR body below | CHANGELOG.md | docs/releases/<v>.md | docs/postmortems/<file> | PR #N updated>

<for pr: the title + full body, ready to paste · always shown in chat so it works without gh>
<for the others: a 2 to 3 line preview>
Scope: ticked `Document it`   (or "no scope row matched"; omit if not on the scope)

此技能不会提交、推送或合并；它只负责撰写文案（并勾选上文结束关卡中的 Document it 选项，这是它唯一会进行的范围编辑）。

---

参考文件

• agent-prompt.md：主线程在撰写时（步骤 3）读取并遵循的写作指南
• templates/：每种类型对应一个结构文件（pr.md、changelog.md、release-note.md、postmortem.md）；主线程在撰写时只读取所选类型对应的文件