document-features

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

document-features

Write feature documentation for the repository — one populated

<docs-dir>/features/<slug>.md

per requested feature — by dispatching subagents in parallel so an "all" run does not serialize. The agent docs directory (

<docs-dir>

) is discovered in Phase 1; it's typically

agents-docs/

but

setup-agentic-repository

may have written it somewhere else.

This skill is the documentation counterpart to

find-features

find-features

discovers what is missing;

document-features

is the focused worker that actually fills the template, in parallel, for the features the user names.

If the user asks "find and document everything", you can start with

find-features

to build the candidate list, then hand that list to this skill. If the user already knows which features they want (e.g. "document auth and billing"), come straight here.

为仓库撰写功能文档——每个指定功能对应一个已填充内容的

<docs-dir>/features/<slug>.md

文件——通过并行调度子代理，避免“全量生成”时的串行执行问题。代理文档目录（

<docs-dir>

）会在阶段1中自动识别；默认路径通常为

agents-docs/

，但

setup-agentic-repository

也可能将其配置在其他位置。

此技能是

find-features

的文档撰写配套功能。

find-features

负责发现缺失的文档，而

document-features

则是专注的执行器，会并行为用户指定的功能填充模板内容。

如果用户要求“查找并记录所有内容”，你可以先调用

find-features

生成候选列表，再将该列表传入此技能。如果用户已经明确知道需要记录的功能（例如“记录认证和计费功能”），则可直接使用此技能。

Phase 1 — Verify prerequisites and locate the docs directory

阶段1——验证先决条件并定位文档目录

Confirm the repo has been initialized with the Mimas template, and discover where its agent docs actually live.

setup-agentic-repository

writes the agent doc tree to agents-docs/
by default (a sibling of any human-maintained

docs/

), but

--docs-dir <dir>

can override that (e.g.

docs/agents

). Don't assume the path; discover it.

Read
```
AGENTS.md
```
at the repo root. Every Mimas-generated
```
AGENTS.md
```
lists its docs paths in the first block (
```
<docs-dir>/AGENT_WORKFLOW.md
```
,
```
<docs-dir>/AGENTS_FEATURES.md
```
, etc.) — the directory in those paths is the docs dir for this repo.
If
```
AGENTS.md
```
doesn't exist or doesn't reference the contract files, fall back to searching for
```
AGENTS_FEATURES.md
```
directly (
```
find . -maxdepth 3 -name AGENTS_FEATURES.md
```
). The directory containing it is the docs dir.
Confirm the files this skill needs are there:
- ```
<docs-dir>/AGENTS_FEATURES.md
```
  — feature documentation contract
- ```
<docs-dir>/features/feature-template.md
```
  — canonical template
- ```
<docs-dir>/FEATURES.md
```
  — feature index

If any are missing, tell the user this skill is designed to run after

setup-agentic-repository

and stop. Do not scaffold them yourself.

For the rest of this skill, treat the discovered directory as

<docs-dir>

and use it wherever paths appear. Critical: the subagent prompt in Phase 3 is a template — substitute the actual discovered value into it before dispatching each subagent. The subagents do not run this Phase 1 themselves and will not discover the dir on their own.

Read

<docs-dir>/AGENTS_FEATURES.md

and the root

AGENTS.md

(plus any subdomain

CONTEXT.md

files) so you know the contract — what counts as an area-level doc vs. a per-service doc, and which subdomains exist. These files are authoritative; if anything in this skill drifts from them, the files win.

确认仓库已使用Mimas模板初始化，并找到其代理文档的实际存储位置。

setup-agentic-repository

默认会将代理文档树写入**

agents-docs/

**（与人工维护的

docs/

目录同级），但可通过

--docs-dir <dir>

参数覆盖默认路径（例如

docs/agents

）。请勿假设路径，需自动识别。

