# Market Research

> >

- **Type:** Skill
- **Install:** `agentstack add skill-berenshtein-market-research-skills-market-research`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [berenshtein](https://agentstack.voostack.com/s/berenshtein)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [berenshtein](https://github.com/berenshtein)
- **Source:** https://github.com/berenshtein/market-research-skills/tree/main/plugins/market-research/skills/market-research

## Install

```sh
agentstack add skill-berenshtein-market-research-skills-market-research
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Market Research — full AJTBD research cycle

This skill orchestrates 9 phases of market research across 3 blocks (Research → Strategy → Output)
with 3 user checkpoints. Three modes: **express**, **quick**, **deep**.

---

## First message

When this skill is invoked, do the following:

1. **Identify inputs.** Check whether the user has provided:
   - A path to a product context document (if a brief / one-pager already exists)
   - A product description in the message
   - Or nothing — then ask

2. **Check for resume.** Look for `research-state.json` in the working folder:
   - If found and `status != "completed"` → propose resuming from the last phase
   - If not found → start a new research project

3. **Pick the mode.** Ask the user:

```
Research mode:

1. **Express** (~40 min, 1 session) — landscape + competitors + segments.
   Research Block only, no strategy or sales artifacts.
   For quick reconnaissance of a new market.

2. **Quick** (~2.5h, 3 sessions) — 1 segment, full 9-phase cycle.
   Research + Strategy + Output. The main mode.

3. **Deep** (~5h, 3-4 sessions) — 2 segments, full analytics.
   Extended data collection, all competitors, 5 experts on the council.

I recommend express for a first look, quick for a full study,
deep when maximum thoroughness is required.
```

4. **Create a working folder** and initialize state:

```
./market-research-{product-slug}/
├── research/
│   └── (artifacts 01-09 will live here)
└── research-state.json
```

---

## Modes: express / quick / deep

| Aspect | Express | Quick | Deep |
|--------|---------|-------|------|
| Time | ~40 min (1 session) | ~2.5h (3 sessions) | ~5h (3-4 sessions) |
| Phases | 1-3 only | 1-9 | 1-9 |
| Checkpoints | CP1 (final) | CP1, CP2, CP3 | CP1, CP2, CP3 |
| Deep-dive segments | — | 1 | 2 |
| Phase 1: English-language sources | No | No | Yes |
| Phase 2: competitors | 5 direct | 7 direct + 2 benchmark | All (10-15 + 3-5 global) |
| Phase 6: CEO Council | — | 3-4 experts | 5 experts |
| Phase 7: Synthesis | — | Offer to skip | Include |
| Output block (8-9) | — | Yes | Yes |

**Express ends after Checkpoint 1.** The user gets a landscape, competitive matrix and segments — enough to decide "dig deeper or not." If desired, they can continue in quick/deep — state allows resume.

---

## State Management

### research-state.json

```json
{
  "version": "1.0",
  "mode": "express|quick|deep",
  "product": "Product name",
  "product_slug": "product-slug",
  "brief_source": "path/to/context.md | manual",
  "workspace": "./market-research-{slug}/",
  "created_at": "2026-03-19T10:00:00Z",
  "updated_at": "2026-03-19T12:00:00Z",
  "current_phase": 0,
  "status": "in_progress|checkpoint|completed|failed",
  "phases": {
    "1": {
      "status": "pending|in_progress|done|skipped",
      "started_at": null,
      "completed_at": null,
      "artifacts": [],
      "sources_count": 0,
      "errors": []
    }
  },
  "checkpoints": {
    "1": {
      "status": "pending|passed",
      "gate_met": false,
      "decisions": {}
    },
    "2": {
      "status": "pending|passed",
      "gate_met": false,
      "decisions": {}
    },
    "3": {
      "status": "pending|passed",
      "gate_met": false,
      "decisions": {}
    }
  },
  "insights": [],
  "selected_segments": [],
  "brief_vars": {
    "product": "",
    "market": "",
    "country": "",
    "currency": "",
    "business_model": "",
    "known_competitors": [],
    "icp_hypothesis": "",
    "url": ""
  }
}
```

### State management rules

- **Update state after each phase:** `current_phase`, `phases[N].status`, `updated_at`
- **Record user decisions** in `checkpoints[N].decisions`
- **Insight tracker:** add every key fact from Phase 1-2 to `insights[]`:
  ```json
  { "id": "I001", "phase": 1, "text": "15.2M self-employed in RF", "confidence": "V", "source_url": "https://...", "status": "pending", "used_in": [] }
  ```
  As insights get used in phases 3-9, update `status` → `"used"` and `used_in`. At the end (Phase 9), check whether any insights are still `"pending"` — ask the user to decide: use or discard.
- **On errors:** record into `phases[N].errors[]`, apply the fallback, do not stop
- **Resume:** when continuing, read state and rebuild context from the artifacts of completed phases
- **Mode upgrade:** if a research project starts in express, the user can continue in quick/deep — update `mode` in state; phases 1-3 are already done

### Confidence Labels

Tag every number and statement in artifacts:
- **[V]** — Verified: confirmed from 2+ independent sources. **Required:** URLs of both sources.
- **[S]** — Single-source: one source. **Required:** source URL.
- **[E]** — Estimated: computed from assumptions. **Required:** the calculation formula.
- **[G]** — Generated: produced by the LLM without a primary source.

**Citation format:**
```
TAM: 280B RUB [V] (Data Insight, 2025: https://... | FTS, 2025: https://...)
SAM: 42B RUB [E] (280 × 0.15 — segment share estimated)
Market growth ~40% [S] (Data Insight, 2025: https://...)
Average ticket ~15K RUB [G]
```

---

## Algorithm: 9 phases in 3 blocks

### RESEARCH BLOCK (Phases 1-3)

#### Phase 1: Market Landscape

**Goal:** Gather the quantitative picture of the market: size, growth, drivers, regulation, key players.

**Execution — worker agents (hybrid pattern).**

Launch 3 (express/quick) or 4 (deep) subagents in parallel via the Agent tool (`subagent_type: "general-purpose"`) in a SINGLE message — all calls at once. Each worker runs in its own clean context and returns a finished section (300-500 words). Raw data (deep research dumps, crawling HTML) stays inside the agent's context and dies with it — the main context is not polluted with tens of thousands of tokens of raw material.

**Worker A: Market Size & Growth**

```
You are a research worker for a market research project. Collect quantitative data
about the "{brief_vars.market}" market in "{brief_vars.country}" for
{current_year - 1}-{current_year}.

Tools (in priority order):
1. deep_researcher_start with the prompt:
   "Research the {brief_vars.market} market in {brief_vars.country}
   ({current_year - 1}-{current_year}). Focus on: TAM in {brief_vars.currency},
   revenue pool, sub-segments relevant to {brief_vars.icp_hypothesis},
   YoY growth rates, adjacent markets for benchmark."
2. Fallback (if deep_researcher is empty/errors out): web_search_advanced_exa
   (numResults: 15, startPublishedDate: "{current_year - 1}-01-01") with the query
   "{brief_vars.market} market {brief_vars.country} {current_year}"
   + crawling_exa on the top-5 URLs.

Return EXACTLY this format (≤400 words, no commentary):

## Market Size & Growth
- TAM: X {brief_vars.currency} [V/S/E] (source URLs)
- YoY growth: X% [V/S/E] (URL)
- Key sub-segments with shares: ...
- Adjacent markets for benchmark: ...

## Sources
| # | Source | URL | Date | What was taken |

Requirements: every number with a confidence label. [V] — 2+ URLs, [S] — 1 URL, [E] — formula.
```

**Worker B: Drivers & Trends**

```
You are a research worker. Collect growth drivers, macro trends, technological and
behavioral shifts, and demographics for the "{brief_vars.market}" market in
"{brief_vars.country}".

Tools: web_search_advanced_exa × 2 in parallel:
- Query 1: "{brief_vars.icp_hypothesis} statistics growth count {current_year}"
  (startPublishedDate: "{current_year - 1}-06-01", numResults: 8, type: neural)
- Query 2: "{brief_vars.market} trends drivers {current_year}"
  (startPublishedDate: "{current_year - 1}-01-01", numResults: 8, type: neural)
+ crawling_exa on the top-3 URLs.

Return (≤400 words):

## Drivers & Trends
- Macro drivers: ...
- Technological shifts: ...
- Behavioral changes: ...
- Demographics: ...

## Sources
| # | Source | URL | Date | What was taken |

Requirements: every fact with a confidence label and URL.
```

**Worker C: Regulation & Players**

```
You are a research worker. Collect regulation and key players in the
"{brief_vars.market}" market in "{brief_vars.country}".

Tools: web_search_advanced_exa × 2:
- "regulation {brief_vars.market} {brief_vars.country} changes law"
  (startPublishedDate: "{current_year - 1}-01-01", numResults: 8)
- "{brief_vars.known_competitors joined by ', '} new players {current_year}"
  (numResults: 10)
+ crawling_exa.

Return (≤500 words):

## Regulation
- Key regulatory acts: ...
- Upcoming changes: ...
- Enforcement trends: ...
- Licensing requirements: ...

## Key Players (short list — details in Phase 2)
Name + 1 line of positioning each. NO detailed cards.

## Sources
| # | Source | URL | Date | What was taken |
```

**Worker D: Global Benchmarks** (deep mode only)

```
You are a research worker. Find English-language analytical sources on the global
state of the "{brief_vars.market in English}" market and benchmarks from mature markets.

Tools: web_search_advanced_exa in English (numResults: 10) + crawling_exa.

Return (≤300 words):

## Global Benchmarks
- Global market size: ...
- Global vs. local growth: ...
- Leaders from other countries as examples: ...

## Sources
| # | Source | URL | Date | What was taken |
```

**Assembly by the main Claude (after receiving all responses):**

1. Create `01-landscape.md` in the order: Market Size → Drivers → Regulation → Players → Global Benchmarks (deep only)
2. Merge all `## Sources` tables into a single **Source Registry** at the end of the file — deduplicate by URL, combine the "What was taken" column:

```markdown
## Source Registry

| # | Source | URL | Publication date | What was taken |
|---|--------|-----|------------------|-----------------|
| 1 | Data Insight | https://... | 2025-02 | TAM, GMV growth |
| 2 | FTS via Interfax | https://... | 2025-01 | Number of self-employed |
| ... | | | | |
```

3. Add each key fact to `insights[]` in state with `source_url` and `confidence`

**Output:** `01-landscape.md`

**Gate (for checkpoint 1):** `sources_count ≥ 10` (unique URLs in the Source Registry)

---

#### Phase 2: Competitive Intelligence

**Goal:** Build a comparative matrix of every competitor.

**Number of competitors:**
- Express: 5 direct
- Quick: 7 direct + 2 global benchmark
- Deep: all that can be found (typically 10-15 direct + 3-5 global)

**Execution — worker agents (hybrid pattern).**

For EVERY competitor, launch a separate subagent via the Agent tool (`subagent_type: "general-purpose"`). All agents — in parallel in a SINGLE message. Each returns a finished card (~400 words). Raw crawling/company_research data stays in the worker's context and dies with it — by the end of Phase 2 the main context receives only 10-15 finished cards instead of hundreds of kilobytes of raw material.

**Worker prompt (template, identical for every worker):**

```
You are a research worker. Collect data on ONE competitor and return a finished
card for the comparative matrix.

Competitor: {competitor_name}
Known URL: {competitor_url | "find it yourself"}
Context: market {brief_vars.market}, {brief_vars.country}

Tools (in order of use):
1. company_research_exa({competitor_name}) — primary collection
2. crawling_exa({url}) — pricing, features, clients from site pages
3. web_search_exa("{competitor_name} reviews customers g2") — reputation

Fallback: if company_research_exa is empty →
crawling_exa on the site + puppeteer_navigate + puppeteer_screenshot of the pricing page.

Return EXACTLY this format, nothing extra (≤400 words):

### {competitor_name}

| Field | Value |
|-------|-------|
| URL | ... |
| Year founded | ... [S] (URL) |
| Services | checklist |
| Target customers | ... |
| Pricing model | ... |
| Specific numbers | ... [V/S/E] (URL) |
| Automation | self-serve / API / manual |
| Known customers | ... |
| Geography | ... |
| Strengths | ... |
| Weaknesses | ... |
| Positioning | 1 sentence |

### Sources
| # | Source | URL | What was taken |

Requirements: every number/fact with a confidence label [V/S/E/G]. No commentary,
only the card and sources. If data is missing — write "⚠️ not found".
```

**Assembly by the main Claude (after all cards are received):**

1. Create `02-competitors.md` with the structure:
   - **Summary matrix** at the top — one row per competitor (key columns: name, URL, pricing model, positioning) for quick comparison
   - **Per-competitor cards** — details from workers, direct first, then benchmark
   - **Source Registry** at the end — merged from all workers, deduplicated by URL

```markdown
## Source Registry

| # | Competitor | Data source | URL | What was taken |
|---|------------|-------------|-----|-----------------|
| 1 | CompanyA | Official website | https://... | Pricing, features |
| 2 | CompanyA | G2 review | https://... | NPS, complaints |
| ... | | | | |
```

2. Check the cards: if a competitor has no pricing → mark `⚠️ pricing not found` in the summary matrix

**Output:** `02-competitors.md`

**Gate (for checkpoint 1):** `competitors_count ≥ 5`

---

#### Phase 3: JTBD Segments

**Goal:** Identify 5 attractive segments and enrich them with data from Phase 1-2.

**Sub-skill invocation:** Use the Skill tool with `skill: "jtbd-segment"`, passing the context:
```
Product: {brief_vars.product}
Market: (data from 01-landscape.md — TAM, drivers, regulation)
Competitors: (data from 02-competitors.md — positioning gaps)
```

**After receiving the segments:**
- Enrich TAM/SAM/SOM with specific numbers from Phase 1 (with confidence labels and URLs)
- Verify: every segment must reference landscape data
- For [E] numbers — the formula is mandatory: `SAM: 42B RUB [E] (TAM 280 × 0.15 segment share)`

**Output:** `03-segments.md`

**Gate (for checkpoint 1):** `segments_count ≥ 3, each with TAM`

---

### ─── CHECKPOINT 1: Research Review ───

**When:** After Phase 3 (all three artifacts ready).

**In express mode:** this is the final checkpoint. After it, propose: "Express complete. Want to continue in quick/deep mode? State is saved, phases 1-3 don't need to be repeated."

**Gate criteria (all must be true):**
- [ ] Phase 1: ≥10 sources with URLs in the Source Registry
- [ ] Phase 2: ≥5 competitors in the matrix
- [ ] Phase 3: ≥3 segments with TAM/SAM/SOM

**If the gate is not met:** tell the user exactly what is missing and offer to redo the specific phase.

**Message to the user:**
```
## Checkpoint 1: Research Review

**Landscape:** {sources_count} sources, TAM = {tam_value}
**Competitors:** {competitors_count} in the matrix
**Segments:** {segments_count}, top-3 by attractiveness:
  1. {segment_1} — TAM {tam_1}
  2. {segment_2} — TAM {tam_2}
  3. {segment_3} — TAM {tam_3}

**Decisions:**
1. Does the landscape match your picture of the market? What is missing?
2. Which competitors are missing?
3. Which 1-2 segments should be prioritized for deep analysis?
   - Quick mode: pick 1
   - Deep mode: pick 2
```

**Record the decisions** in `checkpoints.1.decisions`:
```json
{
  "landscape_approved": true,
  "missing_competitors": [],
  "selected_segments": ["segment-name-1"],
  "user_notes": "..."
}
```

Update `selected_segments` at the root of state.

---

### STRATEGY BLOCK (Phases 4-6) — quick and deep only

#### Phase 4: Job Graph + Forces of Progress

**Goal:** Decompose the Core Job of the selected segments. Include Forces of Progress.

**Sub-skill invocation:** Use the Skill tool with `skill: "jtbd-jobgraph"` for each selected segment, passing:
```
Segment: {segment_name}
Core Jobs: {core_jobs from 03-segments.md}
Market context: (key insights from 01-landscape.md)
```

**After receiving the Job Graph — add a Forces of Progress section:**

```markdown
## Forces of Progress

### Push (what pushes away from the current solution)
- ...

### Pull (what attracts to the new solution)
- ...

### Anxiety (what creates anxiety about switching)
- ...

### Habit (what holds the customer on the current solution)
- ...
```

For each Force, cite concrete data from Phase 1-2 (with confidence labels and source URLs).

**Output:** `04-jobgraph-{segment-slug}.md` (×1-2 depending on mode)

---

##

…

## Source & license

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

- **Author:** [berenshtein](https://github.com/berenshtein)
- **Source:** [berenshtein/market-research-skills](https://github.com/berenshtein/market-research-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-berenshtein-market-research-skills-market-research
- Seller: https://agentstack.voostack.com/s/berenshtein
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.