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

name, description, metadata, allowed-tools, model

name	description	metadata	allowed-tools	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.0.1 research	Grep Glob Read Write WebSearch WebFetch mcp__context7__resolve-library-id mcp__context7__query-docs	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.
• 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

WebFetch each URL in turn. No subagent tool is granted here, so the reads are serial and every fetched page lands in this context: reduce each page to notes by topic area, plus the links worth deepening, before fetching the next one.

Step 5 — Deepen

WebFetch the links worth following, still one at a time and still reducing each page to notes. Stop a branch once its content turns repetitive or leaves the topic, and cap the whole step at roughly ten additional pages — serial reads make that cap a real budget, not a formality.

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.