find-features

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

find-features

Discover feature areas in this repository that are missing from

<docs-dir>/features/

, then create a populated markdown file for each one — following the contract in

<docs-dir>/AGENTS_FEATURES.md

and the template at

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

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

The Mimas template (

setup-agentic-repository

) scaffolds an empty

<docs-dir>/features/

tree. This skill is the next step — it fills it in.

发现当前仓库中未在

<docs-dir>/features/

目录下记录的功能模块，然后为每个模块生成一份完整的Markdown文档——需遵循

<docs-dir>/AGENTS_FEATURES.md

中的约定以及

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

中的模板。Agent文档目录（

<docs-dir>

）会在第一阶段确定——通常为

agents-docs/

，但

setup-agentic-repository

也可能将其部署在其他位置。

Mimas模板（

setup-agentic-repository

）会搭建一个空的

<docs-dir>/features/

目录结构。本Skill是后续步骤——负责填充该目录。

Phase 1 — Verify prerequisites and locate the docs directory

第一阶段——验证前置条件并定位文档目录

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
```
  — the canonical template
- ```
<docs-dir>/FEATURES.md
```
  — the feature index

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

setup-agentic-repository

and stop. Don't try to scaffold them yourself — that is the other skill's job.

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

<docs-dir>

and use it wherever paths appear. Don't hardcode

docs/

agents-docs/

in your reasoning, prompts, or report.

Read

<docs-dir>/AGENTS_FEATURES.md

and the root

AGENTS.md

(plus any subdomain

CONTEXT.md

files) so you know:

what counts as a feature area — a named concept with dedicated logic in the codebase, identified by naming and behavior, not folder structure alone

the split between area-level docs (

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

) and per-service docs (

<docs-dir>/features/<area>/<service>.md

)

which subdomains exist and where their code lives

These files define the contract you must satisfy. The whole point of the skill is to produce docs that look like a senior engineer on this project wrote them, following the rules already agreed in

AGENTS_FEATURES.md

确认仓库已通过Mimas模板初始化，并确定其Agent文档的实际存储位置。

setup-agentic-repository

默认会将Agent文档树写入**

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
```
）。包含该文件的目录即为文档目录。
确认本Skill所需的文件是否存在：
- ```
<docs-dir>/AGENTS_FEATURES.md
```
  ——功能文档约定文件
- ```
<docs-dir>/features/feature-template.md
```
  ——标准模板
- ```
<docs-dir>/FEATURES.md
```
  ——功能索引文件

如果上述任一文件缺失，请告知用户本Skill需在

setup-agentic-repository

之后运行，并停止操作。请勿尝试自行搭建这些文件——这是另一个Skill的职责。

在本Skill的后续操作中，将已发现的目录视为

<docs-dir>

，所有路径均使用该目录。请勿在推理、提示或报告中硬编码

docs/

或

agents-docs/

。

读取

<docs-dir>/AGENTS_FEATURES.md

和根目录下的

AGENTS.md

（以及所有子域的

CONTEXT.md

文件），明确以下内容：

什么是功能模块——代码库中具有独立逻辑的命名概念，通过命名和行为识别，而非仅依赖文件夹结构

模块级文档（

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

）与服务级文档（

<docs-dir>/features/<area>/<service>.md

）的划分

存在哪些子域及其代码存储位置

这些文件定义了必须遵守的约定。本Skill的核心目标是生成符合

AGENTS_FEATURES.md

中既定规则、看起来像是项目资深工程师编写的文档。

Phase 2 — Inventory what is already documented

第二阶段——盘点已文档化的内容

List

<docs-dir>/features/

and capture, before asking the user anything:

Top-level
```
.md
```
files (one per documented area) — ignore
```
feature-template.md
```
, it is the template
Subdirectories under
```
<docs-dir>/features/
```
(areas with per-service docs)
The entries listed in
```
<docs-dir>/FEATURES.md
```

You will use this list to filter out features that already have an area doc. Discrepancies between the filesystem and

<docs-dir>/FEATURES.md

are worth flagging in your final report, but don't block on them.

列出

<docs-dir>/features/

目录下的内容，并在询问用户前记录以下信息：

顶级
```
.md
```
文件（每个文件对应一个已文档化的模块）——忽略
```
feature-template.md
```
，它是模板文件
```
<docs-dir>/features/
```
下的子目录（包含服务级文档的模块）
```
<docs-dir>/FEATURES.md
```
中列出的条目

你将使用此列表过滤掉已拥有模块级文档的功能。文件系统与

<docs-dir>/FEATURES.md

之间的差异需在最终报告中指出，但无需因此暂停操作。

Phase 3 — Ask the user what to discover

