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 (
) is discovered in Phase 1; it's typically
but
may have written it somewhere else.
This skill is the documentation counterpart to
.
discovers what is missing;
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
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.
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.
writes the agent doc tree to
by default (a sibling of any human-maintained
), but
can override that (e.g.
). Don't assume the path; discover it.
- Read at the repo root. Every Mimas-generated lists its docs paths in the first block (
<docs-dir>/AGENT_WORKFLOW.md
<docs-dir>/AGENTS_FEATURES.md
- If doesn't exist or doesn't reference the contract files, fall back to searching for directly (
find . -maxdepth 3 -name AGENTS_FEATURES.md
- Confirm the files this skill needs are there:
<docs-dir>/AGENTS_FEATURES.md
<docs-dir>/features/feature-template.md
- — feature index
If any are missing, tell the user this skill is designed to run after
and stop. Do not scaffold them yourself.
For the rest of this skill, treat the discovered directory as
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
(plus any subdomain
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.
Phase 2 — Decide what to document
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 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
session, prefer the candidate list that already exists in the conversation over re-asking.
- Top-level files (one per documented area, ignoring )
- Subdirectories (areas with per-service docs)
- Entries in
Filter the requested list against the inventory:
- Drop slugs that already have
<docs-dir>/features/<slug>.md
- 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
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.
Phase 3 — Dispatch one subagent per feature, in parallel
This is the whole point of the skill. Documentation per feature is independent work — one subagent can read the code for
while another reads the code for
. 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
call in the
same message (this is what makes them run in parallel). Use the
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 with the value you discovered in Phase 1 (typically
). 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
,
, and
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
file. The dispatcher updates the index after the batch returns.
Phase 4 — Update the index and report back
Once a batch completes, collect each subagent's reported one-liner and add entries to
in alphabetical order, in the form:
- [<slug>](./features/<slug>.md) — one-line description
If
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
- Which sections in the new docs are TODOs that still need human judgment
- That was updated and how many entries were added
- Any discrepancies you noticed between and the filesystem
Do not commit the changes. The user reviews before committing.
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
. 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.
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
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.