读取仓库根目录下的
```
AGENTS.md
```
文件。所有Mimas生成的
```
AGENTS.md
```
都会在首个代码块中列出文档路径（
```
<docs-dir>/AGENT_WORKFLOW.md
```
、
```
<docs-dir>/AGENTS_FEATURES.md
```
等）——这些路径中的目录即为当前仓库的文档目录。
如果
```
AGENTS.md
```
不存在或未引用约定文件，则直接搜索
```
AGENTS_FEATURES.md
```
文件（执行命令
```
find . -maxdepth 3 -name AGENTS_FEATURES.md
```
），包含该文件的目录即为文档目录。
确认此技能所需的文件已存在：
- ```
<docs-dir>/AGENTS_FEATURES.md
```
  ——功能文档约定规则
- ```
<docs-dir>/features/feature-template.md
```
  ——标准模板
- ```
<docs-dir>/FEATURES.md
```
  ——功能索引

如果上述任一文件缺失，请告知用户此技能需在

setup-agentic-repository

执行后使用，并终止操作。请勿自行搭建这些文件。

在后续操作中，将识别到的目录视为

<docs-dir>

，所有路径均以此为基准。重点注意：阶段3中的子代理提示是模板内容——在调度每个子代理前，需将其中的

<docs-dir>

替换为实际识别到的路径。子代理不会自行执行阶段1的操作，也无法自动识别文档目录。

读取

<docs-dir>/AGENTS_FEATURES.md

和根目录下的

AGENTS.md

（以及所有子域的

CONTEXT.md

文件），明确约定规则——区分区域级文档与服务级文档的标准，以及当前存在哪些子域。这些文件具有权威性，如果此技能的说明与这些文件内容冲突，以文件内容为准。

Phase 2 — Decide what to document

阶段2——确定需要记录的功能

The user's request usually contains the answer. Parse what they said:

Named features ("document auth and billing", "write up the search feature") → take that list of slugs
A number ("document 3 features", "write up the top 5") → take a numeric count of the most significant undocumented features
"all" / "every" / "everything" → every undocumented feature with meaningful implementation
Ambiguous or empty → use
```
AskUserQuestion
```
with the same options find-features uses (Top 5 / All / Number / Specific names) plus an "Other" free-text fallback

If the user is continuing from a recent

find-features

session, prefer the candidate list that already exists in the conversation over re-asking.

Then quickly inventory

<docs-dir>/features/

Top-level
```
.md
```
files (one per documented area, ignoring
```
feature-template.md
```
)
Subdirectories (areas with per-service docs)
Entries in
```
<docs-dir>/FEATURES.md
```

Filter the requested list against the inventory:

Drop slugs that already have
```
<docs-dir>/features/<slug>.md
```
. Tell the user which ones you skipped and why
For named features that you cannot locate in the codebase, surface them and ask whether to skip or scaffold a TODO doc. Do not invent feature areas

If the user asked for a number or "all" and you need to identify candidates yourself, scan the subdomains declared in

AGENTS.md

looking for named concepts with dedicated logic — dedicated service layer, non-trivial handler, dedicated tables/migrations, multiple endpoints, real business rules. A single empty route stub is not enough. Rank by significance and trim to the requested count.

用户的请求通常会明确说明需记录的内容。解析用户的请求：

指定功能（例如“记录认证和计费功能”、“撰写搜索功能文档”）→ 直接使用该功能slug列表
指定数量（例如“记录3个功能”、“撰写前5个重要功能”）→ 选取对应数量的最关键未记录功能
“全部”/“所有” → 记录所有具备有效实现的未记录功能
模糊或无明确要求 → 使用
```
AskUserQuestion
```
工具，提供与
```
find-features
```
相同的选项（前5个/全部/指定数量/特定名称），并添加“其他”自由文本选项

如果用户是从最近的

find-features

会话继续操作，优先使用对话中已有的候选列表，而非重新询问用户。

随后快速盘点

<docs-dir>/features/

顶级
```
.md
```
文件（每个文件对应一个已记录的功能区域，忽略
```
feature-template.md
```
）
子目录（包含服务级文档的功能区域）
```
<docs-dir>/FEATURES.md
```
中的条目

将用户请求的列表与盘点结果进行过滤：

移除已存在
```
<docs-dir>/features/<slug>.md
```
文件的slug，并告知用户跳过的内容及原因
对于在代码库中无法定位的指定功能，告知用户并询问是否跳过或搭建一个待办文档。请勿凭空创建功能区域