第三阶段——询问用户需发现的内容

Use

AskUserQuestion

to ask how many features (or which ones) to discover. Phrase the question so it accepts a number, "all", or a free-text list of names. The tool always offers an "Other" free-text fallback, so give a few sensible presets and let the user type a specific answer when none fit.

questions:
  - question: "How many features would you like to discover, or which ones specifically?"
    header: "Scope"
    multiSelect: false
    options:
      - label: "Top 5 (Recommended)"
        description: "Discover up to 5 of the most significant undocumented feature areas."
      - label: "All"
        description: "Find every undocumented feature area in the codebase."
      - label: "A specific number (1–10)"
        description: "I'll tell you a number from 1 to 10."
      - label: "Specific names"
        description: "I'll list the feature names I want documented (e.g. 'auth, billing, search')."

Parse whatever they answer with — accept a bare number, the word "all" (any case), or a comma- or space-separated list. Phrases like "find feature x, y, z" or "auth and billing" should yield

["x", "y", "z"]

and

["auth", "billing"]

respectively. Don't be strict about format; pull out the names.

If the user names features you can't locate in the codebase, surface that and ask whether to skip them or create scaffolded TODO docs for them. Do not silently invent them.

使用

AskUserQuestion

询问用户需要发现多少个功能（或具体哪些功能）。问题表述需支持数字、"all"（全部）或自由文本形式的名称列表。工具始终提供“其他”自由文本选项，因此可给出几个合理预设，让用户在无合适选项时输入特定答案。

questions:
  - question: "How many features would you like to discover, or which ones specifically?"
    header: "Scope"
    multiSelect: false
    options:
      - label: "Top 5 (Recommended)"
        description: "Discover up to 5 of the most significant undocumented feature areas."
      - label: "All"
        description: "Find every undocumented feature area in the codebase."
      - label: "A specific number (1–10)"
        description: "I'll tell you a number from 1 to 10."
      - label: "Specific names"
        description: "I'll list the feature names I want documented (e.g. 'auth, billing, search')."

解析用户的任何回答——接受纯数字、单词"all"（任意大小写）或逗号/空格分隔的列表。类似"find feature x, y, z"或"auth and billing"的表述应分别转换为

["x", "y", "z"]

和

["auth", "billing"]

。无需严格限制格式，提取名称即可。

如果用户指定的功能在代码库中无法找到，请告知用户并询问是否跳过这些功能或为其搭建待办文档框架。请勿凭空创建不存在的功能。

Phase 4 — Discover undocumented feature areas

第四阶段——发现未文档化的功能模块

Scan the codebase for feature areas using the definition from

<docs-dir>/AGENTS_FEATURES.md

. Start from the subdomains declared in the root

AGENTS.md

— if there are several large subdomains, launch one subagent per subdomain in parallel so discovery doesn't serialize.

For each candidate feature, capture:

Slug — kebab-case, ideally matching how the area is referenced in code or routes (e.g.
```
auth
```
,
```
billing
```
,
```
recruitment-content
```
)
One-sentence concept — what the feature does, in user-facing terms
Where the code lives — routes, services, handlers, components, modules
Significance signal — at least one of: dedicated service layer, non-trivial handler, dedicated DB tables/migrations, multiple endpoints, real business rules. A single empty route stub is not enough
Whether it is already documented — does
```
<docs-dir>/features/<slug>.md
```
exist already?

Then filter:

Drop anything that already has an area-level doc
Drop stubs and scaffolding —
```
<docs-dir>/AGENTS_FEATURES.md
```
says an entry must have meaningful implementation. Err on the side of leaving thin features out and noting them as "not yet earning an entry"

Rank what is left by significance (surface area, number of endpoints, depth of business logic), then trim to what the user asked for:

Number → take the top N from the ranked list
"all" → take everything that survived the filter
Named features → take only those, matched by slug or close fuzzy match, warning about any that didn't match

根据

<docs-dir>/AGENTS_FEATURES.md

中的定义扫描代码库，寻找功能模块。从根目录

AGENTS.md

中声明的子域开始——如果存在多个大型子域，为每个子域并行启动一个子Agent，避免发现过程串行执行。

对于每个候选功能，记录以下信息：

Slug——短横线命名格式，最好与代码或路由中引用该模块的方式一致（例如
```
auth
```
、
```
billing
```
、
```
recruitment-content
```
）
一句话概念描述——该功能的用户侧用途
代码位置——路由、服务、处理器、组件、模块
重要性标识——至少满足以下一项：独立服务层、非简单处理器、独立数据库表/迁移、多个端点、实际业务规则。仅一个空路由桩不足以满足要求
是否已文档化——
```
<docs-dir>/features/<slug>.md
```
是否已存在

