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.2 research	Grep Glob Read Write WebSearch WebFetch mcp__context7__resolve-library-id mcp__context7__query-docs	sonnet

Gotchas

• Never infer the output path: a guessed destination scatters a run's files through someone's source tree. If the user named no path, stop and ask.
• Write nothing outside the given output path; the user never asked for a file beside it and will not look for one.
• Never write an empty topic file: a stub reads downstream as researched and closed.
• Subagents read and summarise; the orchestrator writes every file, so writers never collide.
• A Context7 "no results" message, redirect notice, or header-only boilerplate is not coverage; a topic is covered only by a substantive paragraph.

Step 1 — Scope against the working directory

Search for existing use of the topic — imports, config, version pins, reference files already written — and research only what is missing.

The default topic areas are overview, installation, configuration, cli-reference, api-reference, examples and troubleshooting — one file each, only where content exists. If unsure what belongs in one, or a file outside that set is needed, read references/topics.md.

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, then query-docs once per default topic area. Record each response as a source with slug context7-<library-slug> and mark the topic areas it covered; those skip step 4.

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

Step 3 — Discover sources

If the user gave starting URLs, skip discovery: they are the source list, so go to step 4.

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

If nothing usable comes back, report what was searched and 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 links worth deepening, never the raw page. Only notes come back here. If no spawn tool is available, read serially instead, reducing each page to notes before fetching the next.

Step 5 — Deepen

Spawn one more subagent per link worth following, in parallel, returning notes only. Stop a branch once it turns repetitive or leaves the topic; cap the step at roughly ten additional pages.

Step 6 — Write

Merge all notes, Context7 and web, by topic area, then write in the output path:

• <topic>.md for each topic area with content, default or custom. Frontmatter carries topic: (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: the provenance validator matches them literally, and prose in their place parses as nothing, so the check passes having verified nothing.

Read references/file-format.md when the four fields do not settle the case: slug form, the context7-<library-slug> / context7:<library-id> convention, or what belongs in a topic body versus a verbatim copy.

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