如果用户要求记录指定数量或“全部”功能，且需要自行识别候选功能，请扫描

AGENTS.md

中声明的子域，寻找具备专属逻辑的命名概念——例如专属服务层、非 trivial 处理器、专属表/迁移文件、多个端点、实际业务规则。仅包含空路由桩的功能不足以成为候选。按重要性排序并截取到指定数量。

Phase 3 — Dispatch one subagent per feature, in parallel

阶段3——并行调度每个功能对应的子代理

This is the whole point of the skill. Documentation per feature is independent work — one subagent can read the code for

auth

while another reads the code for

billing

. Serializing them throws away the parallelism the harness gives you.

Cap concurrency at 10 subagents. If the final list has more than 10 features, dispatch the first batch of 10 in one message, wait for it to complete, then dispatch the next batch. Do not exceed 10 concurrent agents — it overwhelms tooling and the user's review can't keep up.

For each feature in the current batch, spawn one

Agent

call in the same message (this is what makes them run in parallel). Use the

general-purpose

subagent unless something more specific fits.

Each subagent gets a self-contained prompt — it has not seen this conversation, so include everything it needs. Before dispatching, substitute
<docs-dir>
with the value you discovered in Phase 1 (typically

agents-docs

). The subagents do not discover the dir on their own.

You are documenting a single feature area for this repository. The output is one populated markdown file at `<docs-dir>/features/<slug>.md` that follows the project's feature documentation contract.

Feature slug: <slug>
One-line concept (from discovery, may be rough): <concept>

Authoritative reading order (read these first, in order):
1. `<docs-dir>/AGENTS_FEATURES.md` — the contract that governs how feature docs are written
2. `<docs-dir>/features/feature-template.md` — the canonical template. Mirror its section order and headings; do not invent your own structure
3. `AGENTS.md` and any subdomain `CONTEXT.md` files — for vocabulary and where the code lives

Your task:
- Locate this feature in the codebase. Confirm it has meaningful implementation (service layer, handler, endpoints, tables, real business rules). If it is only a stub, stop and report that back — do not write a doc for a stub
- Create `<docs-dir>/features/<slug>.md` from the template
- Fill in what you can verify from the code: overview, responsibilities, key concepts, endpoint(s), service/handler/repository paths, key types, tests location, related features
- Set `Area:` to the slug, `Status:` to `Active` for production code or `In Progress` for half-built features, and `Last updated:` to today's date in `YYYY-MM-DD`
- For sections you cannot confidently fill (performance, security review, undocumented edge cases), keep the template's prompt and add a clear `TODO:` marker. Honest gaps beat invented content
- If the feature has multiple distinct services or endpoints worth separating, also create `<docs-dir>/features/<slug>/<service>.md` files from the same template and link them from the area doc — but only when complexity actually warrants it. Do not duplicate large sections between area and per-service docs
- Do not edit `<docs-dir>/FEATURES.md` — the dispatcher will update the index once all features are written, to avoid concurrent edits to the same file
- Do not commit anything

Report back when done with:
- Path(s) of the file(s) you created
- One-line description of the feature (this will be used for the FEATURES.md entry)
- Which template sections you left as TODO
- Anything you noticed that needs human judgment

Substitute

<slug>

<concept>

, and

<docs-dir>

per feature. Keep the rest verbatim — the subagent depends on having the contract in its own context.

If features turn out to be unrelated to one another (different subdomains, different layers), there's no need to coordinate beyond avoiding the shared

<docs-dir>/FEATURES.md

file. The dispatcher updates the index after the batch returns.

这是此技能的核心价值。每个功能的文档撰写是独立工作——一个子代理可以读取

auth

功能的代码，同时另一个子代理读取

billing

功能的代码。串行执行会浪费框架提供的并行能力。

并发上限为10个子代理。如果最终列表包含超过10个功能，先调度首批10个功能的子代理（在同一条消息中发送），等待执行完成后，再调度下一批。请勿超过10个并发代理——这会导致工具过载，且用户无法及时完成审核。

对于当前批次中的每个功能，在同一条消息中生成一个

