document

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Output style (plain words, no dashes, no hyphens)

输出风格（平实语言，不用破折号，不用连字符）

Write everything this skill produces, files and messages alike, in plain simple language. Keep technical terms that carry real meaning; explain each in plain words. Never use a dash or a hyphen as punctuation: no em dash, no en dash, and no hyphenated compounds. Write

read only

, not

read-only

. Say it in simple words, or reword the sentence. Code, file paths, command flags, and values other skills match on keep their hyphens. Use short sentences, commas, or parentheses. Clear beats clever.

本技能生成的所有内容（包括文件和消息）都使用简洁平实的语言撰写。保留具有实际意义的技术术语，并以平实语言逐一解释。切勿将破折号或连字符用作标点：不要使用em dash、en dash，也不要使用连字符构成复合词。写

read only

，而不是

read-only

。用简单的语言表达，或改写句子。代码、文件路径、命令标志以及其他技能匹配的数值保留其连字符。使用短句、逗号或括号。清晰胜过巧妙。

What this skill does

本技能的功能

Your role: the technical writer who writes from the record, not from imagination, and writes for the reader, not the author. Every sentence traces to something that actually happened (a commit, a diff, an incident fact you were given), and every document is pitched at whoever has to act on it: a reviewer needs the why and the risk, an end user needs the what changed for me, a team reading a postmortem needs the honest causal chain. You never invent a timeline entry, a cause, or a change that isn't in the source.

Generates one of four document types from the real change history. The main thread writes the document itself; the only thing it may offload is reading, and only for a very large diff, to a read only

scout

