Research Brief

Produce a 200-1000 word research brief on a topic, with cited facts, quotes, suggested narrative angles, and open questions. Save to a markdown file under ./generated/research/.md so downstream skills can ingest via --research .

This skill does NOT:

• write the final post / carousel / reel (that's essay-write / viral-text / carousel-builder / reel-builder)
• run literature reviews requiring paywalled sources (Google Scholar, Pubmed — flag those as out-of-reach in the brief)
• give real-time prices / stocks / API quotas (use a dedicated tool, not WebSearch)
• replace primary-source domain research where the user already has expertise — the brief is a STARTING point, not a final word

Use when the user wants to gather context before writing, or wants a structured handoff to the downstream content skills.

ROLE

Read the topic → choose depth + sources → run search queries → extract facts with citations → synthesize into the canonical brief structure → save to ./generated/research/.md → return the path so other skills can pick it up.

PIPELINE

1. Clarify if topic is broad. "AI" / "marketing" — ask once for a sharper angle ("AI for which audience / which use case?"). Otherwise proceed.

1. Pick depth:

• --depth quick: 3-5 WebSearch queries, 200-400 word brief. ~1-2 min wall time.
• --depth standard (default): 7-10 queries, WebFetch the top 3 results per cluster, 500-800 word brief. ~3-5 min.
• --depth deep: 12-20 queries, includes Firecrawl/Exa MCP if available, 800-1500 word brief. ~5-10 min.

1. Probe available sources (see references/mcp-probe.md):

• WebSearch — always available inside Claude Code.
• WebFetch — always available.
• mcp__firecrawl__* — present if the user has Firecrawl MCP installed. Best for deep-crawl scrape of a known site.
• mcp__exa__* — present if Exa MCP installed. Best for neural/semantic search and finding non-obvious sources.
• Gracefully degrade: if a tool isn't present, note "(skipped — Firecrawl MCP not configured)" in the Sources section.

1. Run query batches — see references/methodology.md:

• Cluster A: foundational definitions (what is X, history, key actors). 2-4 queries.
• Cluster B: recent developments / news (last 6-12 months). 2-4 queries.
• Cluster C: contrarian / failure modes / criticism. 1-3 queries.
• Cluster D: data + numbers + named studies. 2-4 queries.
• Cluster E (deep only): primary sources, original papers, founder interviews. 2-5 queries.

1. Extract: for each result, pull facts with the source URL, distinguishing between:

• Verified facts (≥2 corroborating sources OR a primary source)
• Single-source claims (note as such — [single-source])
• Quotes (named attribution + URL + access date)
• Open questions (claims that couldn't be verified — list them as research gaps, don't fabricate confirmations)

1. Synthesize into canonical structure (see references/output-format.md):

``` #

Brief generated: . Sources used: . Depth: .

## TL;DR

## Key facts

• [#1]
• [#2]
• ...

## Notable quotes > "" — , , [#N]

## Suggested angles

1. — for
2. — ...
3. — ...

## Open questions

• ...

## Out of reach / requires expertise

## Sources

1. []() — accessed
2. ...

```

1. Write to disk: ./generated/research/-.md. Slug = kebab-case-of-topic, max 40 chars. If file exists, append timestamp.

1. Return path + 1-line summary on stdout: Brief written to ./generated/research/...md (N sources, TL;DR: ...).

MODES

• research-brief — default standard depth
• research-brief --depth quick|standard|deep — control breadth
• research-brief --sources websearch,webfetch,firecrawl,exa — restrict to specific tools (default: all available)
• research-brief --output — custom output path
• research-brief --format brief|outline|article-ready — controls verbosity (200 / 500 / 1000+ words)
• research-brief --angles 3 — number of suggested narrative angles in the output (default 3)
• research-brief --lang en|ru|mixed — write the brief in that language (sources can be any)
• research-brief --for carousel|reel|post|essay|landing — bias the angles + structure toward a downstream format

REFERENCES (load on demand)

| File | When to load | |---|---| | [references/methodology.md](references/methodology.md) | Always at step 4 — cluster definitions + query patterns + de-dup rules | | [references/sources.md](references/sources.md) | Picking sources — what to trust, what to flag, primary vs. secondary, when to escalate to deep | | [references/output-format.md](references/output-format.md) | Step 6 — exact section structure, citation format, slug rules, multilingual handling | | [references/mcp-probe.md](references/mcp-probe.md) | Step 3 — how to detect Firecrawl/Exa MCP presence, what each adds, graceful fallback |

EXAMPLES

See [examples/before-after.md](examples/before-after.md) — 3 calibration runs: standard depth on a tech topic (productivity software), quick depth on a cultural topic (a brand campaign), deep depth on a niche business topic (vertical AI in a specific industry).

CONSTRAINTS

• Cite every non-trivial claim. Inline [#N] markers tied to the Sources list. No source = put it in "Open questions" instead of presenting as fact.
• Don't fabricate sources. If WebSearch returns nothing solid, say so. A short brief with 5 real sources beats a long one with invented ones.
• Distinguish verified vs. single-source. Two corroborating sources OR a primary source → verified. One link → mark [single-source] next to the fact.
• Quote attributions need a person OR org + publication + date. Anonymous "experts say" — don't include.
• Date every source with access date. Web changes fast — note when you read it.
• Suggested angles must reference a specific downstream format (carousel, reel, essay) — generic "you could write about X" is useless.
• Open questions are mandatory for --depth standard and --depth deep. The list of things you DIDN'T resolve is half the value.
• Out of reach flag — paywalled papers, NDA-protected info, vendor-specific pricing — list them, don't fake answers.
• Output file path is always returned on stdout, last line. Downstream skills parse for --research ingestion.
• Don't run the actual research if the file already exists for today's topic-slug + date unless --force-refresh was passed. Print existing path and ask if user wants to refresh.
• Language: brief body follows --lang. Sources can be any language — translate quotes when needed, keep original in a (original: ...) annotation.
• Never insert hype words ("revolutionary", "game-changing", "stunning"). The brief is dry intelligence, not marketing.
• Don't promote your own confidence. If a source is weak, say "single blog post, no corroboration" — don't pad with "industry sources suggest".

INVOCATION HINTS

When the user says any of:

• "research X", "look up X", "what's known about X"
• "gather facts on Y", "brief me on Y", "give me a primer on Y"
• "prepare research for a post / carousel / reel / video on Z"
• "what's the current state of X", "trends in X right now"
• "find sources for X", "verified facts about X"
• "I need numbers / stats / quotes on X"

RU triggers:

• «исследуй X», «собери информацию по Y»
• «что известно про X», «подготовь ресерч по X»
• «факты по теме X с источниками»
• «найди источники / цитаты / цифры по X»
• «бриф по X», «справку по X»

Defaults: --depth standard --format brief --angles 3 --lang .

This skill is the upstream for carousel-builder and reel-builder — they accept --research and ingest the brief automatically. Chain: research-brief "topic" → carousel-builder --research ./generated/research/topic-YYYYMMDD.md → 8 slides on the same topic with cited facts.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Mikefluff
• Source: Mikefluff/skills
• License: MIT
• Homepage: https://www.npmjs.com/package/@mikefluff/skills

Install and usage instructions live in the source repository linked above.