Agent

调用（这是实现并行执行的关键）。除非有更合适的专用子代理，否则使用

general-purpose

子代理。

每个子代理都会收到一个独立的提示——它无法查看当前对话内容，因此需包含其所需的全部信息。调度前，请将提示中的
<docs-dir>
替换为阶段1中识别到的路径（通常为

agents-docs

）。子代理无法自行识别文档目录。

You are documenting a single feature area for this repository. The output is one populated markdown file at `<docs-dir>/features/<slug>.md` that follows the project's feature documentation contract.

Feature slug: <slug>
One-line concept (from discovery, may be rough): <concept>

Authoritative reading order (read these first, in order):
1. `<docs-dir>/AGENTS_FEATURES.md` — the contract that governs how feature docs are written
2. `<docs-dir>/features/feature-template.md` — the canonical template. Mirror its section order and headings; do not invent your own structure
3. `AGENTS.md` and any subdomain `CONTEXT.md` files — for vocabulary and where the code lives

Your task:
- Locate this feature in the codebase. Confirm it has meaningful implementation (service layer, handler, endpoints, tables, real business rules). If it is only a stub, stop and report that back — do not write a doc for a stub
- Create `<docs-dir>/features/<slug>.md` from the template
- Fill in what you can verify from the code: overview, responsibilities, key concepts, endpoint(s), service/handler/repository paths, key types, tests location, related features
- Set `Area:` to the slug, `Status:` to `Active` for production code or `In Progress` for half-built features, and `Last updated:` to today's date in `YYYY-MM-DD`
- For sections you cannot confidently fill (performance, security review, undocumented edge cases), keep the template's prompt and add a clear `TODO:` marker. Honest gaps beat invented content
- If the feature has multiple distinct services or endpoints worth separating, also create `<docs-dir>/features/<slug>/<service>.md` files from the same template and link them from the area doc — but only when complexity actually warrants it. Do not duplicate large sections between area and per-service docs
- Do not edit `<docs-dir>/FEATURES.md` — the dispatcher will update the index once all features are written, to avoid concurrent edits to the same file
- Do not commit anything

Report back when done with:
- Path(s) of the file(s) you created
- One-line description of the feature (this will be used for the FEATURES.md entry)
- Which template sections you left as TODO
- Anything you noticed that needs human judgment

根据每个功能替换

<slug>

、

<concept>

和

<docs-dir>

的值。其余内容保持原样——子代理依赖这些约定内容完成工作。

如果功能之间互不相关（属于不同子域、不同层级），除了避免同时编辑共享的

<docs-dir>/FEATURES.md

文件外，无需进行其他协调。调度器会在批次执行完成后更新索引。

Phase 4 — Update the index and report back

阶段4——更新索引并反馈结果

Once a batch completes, collect each subagent's reported one-liner and add entries to

<docs-dir>/FEATURES.md

in alphabetical order, in the form:

- [<slug>](./features/<slug>.md) — one-line description

<docs-dir>/FEATURES.md

still contains the placeholder

_No feature areas documented yet. Add entries as you build out the system._

, remove that line as you add the first real entry.

Then, if more features remain (because the original list was >10), dispatch the next batch of up to 10 and repeat.

When everything is written, tell the user:

