Topic Research
Turns a topic into a rigorous, sourced, fact-checked report. Two artifacts come out every time: a markdown brief (agent-readable, the handoff to a content-writer skill) and a branded HTML report (human-facing, deployable). The workflow is: interview the user so the research is targeted, fan out parallel research sub-agents across source types, verify every hard claim, synthesize to markdown, render to HTML, deploy.
[!important] The two rules that make this good
- Targeted, not generic. The Phase 0 Q&A shapes every sub-agent. Research aimed at a purpose beats a topic dump every time.
- Verify before you publish. No hard number reaches the report without a fact-check verdict and a caveat. Fact and opinion stay visibly separate.
Phase 0: Targeted Q&A + capability probe
Do both before any research runs. Ask conversationally, one thing at a time, adapting to answers.
A. Targeted Q&A (this shapes the whole run)
- Topic, and what they already believe or suspect about it.
- Purpose: is this to write a specific piece of content (which format? which audience?), to make a decision, to brief a team, to prep for a talk? A content purpose changes what the report emphasizes and how the markdown is structured downstream.
- Angle / biases / skepticism to reflect: a point of view they want the research to support or pressure-test, claims they are suspicious of, hot takes to stress-test. These become explicit search directives for the sub-agents. If they have none, the research stays neutral and simply reports the tension it finds.
- Depth: Quick / Standard / Deep (see below).
- Output: report + markdown always; deploy target is a Claude live artifact (instant, no infra) or Vercel (stable custom URL). Ask which.
- Brand: default to the neo-brutalist "Signal Report" look in
assets/report-template.html. If they have a brand (site, design system, colors/fonts/logo), extract and restyle; the CSS is token-driven at the top of the template.
Capture the answers in a short brief-config (topic, purpose, audience, directives, depth, deploy, brand) that you carry through every phase.
B. Capability probe
Detect which connectors are available (see references/connectors.md for the exact checks and how to connect each):
Firecrawl, Apify, a scholarly/PubMed MCP, YouTube MCP / vidIQ, Reddit MCP, browser-harness, and the Vercel deploy path.
Show the user the research plan you will run given what is connected, then offer to connect the high-value missing ones (Firecrawl and Apify are the biggest upgrades; PubMed only matters for medical topics). If they decline, name the fallback each stream will use and continue. Never hard-fail for a missing connector; degrade.
Depth control (user preference + topic-aware)
- Quick: 2-3 streams, shallow read, ~1 fact-check pass. For fast-moving or lightly-researched topics.
- Standard: all 4 streams, ~15 sources, full fact-check. The default.
- Deep: all 4 streams with more agents per stream, wider reading, adversarial fact-check (multiple verifiers per claim).
- Auto-downshift: if a topic has little scholarly literature (true for most marketing topics), lighten or skip the scholarly stream rather than padding it, and say so. Do not fake depth.
Phase 1: Parallel research fan-out
Launch one sub-agent per source type, concurrently (send them in a single batch). Give each the topic + purpose + the user's angle/biases as explicit directives. Each returns structured markdown: findings (one source URL each), a "hard claims to verify" list, and vendor/anecdotal claims flagged. Full parameterized prompts are in references/research-agents.md.
| Stream |
Job |
Primary connector |
Fallback ladder |
| Scholarly / evidence |
Credible papers, studies, citations only. Domain-aware: medical → PubMed/PMC (+ bioRxiv/medRxiv, ClinicalTrials); AI/CS → arXiv; general → Semantic Scholar / Scholar |
Scholarly/PubMed MCP + Firecrawl paper index |
web search on journal / .edu / .gov domains → browser-use |
| Forums / community |
Real language, pain points, firsthand results (anecdotal), objections |
Apify Reddit scraper |
Reddit MCP → web search site:reddit.com + fetch → browser-use |
| Web / vendor |
Vendor docs, industry data, reputable blogs, the tool/landscape |
Firecrawl search + scrape |
web search + web fetch → browser-use for JS-heavy pages |
| Creators / video |
What top creators teach; recurring tactics + contrarian takes |
YouTube MCP + vidIQ + transcripts (yt-dlp / watch) |
Apify YouTube scraper → web search for summaries |
Keep per-stream reading within the depth budget and have each agent log/report anything it deliberately skipped. No silent truncation.
Phase 2: Fact-check pass
Collect every "hard claim" from all streams, dedupe, and verify with the fact-checker skill (Standard: one pass; Deep: multiple independent verifiers per claim, kill on majority-refute). Each claim gets a verdict (VERIFIED / PARTIAL / PROJECTION / VENDOR-CLAIM / ANECDOTAL / FALSE), a primary source, and a one-line caveat. Apply corrections to the synthesis. A caught correction is a feature: surface it in the ledger.
Never fact-check firsthand forum anecdotes as fact; they are sentiment and stay labelled as such.
Phase 3: Synthesize to the markdown brief
Merge the four streams + verdicts into one structured markdown brief using references/brief-template.md: TL;DR, headline stats, verified evidence, a "what the evidence says" / playbook section (tag each point with how many source types corroborate it), the counter-narrative / skepticism, a tool-or-landscape section where relevant, voice-of-market language, the claims-verified ledger, and grouped sources. Keep fact and opinion visibly separate, and reflect the user's stated angle honestly (support it where the evidence does, push back where it doesn't).
[!important] The markdown is the point, not a waypoint
Produce the markdown before the HTML and always keep it. It is the agent-readable handoff: the next skill in the chain (a brand-voice content writer) consumes this exact file to write the piece. HTML is the human render; markdown is the machine brief. Save it as <topic-slug>-brief.md in the working folder.
Phase 4: Render to the branded HTML report
Adapt assets/report-template.html (a complete worked example, the GEO/AEO "Signal Report"). Keep the <style> block and the component patterns (KPI cards, evidence cards, playbook cards, skeptic quote blocks, the tool table, the claims-ledger rows, grouped sources) and swap in the new topic's content from the markdown brief. Restyle the CSS tokens + brand-badge text if the user gave a brand. The file must stay self-contained (no external assets except the Google Fonts link already in the template). Verify it renders (open it, check computed styles / console) before deploying.
Phase 5: Deploy and deliver
Deploying makes the report public, so confirm first: show the user the rendered report and the fact-check ledger, and get an explicit go-ahead before deploying. If they want changes, revise and re-confirm.
Deploy to the target chosen at intake (see references/connectors.md for both paths):
- Claude live artifact: instant, no infrastructure, good default for one-off research.
- Vercel: stable custom URL. Locally the CLI is fine; from a cloud routine, git push is the deploy (never the Vercel CLI/API).
Save the markdown + HTML locally, return the live URL, and tell the user the markdown path plus the one line that matters: this brief can feed straight into a content-writer skill to draft the piece.
Principles (baked into every run)
- Connector-adaptive with graceful degradation and ask-to-connect. Never hard-fail.
- Every claim carries a source. Verify hard numbers before publishing. Label vendor / anecdotal / projection.
- Triangulate across source types and show the corroboration count. One source alone lies.
- Cap depth for cost; log anything skipped.
- Targeted beats generic: the Q&A directives ride along into every sub-agent.
- Two artifacts, always: markdown brief (handoff) + HTML report (render).
Reference files
references/research-agents.md: the parameterized sub-agent prompts (4 research streams + fact-check).references/connectors.md: capability probe, how to connect each source, fallback ladders, and both deploy paths.references/brief-template.md: the markdown brief skeleton (the handoff artifact structure).assets/report-template.html: the branded "Signal Report" HTML, a complete worked example to adapt.
Self-improvement
This skill is never finished. Improve it as you use it.
- When the user corrects how a step was done, update the relevant reference file (
research-agents.md, connectors.md, or brief-template.md) or this SKILL.md so the correction sticks. Do not just fix it for this run.
- When a correction is a hard rule ("always X", "never Y"), add it as a permanent rule here.
- When the user says a brief or report was genuinely good, save it to
references/examples/ so it becomes a model for future runs.
- Keep the skill small: when you add something, run the deletion test and cut anything that no longer changes behavior.
1---2name: topic-research3description: Research any topic end to end and get back a fact-checked, branded HTML report plus an agent-readable markdown brief. Use when the user wants to research a topic, do a deep dive, build a research report or briefing, gather evidence before writing a piece of content, understand 'what does the research say / what are people saying about X', or study a subject across papers, forums, YouTube, and vendor/web sources. Fans out parallel sub-agents (one per source type), verifies every hard claim with the fact-checker, synthesizes one sourced markdown brief, renders it as a branded report, and deploys it live. Connector-adaptive: uses Firecrawl, Apify, a scholarly/PubMed MCP, YouTube/vidIQ, and Reddit where available, and falls back to web search, web fetch, and browser-use where they are not. Trigger on 'research this topic', 'topic research', 'do a deep dive on', 'build me a research report', 'what does the evidence say about', or 'research X before I write about it'.4---56# Topic Research78Turns a topic into a rigorous, sourced, fact-checked report. Two artifacts come out every time: a **markdown brief** (agent-readable, the handoff to a content-writer skill) and a **branded HTML report** (human-facing, deployable). The workflow is: interview the user so the research is targeted, fan out parallel research sub-agents across source types, verify every hard claim, synthesize to markdown, render to HTML, deploy.910> [!important] The two rules that make this good11> 1. **Targeted, not generic.** The Phase 0 Q&A shapes every sub-agent. Research aimed at a purpose beats a topic dump every time.12> 2. **Verify before you publish.** No hard number reaches the report without a fact-check verdict and a caveat. Fact and opinion stay visibly separate.1314---1516## Phase 0: Targeted Q&A + capability probe1718Do both before any research runs. Ask conversationally, one thing at a time, adapting to answers.1920### A. Targeted Q&A (this shapes the whole run)211. **Topic**, and what they already believe or suspect about it.222. **Purpose**: is this to write a specific piece of content (which format? which audience?), to make a decision, to brief a team, to prep for a talk? A content purpose changes what the report emphasizes and how the markdown is structured downstream.233. **Angle / biases / skepticism to reflect**: a point of view they want the research to support or pressure-test, claims they are suspicious of, hot takes to stress-test. These become explicit search directives for the sub-agents. If they have none, the research stays neutral and simply reports the tension it finds.244. **Depth**: Quick / Standard / Deep (see below).255. **Output**: report + markdown always; deploy target is a Claude live artifact (instant, no infra) or Vercel (stable custom URL). Ask which.266. **Brand**: default to the neo-brutalist "Signal Report" look in `assets/report-template.html`. If they have a brand (site, design system, colors/fonts/logo), extract and restyle; the CSS is token-driven at the top of the template.2728Capture the answers in a short `brief-config` (topic, purpose, audience, directives, depth, deploy, brand) that you carry through every phase.2930### B. Capability probe31Detect which connectors are available (see `references/connectors.md` for the exact checks and how to connect each):32Firecrawl, Apify, a scholarly/PubMed MCP, YouTube MCP / vidIQ, Reddit MCP, browser-harness, and the Vercel deploy path.3334Show the user the research plan you will run given what is connected, then **offer to connect the high-value missing ones** (Firecrawl and Apify are the biggest upgrades; PubMed only matters for medical topics). If they decline, name the fallback each stream will use and continue. Never hard-fail for a missing connector; degrade.3536### Depth control (user preference + topic-aware)37- **Quick**: 2-3 streams, shallow read, ~1 fact-check pass. For fast-moving or lightly-researched topics.38- **Standard**: all 4 streams, ~15 sources, full fact-check. The default.39- **Deep**: all 4 streams with more agents per stream, wider reading, adversarial fact-check (multiple verifiers per claim).40- **Auto-downshift**: if a topic has little scholarly literature (true for most marketing topics), lighten or skip the scholarly stream rather than padding it, and say so. Do not fake depth.4142---4344## Phase 1: Parallel research fan-out4546Launch **one sub-agent per source type, concurrently** (send them in a single batch). Give each the topic + purpose + the user's angle/biases as explicit directives. Each returns structured markdown: findings (one source URL each), a "hard claims to verify" list, and vendor/anecdotal claims flagged. Full parameterized prompts are in `references/research-agents.md`.4748| Stream | Job | Primary connector | Fallback ladder |49|---|---|---|---|50| **Scholarly / evidence** | Credible papers, studies, citations only. Domain-aware: medical → PubMed/PMC (+ bioRxiv/medRxiv, ClinicalTrials); AI/CS → arXiv; general → Semantic Scholar / Scholar | Scholarly/PubMed MCP + Firecrawl paper index | web search on journal / `.edu` / `.gov` domains → browser-use |51| **Forums / community** | Real language, pain points, firsthand results (anecdotal), objections | Apify Reddit scraper | Reddit MCP → web search `site:reddit.com` + fetch → browser-use |52| **Web / vendor** | Vendor docs, industry data, reputable blogs, the tool/landscape | Firecrawl search + scrape | web search + web fetch → browser-use for JS-heavy pages |53| **Creators / video** | What top creators teach; recurring tactics + contrarian takes | YouTube MCP + vidIQ + transcripts (yt-dlp / `watch`) | Apify YouTube scraper → web search for summaries |5455Keep per-stream reading within the depth budget and have each agent `log`/report anything it deliberately skipped. No silent truncation.5657---5859## Phase 2: Fact-check pass6061Collect every "hard claim" from all streams, dedupe, and verify with the **`fact-checker` skill** (Standard: one pass; Deep: multiple independent verifiers per claim, kill on majority-refute). Each claim gets a verdict (**VERIFIED / PARTIAL / PROJECTION / VENDOR-CLAIM / ANECDOTAL / FALSE**), a primary source, and a one-line caveat. Apply corrections to the synthesis. A caught correction is a feature: surface it in the ledger.6263Never fact-check firsthand forum anecdotes as fact; they are sentiment and stay labelled as such.6465---6667## Phase 3: Synthesize to the markdown brief6869Merge the four streams + verdicts into one structured markdown brief using `references/brief-template.md`: TL;DR, headline stats, verified evidence, a "what the evidence says" / playbook section (tag each point with how many source types corroborate it), the counter-narrative / skepticism, a tool-or-landscape section where relevant, voice-of-market language, the **claims-verified ledger**, and grouped sources. Keep fact and opinion visibly separate, and reflect the user's stated angle honestly (support it where the evidence does, push back where it doesn't).7071> [!important] The markdown is the point, not a waypoint72> Produce the markdown **before** the HTML and always keep it. It is the agent-readable handoff: the next skill in the chain (a brand-voice content writer) consumes this exact file to write the piece. HTML is the human render; markdown is the machine brief. Save it as `<topic-slug>-brief.md` in the working folder.7374---7576## Phase 4: Render to the branded HTML report7778Adapt `assets/report-template.html` (a complete worked example, the GEO/AEO "Signal Report"). **Keep the `<style>` block and the component patterns** (KPI cards, evidence cards, playbook cards, skeptic quote blocks, the tool table, the claims-ledger rows, grouped sources) and **swap in the new topic's content** from the markdown brief. Restyle the CSS tokens + brand-badge text if the user gave a brand. The file must stay self-contained (no external assets except the Google Fonts link already in the template). Verify it renders (open it, check computed styles / console) before deploying.7980---8182## Phase 5: Deploy and deliver8384Deploying makes the report public, so confirm first: show the user the rendered report and the fact-check ledger, and get an explicit go-ahead before deploying. If they want changes, revise and re-confirm.8586Deploy to the target chosen at intake (see `references/connectors.md` for both paths):87- **Claude live artifact**: instant, no infrastructure, good default for one-off research.88- **Vercel**: stable custom URL. Locally the CLI is fine; from a cloud routine, **git push is the deploy** (never the Vercel CLI/API).8990Save the markdown + HTML locally, return the live URL, and tell the user the markdown path plus the one line that matters: *this brief can feed straight into a content-writer skill to draft the piece.*9192---9394## Principles (baked into every run)95- Connector-adaptive with graceful degradation and ask-to-connect. Never hard-fail.96- Every claim carries a source. Verify hard numbers before publishing. Label vendor / anecdotal / projection.97- Triangulate across source types and show the corroboration count. One source alone lies.98- Cap depth for cost; log anything skipped.99- Targeted beats generic: the Q&A directives ride along into every sub-agent.100- Two artifacts, always: markdown brief (handoff) + HTML report (render).101102## Reference files103- `references/research-agents.md`: the parameterized sub-agent prompts (4 research streams + fact-check).104- `references/connectors.md`: capability probe, how to connect each source, fallback ladders, and both deploy paths.105- `references/brief-template.md`: the markdown brief skeleton (the handoff artifact structure).106- `assets/report-template.html`: the branded "Signal Report" HTML, a complete worked example to adapt.107108## Self-improvement109This skill is never finished. Improve it as you use it.110- When the user corrects how a step was done, update the relevant reference file (`research-agents.md`, `connectors.md`, or `brief-template.md`) or this SKILL.md so the correction sticks. Do not just fix it for this run.111- When a correction is a hard rule ("always X", "never Y"), add it as a permanent rule here.112- When the user says a brief or report was genuinely good, save it to `references/examples/` so it becomes a model for future runs.113- Keep the skill small: when you add something, run the deletion test and cut anything that no longer changes behavior.
naveedharri