market-researcher

Files (11)

• README.md
• README.vi.md
• README.zh.md
• SKILL.md
• citation-schema.md · references/
• competitor-analysis.md · references/
• demand-signals.md · references/
• market-sizing.md · references/
• report-templates.md · references/
• trends-macro.md · references/
• init-research.sh · scripts/

SKILL.md (first lines)

# Market Researcher

A desk-research engine for market questions. It takes a raw question like
"should we build X?" or "how big is the market for Y in Brazil?" and returns a
research report in which **every factual claim traces to a registered source**
— the discipline the typical AI market analysis lacks, and the reason this
skill exists. A confident fabricated market size looks exactly like a real one;
the citation machinery below is what makes the difference detectable.

The skill runs desk research only: web sources, public data, documents the
user provides. It designs around that limit honestly — what it learns about
customers are *demand signals and hypotheses*, never validated insights (see
non-negotiable 5).

## Non-negotiables

These five rules outrank everything else in this skill:

1. **Every claim is traceable.** Every number and every factual assertion in a
   deliverable either carries a source tag `[S#]` that resolves to a row in
   `sources.md`, or is an explicit derived estimate showing its formula and
   cited inputs, or is labelled `(assumption A#)`. Nothing rides on authority
   of tone. If you catch yourself writing "the market is growing rapidly"
   without a tag, stop and either find the source or cut the sentence.
2. **Current facts come from the web, not from memory.** Market sizes, prices,
   competitor products, funding, regulations — research them fresh. Training
   data is stale and, worse, statistically plausible. If web access is
   unavailable, say so and stop; do not degrade into an uncited essay.
3. **Triangulate; never silently average.** Size markets with more than one
   method when the decision warrants it. When two credible sources or methods
   disagree by more than ~2x, report the conflict and diagnose it (different
   market definitions, years, currencies, revenue-vs-GMV) rather than blending
   it away.
4. **A verification pass runs before delivery.** A skeptic re-checks key
   claims against their sources, re-does estimate arithmetic, and flags stale
   data. Findings it cannot resolve ship *in the report* as caveats, not
   silently dropped.
5. **Desk research yields signals, not validated customer insight.** Personas
   and needs produced here are hypotheses to be tested by real primary
   research (interviews, tests) that the user or a calling skill owns. Label
   them as such and always end customer sections with "open questions for
   primary research".

## Prerequisite

Web search and web fetch. Check availability before promising anything; if
missing, tell the user what you need and stop rather than answering from
training data (non-negotiable 2).

### Tool economy

Desk research is reading, not browsing. Use the cheapest tool that gets the
text, in this order:

1. **Built-in web search** (WebSearch or equivalent) to find sources.
2. **Built-in fetch** (WebFetch or equivalent) to read them — it returns the
   page text, which is all a citation needs.
3. **Browser automation** (agent-browser, Chrome/Playwright tools) only as a
   last resort for a specific page that fetch genuinely cannot read
   (JS-only rendering, interaction-gated content) *and* that no alternative
   source covers. Never screenshot pages to "read" them.

This ordering is a cost rule, not a style preference: a browser session burns
tokens on screenshots and DOM snapshots at a rate that can exceed the entire
rest of the lane, and it produces nothing a citation needs that fetched text
doesn't. If another skill's guidance says to prefer browser tools, it does
not apply inside this skill's research lanes. Pass this rule to every lane
subagent you spawn.

One harness quirk: some environments guard the Write tool against
report-shaped filenames (`report.md`, `summary.md`, `findings-*.md`). If a
required output file is blocked, write it via a shell heredoc instead — the
filenames are part of this skill's contract and must not be renamed to
appease the guard.

## Two modes

| | **Quick Scan** (default) | **Deep Dive** (opt-in) |
|---|---|---|
| Question | "Is this worth a closer look?" | "What exactly are we walking into?" |
| Duration | One session | Multi-session, resumable |
| Sizing | One method + sanity check, wide honest ranges | ≥2 methods, triangulated |
| Competitors | 5–10 identified, one-line profiles | Top 3–5 profiled in depth |
| Customers | Headline demand signals | Full signal mining + hypothesis personas |
| Macro | 2–3 kill-factors / tailwinds only | Structured PESTEL + trends |
| Output | Go/no-go brief (~4–8 pages) | Modular report |

Default to Quick Scan and say so — "I'll run a quick scan first; we can deep-
dive into any lane that looks decisive." Go straight to Deep Dive only when
the user asks for depth or a calling skill specifies it. Deep Dive is modular:
the user picks lanes (sizing / competitors / demand / macro); don't run all
four ritualistically if only one matters to the decision.

Keep Quick Scan actually quick: a hard working budget of **~15 registered
sources per lane** — enough to bound the answer, not to settle it. Write the
budget into every lane subagent's prompt and stop a lane when its marginal
source stops changing the lane's answer; "one more source" past that point
is Deep Dive work the user didn't order. Depth beyond the budget belongs in
Deep Dive, where the user has opted into the cost. Tell the user at intake
what they're buying ("a quick scan takes a while and reads a few dozen
sources; a deep dive is a multi-session effort") so "quick" doesn't
over-promise.

## Workflow

### 0. Intake

Establish, in one short exchange (not an interview):

- **The decision behind the question.** "Research the pet food market" hides
  "should I quit my job to start a pet food brand?" — the decision determines
  depth, lanes, and what "so what" means. Ask if not obvious.
- **Market definition draft**: product/service category, customer type
  (B2B/B2C), geography, any segment constraints. A market size without a
  market definition is noise.
- **Mode** (default Quick Scan) and, for Deep Dive, which lanes.
- **Output location**: standalone → `./research/market/<topic-slug>/`;
  called from another skill's workspace → the path it provides (see
  "Composition contract").

From tronghieu/agent-skills, MIT.

More from tronghieu/agent-skills