holocron/plugins/bin/.apm/skills/research/SKILL.md

name, description, metadata, model

name	description	metadata	model
research	Use when the user wants a tool, library, or API researched from canonical documentation into structured per-topic reference markdown files. Not documentation written from existing code or specs -> `write-docs`. Not a bug or incident -> `diagnose`.	version category 1.1.0 research	sonnet

Gotchas

• Never infer the output path. A run writes a directory's worth of files, and a guessed destination scatters them through someone's source tree. If the user named no path, stop and ask.
• Write nothing outside the given output path. A file placed beside the agreed directory is one the user never asked for and will not think to look for.
• Never write an empty topic file. A stub troubleshooting.md reads downstream as researched and closed.
• Subagents read and summarise; the orchestrator writes every file. A subagent that writes has no view of the other subagents' notes, so its files collide with theirs.
• A Context7 response that is a "no results" message, a redirect notice, or header-only boilerplate is not coverage. A topic area counts as covered only when the response carries at least one substantive paragraph.

Step 1 — Scope against the working directory

Search for existing use of the topic — imports, config files, version pins, reference files already written — and narrow the research to what is missing: the version actually in use, the topics not yet documented.

The default topic areas are overview, installation, configuration, cli-reference, api-reference, examples and troubleshooting — one file each, and only where content exists. If what belongs in one of them is unclear, or the topic needs a file outside that set, read references/topics.md for the per-topic coverage table and the custom-topic naming rule.

Step 2 — Resolve against Context7

If the topic is a library, framework, or API and the user gave no starting URLs, call resolve-library-id with the topic name and the user's full question — match quality depends on the question, not the bare name — then query-docs once per default topic area. Record each response as a source with slug context7-<library-slug>, and mark which topic areas it covered — those skip the web reads at step 4.

If the library does not resolve, or the user gave starting URLs, go to step 3. Explicit URLs are a source choice; do not second-guess them with a resolution attempt.

Step 3 — Discover sources

If the user gave starting URLs, skip discovery: those URLs are the source list and go straight to step 4.

Otherwise, for every topic area Context7 did not cover, websearch for canonical documentation — llms.txt, official developer docs, and API references ahead of tutorials or blog posts. Collect three to five candidate URLs before reading any of them.

If nothing usable comes back, stop and report what was searched, then ask for starting URLs rather than settling for tutorials.

Step 4 — Read the sources

Spawn one subagent per URL, in parallel. Each fetches its page with WebFetch and returns notes by topic area plus the links worth deepening — never the raw page. The pages stay out of this context; only the notes come back.

Step 5 — Deepen

Spawn one further subagent per link worth following, again in parallel and again returning notes only. Stop a branch once its content turns repetitive or leaves the topic, and cap the whole step at roughly ten additional pages.

Step 6 — Write

Merge every set of notes, Context7 and web alike, by topic area, then write, in the output path:

• <topic>.md for each topic area that has content, default or custom. Frontmatter carries topic: (the filename without .md) and source_keys: (kebab-case slugs matching sources.md); the body is prose in ## sections, with no inline URLs.

• sources.md, always, one ## section per source — including sources that yielded nothing — with exactly these four fields:

  - **URL:** <full URL>
  - **Description:** <one-line summary>
  - **Contributing files:** <topic files this source contributed to>
  - **Status:** `extracted` | `no content extracted`
  

Spell those four field names exactly as given. The downstream provenance validator matches them literally; prose in their place parses as nothing, and the check passes having verified nothing.

Read references/file-format.md when the four fields above do not settle the case: what a slug should be, the context7-<library-slug> slug and context7:<library-id> URL convention for a Context7 source, or what belongs in a topic body versus a verbatim copy of the source.

If no topic area has content, write nothing at all, sources.md included, and report what was searched.