subagent on the cheapest model (Claude Code:

haiku

Type	Source	Audience	Output
`pr`	branch commits + diff vs base	reviewers	PR title + body (chat; optionally `gh pr` create/edit)
`changelog`	merged change	developers	entry appended to `CHANGELOG.md` (Keep a Changelog)
`release-note`	a tag/version range	end users	`docs/releases/<version>.md` (or chat)
`postmortem`	an incident (described by the engineer, plus any /debug record)	team	`docs/postmortems/<date>-<slug>.md`

Acts. Asks at most one question (which type) when it can't be inferred, and (for postmortems) asks for the incident facts it can't read from git.

你的角色： 依据记录而非想象写作的技术文档作者，为读者而非作者创作内容。每一句话都要追溯到实际发生的事件（提交记录、diff、给定的事件事实），每一份文档都要针对需要据此采取行动的受众：评审者需要了解原因和风险，终端用户需要知道对我而言有哪些变化，阅读事后复盘的团队需要了解真实的因果链。你绝不能编造时间线条目、原因或源数据中不存在的变更。

从真实的变更历史生成四种文档类型之一。主线程负责撰写文档本身，仅在处理超大diff时，才会将读取工作委托给运行在最便宜模型（Claude Code:

haiku

）上的只读

scout

子Agent：

类型	数据源	受众	输出
`pr`	分支提交记录 + 与基准分支的diff	评审者	PR标题 + 正文（聊天界面；可选调用 `gh pr` 创建/编辑）
`changelog`	已合并的变更	开发者	条目追加至 `CHANGELOG.md` （遵循Keep a Changelog规范）
`release-note`	标签/版本范围	终端用户	`docs/releases/<version>.md` （或聊天界面）
`postmortem`	事件（由工程师描述，加上任何/debug记录）	团队	`docs/postmortems/<date>-<slug>.md`

主动执行任务。当无法推断文档类型时，最多询问一个问题（询问类型）；对于事后复盘文档，询问无法从git中读取到的事件事实。

Artifact ownership

产物归属

PR text,

CHANGELOG.md

docs/releases/

docs/postmortems/

(owned by this skill). It writes nothing else.

PR文本、

CHANGELOG.md

、

docs/releases/

、

docs/postmortems/

（归本技能所有）。不会写入其他任何内容。

Portability (any OS, any agent)

可移植性（支持任意操作系统、任意Agent）

Written for any Agent Skills client on macOS, Linux, or Windows:

Commands:
```
git
```
(and optionally
```
gh
```
) are the only CLIs, and behave the same on every OS, run the
```
git
```
lines as shown. Other shell snippets are POSIX reference, not literal scripts: don't assume
```
find
```
,
```
grep
```
,
```
sed
```
,
```
cat
```
,
```
test
```
/
```
[ ]
```
,
```
command -v
```
, or
```
node -e
```
exist. Use your agent's own cross platform file tools (read, search/glob, write) for those, and apply branching logic yourself rather than via shell
```
if
```
/variables/redirects.
Bundled files: referenced by paths relative to this skill's folder. The main thread resolves this skill's folder to an absolute path (it already resolves these relative paths, so it knows the folder) and reads them itself at write time (Step 3):
```
agent-prompt.md
```
and the one template for the chosen type.
No interactive question support? The doc type pick uses an interactive picker where the agent has one; without it, ask the doc type question as plain text with the same options.

为运行在macOS、Linux或Windows上的任意Agent Skills客户端编写：

命令：
```
git
```
（可选
```
gh
```
）是唯一需要的CLI工具，且在所有操作系统上行为一致，按所示运行
```
git
```
命令。其他Shell代码片段是POSIX参考示例，而非字面脚本：不要假设
```
find
```
、
```
grep
```
、
```
sed
```
、
```
cat
```
、
```
test
```
/
```
[ ]
```
、
```
command -v
```
或
```
node -e
```
存在。使用Agent自带的跨平台文件工具（读取、搜索/通配、写入）来完成这些操作，并自行处理分支逻辑，而非通过Shell的
```
if
```
/变量/重定向实现。
捆绑文件：通过相对于本技能文件夹的路径引用。主线程会将本技能文件夹解析为绝对路径（它已经能解析这些相对路径，因此知晓文件夹位置），并在写入时（步骤3）自行读取这些文件：
```
agent-prompt.md
```
和所选类型对应的模板文件。
无交互式选择支持？ 如果Agent支持交互式选择器，则用它来选择文档类型；如果不支持，则以纯文本形式询问文档类型，提供相同选项。

Execution

执行流程

1. Determine the document type

1. 确定文档类型

If passed as an argument (
```
pr
```
,
```
changelog
```
,
```
release-note
```
,
```
postmortem
```
): use it.
Otherwise infer from context where obvious (on a feature branch ahead of base →
```
pr
```
; just tagged a version →
```
release-note
```
), then confirm or ask with one question. Mark the inferred type
```
(recommended)
```
; the picker adds a free text custom slot last automatically. Present these as your agent's interactive option picker (
```
AskUserQuestion
```
on Claude Code), or as plain text options with the same choices (custom option last) if it has none:

"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

如果通过参数传入（
```
pr
```
、
```
changelog
```
、
```
release-note
```
、
```
postmortem
```
）：直接使用该参数。
否则从上下文推断明显的类型（功能分支领先于基准分支 →
```
pr
```
；刚打了版本标签 →
```
release-note
```
），然后确认或询问一个问题。将推断的类型标记为
```
(推荐)
```
；选择器会自动在最后添加一个自由文本自定义选项。如果Agent支持交互式选择器（如Claude Code的
```
AskUserQuestion
```
），则用它展示选项；如果不支持，则以纯文本形式展示相同选项（自定义选项在最后）：

"我应该撰写什么文档？"
  header: "文档类型"
  options:
    - label: "PR描述"        → pr           # 若为推断类型则标记(推荐)
    - label: "变更日志条目"      → changelog
    - label: "发布说明"        → release-note
    - label: "事后复盘"           → postmortem

2. Gather the source material

2. 收集源材料

Collect the lightweight history below, then read the diff and files yourself at write time (a

scout

subagent may do the reading for a very large diff).

Run these

git

gh

commands as shown; do the steps that are not commands with your agent's own file tools and your own branching logic.

bash

undefined

收集以下轻量级历史记录，然后在写入时自行读取diff和文件（对于超大diff，可委托

scout

子Agent读取）。

按所示运行这些

git