然后进行过滤：

移除已拥有模块级文档的功能
移除桩代码和脚手架——
```
<docs-dir>/AGENTS_FEATURES.md
```
规定条目必须包含有意义的实现。尽量排除功能薄弱的模块，并标注为“暂未达到文档标准”

根据重要性（覆盖范围、端点数量、业务逻辑深度）对剩余功能进行排序，然后根据用户的要求筛选：

数字——从排序列表中选取前N个
"all"——保留所有通过过滤的功能
指定名称——仅保留匹配的功能（通过slug或模糊匹配），并对未匹配到的功能发出警告

Phase 5 — Create the feature docs

第五阶段——生成功能文档

For each chosen feature:

Read
```
<docs-dir>/features/feature-template.md
```
once and use it as the structural template — section order, headings, prompts. Do not invent your own structure.
Create
```
<docs-dir>/features/<slug>.md
```
populated from the template:
- Fill in what you can verify from the code: overview, responsibilities, key concepts, API 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 characteristics, security review, edge cases nobody has documented), keep the template's prompt and add a clear TODO marker. Leaving an honest gap is better than inventing content
If the feature has multiple distinct services or endpoints worth separating, also create
```
<docs-dir>/features/<slug>/
```
and seed per-service docs (
```
<docs-dir>/features/<slug>/<service>.md
```
) from the same template, then link them from the area doc. Only do this when complexity actually warrants it — the contract says don't duplicate large sections between area and per-service docs

After writing each file, add an entry 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.

对于每个选中的功能：

读取一次
```
<docs-dir>/features/feature-template.md
```
，并将其作为结构模板——包括章节顺序、标题、提示内容。请勿自行创建结构。
基于模板创建
```
<docs-dir>/features/<slug>.md
```
文件：
- 填充可从代码中验证的内容：概述、职责、核心概念、API端点、服务/处理器/仓库路径、核心类型、测试位置、相关功能
- 将**
```
Area:
```
  设置为slug，
```
Status:
```
  设置为
  Active
  （生产代码）或
  In Progress
  （开发中功能），
```
Last updated:
```
  **设置为当前日期，格式为
```
YYYY-MM-DD
```
- 对于无法准确填充的章节（性能特征、安全审查、未记录的边缘情况），保留模板中的提示内容并添加清晰的TODO标记。如实留白比编造内容更有价值
如果该功能包含多个需拆分的独立服务或端点，还需创建
```
<docs-dir>/features/<slug>/
```
目录，并基于同一模板生成服务级文档（
```
<docs-dir>/features/<slug>/<service>.md
```
），然后在模块级文档中添加链接。仅当复杂度确实需要时才执行此操作——约定要求避免在模块级和服务级文档之间重复大段内容

完成每个文件的编写后，在

<docs-dir>/FEATURES.md

中按字母顺序添加条目，格式如下：

- [<slug>](./features/<slug>.md) — 一句话描述

如果

<docs-dir>/FEATURES.md

仍包含占位符

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

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

Phase 6 — Report back

第六阶段——反馈结果

Tell the user:

Which feature docs were created (full paths)
Which candidates were considered but rejected, and why ("too thin to earn an entry yet", "matches existing doc <name>", etc.)
Which sections in the new docs are TODOs that still need human judgment (performance, security, business rules, error scenarios)
Whether
```
<docs-dir>/FEATURES.md
```
was updated, and any discrepancies you noticed between it and the filesystem

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

告知用户：

已创建的功能文档的完整路径
被考虑但最终被拒绝的候选功能及其原因（例如“暂未达到文档标准”、“与现有文档<name>重复”等）
新文档中仍需人工判断的TODO章节（性能、安全、业务规则、错误场景）
是否更新了
```
<docs-dir>/FEATURES.md
```
，以及发现的文件系统与该文件之间的差异

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

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 you cannot find something, leave the template prompt in place with a TODO — do not guess.

Concept-first for area docs. The area-level doc explains what the feature is for — responsibilities, boundaries, vocabulary. 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 (no auth, no caching, no migrations, no feature flags). 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: describe rate limiting

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

比例适当。仅包含一个处理器的小型CRUD端点无需填充模板的所有章节。可删减或跳过与实际情况无关的章节（无认证、无缓存、无迁移、无功能标志）。模板是一个可能相关内容的清单，而非要求必须填充每个章节的强制约定。

遵循约定。

<docs-dir>/AGENTS_FEATURES.md

和

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

中的结构、标题和规则始终具有最高优先级。如果本Skill的说明与这些文件存在冲突，以文件内容为准——这些文件随项目一同维护，是其他Agent读取的依据。