/web-research — Library Skill: Web Research

Reusable web research module. Called from other agents via the Skill tool.

How It Is Invoked

Skill tool: web-research
Input: {
  topic: "<topic to research>",
  urls?: ["url1", "url2"],          // direct source list (optional)
  keywords?: ["k1", "k2"],          // search queries (optional)
  depth: "shallow" | "medium" | "deep",  // 3 / 5 / 7 sources
  output_format: "summary" | "report" | "structured"
}

Flow

1. Source Collection

• If urls is provided → WebFetch each URL
• If keywords is provided → find URLs by keyword via a user-provided search service (MCP, if available)
• If neither → return to the user: "topic + urls/keywords required"

2. Validation per Source

Check	Rule
Scheme	http(s) only
robots.txt	the WebFetch tool does its own check
Rate limit	≥1 sec between consecutive calls to the same domain
Content-Type	text/* + application/json
Size	Max 1MB / source
Token	Max 15K / source, 50K total

Failed source → skip + WARN in the report.

3. Synthesis

Extract from each source:

• Title + URL + access date (attribution)
• 3-5 key points
• 1-2 quotes (if any)

Synthesis prompt (LLM):

• Extract common themes
• Flag conflicting information
• Preserve source attribution (a [URL] next to each claim)

4. Output

Per the output_format selection:

summary (200-400 words):

## <topic> — Web Research Summary
<2-3 paragraph synthesis>

### Sources
- [Title 1](url1) (accessed: <date>)
- ...

report (full markdown report):

# <topic> — Web Research Report

> Generated: <ISO> · Sources: <N>

## Executive Summary
<3-5 bullets>

## Detailed Findings
### Theme 1
<synthesis + attributions>
...

## References
<full URL list with metadata>

structured (JSON):

{
  "topic": "...",
  "sources": [
    { "url": "...", "title": "...", "key_points": [...], "accessed_at": "..." }
  ],
  "themes": [
    { "name": "...", "supporting_sources": [...], "summary": "..." }
  ],
  "contradictions": [...],
  "confidence": "high|medium|low"
}

Anti-Patterns

• ❌ Writing a claim without source attribution — every claim must be tied to a URL
• ❌ Vagueness like "some say X" — provide a concrete source or drop it
• ❌ A whole report from 1 source — minimum 3 sources
• ❌ A URL that violates robots.txt — the WebFetch tool already blocks it

Typical Pattern for the Calling Agent

// In the pain-miner agent's PHASE 2:
const research = await callSkill("web-research", {
  topic: "US single-parent adoption pain points",
  keywords: ["adoption process complaints", "single parent legal challenges"],
  depth: "medium",
  output_format: "structured",
});
// runs its own pain analysis on research.themes[]

Error Handling

• All sources fail → report to the user + skip
• Token limit exceeded → newest 50K + WARN
• WebFetch tool missing → to the user: "WebFetch permission missing, provide sources manually"

Versioning

This skill is tied to framework/VERSION.md. v3.2.0 (Phase 6 reform).