✨ Add research agents and governance skill to g4b_ai

Three tool-restricted agents (scout/search/researcher) that cannot spawn sub-agents, plus a research skill that prevents recursive agent chains and caps web fetching.
2026-06-25 01:42:00 +02:00
parent 293fcffea3
commit 8545738a05
8 changed files with 263 additions and 4 deletions
@@ -0,0 +1,119 @@
+---
+name: research
+description: 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