Which feature docs were created (full paths), grouped by batch if there were multiple
Which requested features were skipped, and why ("already documented at
```
<docs-dir>/features/<slug>.md
```
", "could not locate in codebase", "implementation too thin to earn an entry yet")
Which sections in the new docs are TODOs that still need human judgment
That
```
<docs-dir>/FEATURES.md
```
was updated and how many entries were added
Any discrepancies you noticed between
```
<docs-dir>/FEATURES.md
```
and the filesystem

Do not commit the changes. The user reviews before committing.

批次执行完成后，收集每个子代理返回的单行描述，并按字母顺序添加到

<docs-dir>/FEATURES.md

中，格式如下：

- [<slug>](./features/<slug>.md) — one-line description

如果

<docs-dir>/FEATURES.md

中仍包含占位符

_No feature areas documented yet. Add entries as you build out the system._

，在添加第一条真实条目时删除该占位符。

如果还有剩余功能（原列表超过10个），则调度下一批最多10个功能的子代理，重复上述流程。

所有文档撰写完成后，告知用户：

创建的功能文档路径（完整路径），如果分多批次则按批次分组展示
跳过的请求功能及原因（例如“已在
```
<docs-dir>/features/<slug>.md
```
中记录”、“在代码库中无法定位”、“实现过于简单，暂无需单独文档”）
新文档中仍为TODO、需要人工补充的章节
```
<docs-dir>/FEATURES.md
```
已更新，以及新增的条目数量
发现的
```
<docs-dir>/FEATURES.md
```
与文件系统之间的不一致情况

请勿提交更改。需等待用户审核后再提交。

Why this is structured around subagents

为何基于子代理构建此技能

Documenting one feature is read-heavy and largely independent of documenting another — different files, different services, different endpoints. The slow part is the reading, and parallelizing the reading is the entire reason this skill exists separately from

find-features

. Spawning ten subagents in one message and letting them work concurrently turns a 10-minute sequential run into something closer to a 1–2 minute parallel one, with each subagent producing a focused, faithful doc because its whole context is one feature.

The 10-agent cap is pragmatic, not theoretical: more than that and you risk rate limits, output you can't usefully review at once, and the dispatcher running out of room to track which agent owns which slug. Two batches of ten is fine; ten batches of one is the failure mode this skill is designed to avoid.

单个功能的文档撰写需要大量代码阅读工作，且与其他功能的文档撰写工作基本独立——涉及不同文件、不同服务、不同端点。最耗时的部分是代码阅读，而并行化代码阅读正是此技能独立于

find-features

存在的核心原因。在一条消息中生成10个子代理并让它们并行工作，可将原本10分钟的串行执行时间缩短至1-2分钟左右，且每个子代理仅专注于一个功能，能生成更精准、符合要求的文档。

10个代理的并发上限是务实的选择，而非理论限制：超过此数量可能会触发速率限制，导致用户无法有效审核输出内容，且调度器可能无法跟踪每个代理对应的slug。分两批各10个代理是可行的；而分10批各1个代理则是此技能要避免的失败模式。

What makes a good output

优质输出的标准

Faithful to the code. Endpoint paths, file locations, method names, table names must match what is actually in the repo. If a subagent can't find something, the right move is a

TODO:

marker, not a guess.

Concept-first for area docs. The area-level doc explains what the feature is for — responsibilities, boundaries, vocabulary. Deep implementation detail belongs in per-service docs once they exist.

Honest about gaps. A clear

TODO: describe rate limiting

is more useful than a fabricated rate limit policy. Future sessions can fill these in from real information.

Proportionate. A small CRUD endpoint with one handler does not need every section of the template. Trim or skip sections that genuinely do not apply. The template is a checklist of what might be relevant, not a contract that every section must be populated.

Honors the contract. The structure, headings, and rules in

<docs-dir>/AGENTS_FEATURES.md

and

<docs-dir>/features/feature-template.md

win every time. If this skill's instructions ever drift from those files, the files are authoritative — they live with the project and are what other agents read.

忠实于代码。端点路径、文件位置、方法名称、表名必须与仓库中的实际内容一致。如果子代理无法找到相关内容，正确的做法是添加

TODO:

标记，而非猜测内容。

区域文档以概念为先。区域级文档需解释功能的用途——职责、边界、术语。深层实现细节应放在服务级文档中（当服务级文档存在时）。

坦诚说明空白。清晰的

TODO: 描述限流规则

比虚构的限流策略更有用。后续会话可根据真实信息补充这些内容。

比例适当。仅包含一个处理器的小型CRUD端点无需填充模板的所有章节。可删减或跳过完全不适用的章节。模板是可能相关内容的检查清单，而非要求必须填充所有章节的强制约定。

遵守约定规则。

<docs-dir>/AGENTS_FEATURES.md

和

<docs-dir>/features/feature-template.md

中的结构、标题和规则具有最高权威性。如果此技能的说明与这些文件内容冲突，以文件内容为准——这些文件随项目一起维护，是其他代理会读取的依据。