reliquary/plugins/g4b_ai/skills/research/SKILL.md

name, description

name	description
research	Governs how research is conducted — bounded agent spawning, no recursive sub-agents, web content downloaded as markdown and scanned locally. Use whenever launching research agents, fetching web content for analysis, or when another skill (like research-tree) is about to spawn agents that touch the web. Composes with workpad for output placement and research-tree for multi-topic structure.

Research Governance

This skill regulates how research agents behave. It does not replace research-tree (which governs the structure of multi-topic research) or workpad (which governs where output goes). It layers on top of both.

The core problem this solves

Without governance, a research agent can spawn sub-agents, which spawn more sub-agents, which each scrape entire websites. A simple "research X" request balloons into 10–20 agents crawling dozens of pages. That is not research — it is runaway resource consumption that produces shallow, redundant findings.

The rules

1. Research agents must not spawn sub-agents

Every agent dispatched for research work is a leaf agent. It does its own reading, searching, and fetching. It does not delegate to further agents.

Agent tiers

Pick the right agent for the job. All three are tool-restricted and cannot spawn sub-agents:

Agent	Model	Can write files	Web fetch cap	Use for
scout	haiku	No	2 pages	Quick fact extraction — a version number, a function signature, a config value from a web page
search	sonnet	No	3–5 pages	Code/file lookups, symbol tracing, "where is X defined", multi-file search
researcher	opus (medium effort)	Yes	5 pages	Deep topics requiring synthesis and a written report — architecture comparisons, technology evaluations, multi-source analysis

Default to scout for simple lookups. Use search when you need to trace through code. Use researcher only when the topic genuinely needs synthesis and a written document.

When spawning research agents (via the Agent tool or workflow scripts):

• Use subagent_type: "scout" for quick fact extraction from a page or file
• Use subagent_type: "search" for code/file lookups and symbol tracing
• Use subagent_type: "researcher" for complex topics that need a written report
• In workflow scripts, use agentType: 'scout', 'search', or 'researcher' accordingly

The orchestrator (you, the main agent, or the workflow script) is the only entity that decides how many agents run. Individual research agents never make that decision.

2. Web content is fetched and read, not scraped

When research requires information from the web:

• Fetch specific pages. Use WebFetch to download a specific URL. The tool returns the page content as text/markdown.
• Read the content locally. Extract what you need from the fetched content. Do not follow every link.
• Budget fetches per agent. A single research agent should fetch at most 3–5 pages. If the research genuinely needs more, that is a sign the topic should be split into multiple agents at the orchestrator level — not that one agent should crawl more.
• Never crawl. Do not write loops that follow links, do not fetch "all pages" from a documentation site, do not spider a domain.

How to fetch web content

Built-in tools (always available):

• WebFetch — fetches a URL and returns content. Works for most documentation pages, blog posts, API references.
• WebSearch — searches the web and returns results with snippets. Use to find the right URL before fetching.

MCP servers for richer web-to-markdown conversion (if configured):

• @anthropic/fetch — Anthropic's fetch MCP; similar to WebFetch but runs as an MCP server
• firecrawl — converts web pages to clean markdown; good for documentation sites
• markdownify / reader — HTML-to-markdown conversion services
• jina-reader — extracts main content from web pages as markdown
• browser-tools — browser automation for pages that require JavaScript rendering

Check what MCP servers are available with ToolSearch before falling back to raw WebFetch. If a markdown-conversion MCP is available, prefer it — the output is cleaner and easier to scan.

The pattern for web research:

1. WebSearch to find relevant URLs (1-3 searches)
2. WebFetch (or MCP equivalent) to download 1-3 most relevant pages
3. Read the downloaded content, extract findings
4. Write findings to report file

This is one agent's entire web interaction. Not ten agents each doing this.

3. The orchestrator controls breadth, agents control depth

The division of responsibility:

Concern	Who decides
How many agents to spawn	Orchestrator (you)
Which topics to research	Orchestrator, informed by research-tree
How deep to go on one topic	The individual agent
Whether to fetch a web page	The individual agent
Whether to spawn another agent	Never the individual agent
Where to write output	Workpad skill

4. Phases gate runaway growth

When using research-tree's phased approach:

• Review each phase's output before launching the next. This is not optional — it is the checkpoint where you catch redundancy, contradiction, or scope creep.
• Trim the next phase if earlier phases already answered some questions. Don't launch agents for topics that are already covered.
• Cap total agents. A typical research tree should use 3–12 agents total across all phases. If you're planning more than 15, the decomposition is too fine-grained — consolidate topics.

5. Research output goes to the workpad

Compose with the workpad skill:

• Individual agent reports → research/<dated-subfolder>/phase-N-<topic>.md
• Summary/index → research/<dated-subfolder>/index.md
• If no workpad exists, ask the user before creating one

Applying this skill

When you are about to do research — whether triggered by the user saying "research", "investigate", "look into", or by another skill like research-tree — apply these rules:

1. Plan first. List the topics and how many agents you need. Share with the user.
2. Instruct each agent. Every agent prompt must include: the specific research question, where to write output, and the constraint that it must not spawn sub-agents.
3. Use the search agent for lookups. For "find where X is defined" or "what files reference Y", use subagent_type: "search" — it is tool-restricted and cannot spawn agents by design.
4. Fetch web content through the agent, not through sub-agents. The agent doing the research fetches the pages it needs directly.
5. Review between phases. Read what came back before sending more agents.

What this skill does NOT govern

• The internal structure of a research tree (phases, dependencies) — that's research-tree
• Where files go — that's workpad
• Whether to do research at all — that's your judgment as orchestrator
• Which model to use — out of scope