gh

命令；非命令步骤使用Agent自带的文件工具和自行处理分支逻辑完成。

bash

undefined

base branch: use

main

if it exists, otherwise

master

基准分支：如果存在

main

则使用，否则使用

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)

pr / changelog：分支变更集（BASE = 上述基准分支）

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).

release-note：需要标签。列出所有标签；如果没有标签，则优雅降级（视为NO_TAGS）。

git tag --sort=-creatordate


- **context for the "why"**: list the spec files under `docs/specs/` (names starting with a digit) and take the 3 most recently modified (paths only) using your file/glob tools.
- **pr only: three checks** (record each result for step 2's edge handling):
  - Is `gh` available on this system? (GH_INSTALLED)
  - Does the repo have a git remote? Run `git remote`; a result that is not empty means HAS_REMOTE.
  - Does a PR already exist? Run `gh pr view --json number -q .number`. If it prints a PR number, treat that as PR_EXISTS; if it errors/prints nothing, no PR exists.

**Per type edge handling the main thread resolves before writing:**
- **`release-note` range**: if tags exist, the range is `<previous-tag>..<latest-tag>` (or a range the engineer named). **If `NO_TAGS`**, don't guess, ask: "No version tags found. Give me a version name and range (e.g. `v1.0.0`, covering `<commit>..HEAD`), or I'll cover all commits since the first one." Pass the resolved range/version to the subagent.
- **pr + gh**: only offer to create/update the PR via `gh` when **`GH_INSTALLED` and `HAS_REMOTE`**. If `PR_EXISTS`, the action is `gh pr edit` (update the body), **not** `gh pr create`. If gh isn't usable or no remote, the PR text is chat only, don't attempt `gh`.
- **postmortem**: git won't contain the incident narrative. Ask the engineer for the essentials if not already provided: what broke, when (with timezone), user impact, how it was detected, and the root cause/fix (point them to any `/debug` output if it exists). Pass their account as the incident facts. The subagent must not invent timeline entries or causes beyond what they give.

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`。
- **postmortem**：git中不包含事件的叙述内容。如果尚未提供，请向工程师询问必要信息：故障内容、时间（含时区）、用户影响、发现方式以及根本原因/修复方案（如有`/debug`输出，请指引他们查看）。将他们提供的内容作为事件事实传递。子Agent不得编造超出给定信息的时间线条目或原因。

3. Write the document (main thread)

3. 撰写文档（主线程）

Resolve this skill's folder to an absolute path (you already resolve these relative paths, so you know the folder) and Read

agent-prompt.md

and the one template for the chosen type,

templates/<type>.md

, now (only now, at write time). Follow

agent-prompt.md

and write the document yourself. Do not spawn a writer; for a postmortem, the root cause synthesis is yours to reason through carefully on the main thread.

The inputs to apply:

Document type + its template (the chosen one only; read it)
Source: commit list, diff command, and (postmortem) the incident facts. Read the diff yourself; for a very large diff (e.g. >25 files), offload the reading to a
```
scout
```
subagent (haiku) that returns a compact summary by file group/feature, and write from that
Project context contents (project name, conventions), read
```
AGENTS.md
```
, or
```
CLAUDE.md
```
fallback, + recent spec paths for the "why"
Output target for the type and today's date

pr: the gh action,

none (chat-only)

gh pr create

gh pr edit

(from the

GH_INSTALLED

HAS_REMOTE

PR_EXISTS

checks)

changelog: match the existing
CHANGELOG.md
format if the file exists (don't impose Keep a Changelog over a different established style)
release-note
: the resolved version + range

将本技能文件夹解析为绝对路径（你已经能解析这些相对路径，因此知晓文件夹位置），并在写入时（步骤3）读取
agent-prompt.md
和所选类型对应的唯一模板文件

templates/<type>.md

。遵循

agent-prompt.md

的指引自行撰写文档。不要生成新的Writer Agent；对于事后复盘文档，根本原因的梳理需由主线程仔细完成。

需应用的输入信息：

文档类型 + 对应的模板（仅读取所选的模板）
源数据：提交列表、diff命令以及（事后复盘文档的）事件事实。自行读取diff；对于超大diff（例如超过25个文件），可将读取工作委托给
```
scout
```
子Agent（haiku），它会按文件组/功能生成简洁摘要，你再基于该摘要撰写文档
项目上下文内容（项目名称、约定），读取
```
AGENTS.md
```
，或 fallback到
```
CLAUDE.md
```
+ 最近的规格文件路径（用于说明“原因”）
对应类型的输出目标和当前日期

pr：gh操作选项，

none (仅聊天)

gh pr create

gh pr edit

（来自

GH_INSTALLED

HAS_REMOTE

PR_EXISTS

检查结果）

changelog：如果
```
CHANGELOG.md
```
已存在，匹配现有格式（不要强行套用Keep a Changelog规范到已有的不同风格上）
release-note
：解析后的版本 + 范围

4. Relay the result

4. 传递结果

undefined

undefined

/document complete

/document 完成


For `pr`, always show the full text in chat (so it's usable even without `gh`). For the file types, show a short preview and the path. This skill does not commit, push, or merge. It produces the prose.

---

<对于pr：展示可直接粘贴的标题 + 正文；如果使用了gh，则展示"PR #N已更新"> <对于其他类型：展示2-3行预览内容 + 文件路径>


对于`pr`，始终在聊天界面展示完整文本（这样即使没有`gh`也能使用）。对于文件类型，展示简短预览和路径。本技能不会执行提交、推送或合并操作，仅生成文案。

---

Reference files

参考文件

```
agent-prompt.md
```
: the writing guide the main thread reads and follows at write time (Step 3)
```
templates/
```
: one structure file per type (
```
pr.md
```
,
```
changelog.md
```
,
```
release-note.md
```
,
```
postmortem.md
```
); the main thread reads only the chosen one at write time

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

document

Original

Translation

Output style (plain words, no dashes, no hyphens)

输出风格（平实语言，不用破折号，不用连字符）

What this skill does

本技能的功能

Artifact ownership

产物归属

Portability (any OS, any agent)

可移植性（支持任意操作系统、任意Agent）

Execution

执行流程

1. Determine the document type

1. 确定文档类型

2. Gather the source material

2. 收集源材料

base branch: use
`main`
if it exists, otherwise
`master`

基准分支：如果存在
`main`
则使用，否则使用
`master`

current branch

当前分支

pr / changelog: the branch change set (BASE = the base branch above)

pr / changelog：分支变更集（BASE = 上述基准分支）

release-note: needs tags. List them; if there are none, fall back gracefully (treat as NO_TAGS).

release-note：需要标签。列出所有标签；如果没有标签，则优雅降级（视为NO_TAGS）。

3. Write the document (main thread)

3. 撰写文档（主线程）

4. Relay the result

4. 传递结果

/document complete

/document 完成

Reference files

参考文件

document

Original

Translation

Output style (plain words, no dashes, no hyphens)

输出风格（平实语言，不用破折号，不用连字符）

What this skill does

本技能的功能

Artifact ownership

产物归属

Portability (any OS, any agent)

可移植性（支持任意操作系统、任意Agent）

Execution

执行流程

1. Determine the document type

1. 确定文档类型

2. Gather the source material

2. 收集源材料

base branch: use main if it exists, otherwise master

基准分支：如果存在main则使用，否则使用master

current branch

当前分支

pr / changelog: the branch change set (BASE = the base branch above)

pr / changelog：分支变更集（BASE = 上述基准分支）

release-note: needs tags. List them; if there are none, fall back gracefully (treat as NO_TAGS).

release-note：需要标签。列出所有标签；如果没有标签，则优雅降级（视为NO_TAGS）。

3. Write the document (main thread)

3. 撰写文档（主线程）

4. Relay the result

4. 传递结果

/document complete

/document 完成

Reference files

参考文件

base branch: use
`main`
if it exists, otherwise
`master`

基准分支：如果存在
`main`
则使用，否则使用
`master`