Alireza Rezvani’s open-source Market Research Skill uses local Python tools to estimate market size, plan survey samples, and score customer segments. Install the complete Skill folder in Claude Code, Codex, or OpenClaw, then supply your research data.
Use this Skill before committing to a new category, audience, or market. Start with a research brief, compare top-down and bottom-up estimates of total, serviceable, and obtainable market size (TAM/SAM/SOM), plan survey quotas if you need primary research, and evaluate candidate segments. It supplies calculation scripts and research methods; market data, source checks, and the final commercial decision remain with your team.
market_sizer.py calculates TAM/SAM/SOM from published market value and from potential customers × annual price. With --method both, it reports the TAM gap and flags differences above the selected profile’s tolerance.
sample_size_planner.py applies finite-population correction to the overall sample and calculates segment floors and quotas. Segment floors use the uncorrected formula, so their total can exceed the overall sample requirement.
segmentation_scorer.py weights measurable, substantial, accessible, differentiable, and actionable scores supplied by you. It returns TARGET, WATCH, or DROP; a failed size or accessibility gate means DROP even if other scores are high.
The package includes three research references, a brief template, and configuration helpers. The six Python files use the standard library; the optional autoresearch evaluator is separate from the three core analysis tools.
Use Claude Code, Codex, or OpenClaw with local file and terminal access. Have Git and Python 3 available. The inspected scripts import only standard-library modules; no pip packages, API keys, or store connection are required for the calculations.
Keep SKILL.md, scripts/, references/, and assets/ together. Copying the instructions into a chat omits the tools they call. If market-research is already installed, back up local changes before replacing it.
Prepare market.json, survey.json, or segments.json using the embedded SAMPLE objects as schema examples. Define geography, year, currency, customer counts, annual spending, and evidence for each assumption. Example data is fictional B2B SaaS data.
Uses the author’s --skill installer at the reviewed commit. Run in a terminal on macOS/Linux or WSL. By default it copies to ~/.codex/skills/market-research and replaces an existing copy; CODEX_SKILLS_DIR can change the destination.
git clone https://github.com/alirezarezvani/claude-skills.git
cd claude-skills
git checkout 6d2f02ea077eead1bee5411a31bcc6db5a11a70c
./scripts/codex-install.sh --skill market-researchThe complete, unchanged English SKILL.md is shown below. It is one file in an 11-file Skill package; copying this text does not install the scripts, references, or template. The Chinese guide and starter prompts are EcomAgentTools editorial adaptations.
Checked on October 25, 2026 at repository commit 6d2f02ea077e. The Skill declares version 2.9.0; the Research Ops plugin declares 2.14.1. Source and scripts were inspected, but installation and agent execution were not tested. GitHub stars and forks refer to the whole claude-skills repository.
View the reviewed source · MIT · © 2025 Alireza Rezvani
MIT License Copyright (c) 2025 Alireza Rezvani Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
---
name: market-research
description: Use when doing upstream market-research methodology — sizing a market as TAM/SAM/SOM computed BOTH top-down and bottoms-up (never a single unsourced number), planning a survey sample size with finite-population correction and per-segment minimums, or scoring candidate market segments against Kotler's measurable/substantial/accessible/differentiable/actionable criteria. Outputs always show the method and the assumptions. For market-research analysts and product-marketing at the sizing/survey/segmentation moment. Distinct from marketing-skill (campaign analytics, attribution, demand-gen) — this is the evidence-building methodology, not live-campaign optimization.
license: MIT
metadata:
version: 2.9.0
author: claude-code-skills
tags: [research-ops, market-research, tam-sam-som, market-sizing, survey, sampling, segmentation, competitive-intelligence]
compatible_tools: [claude-code, codex-cli, cursor, antigravity, opencode, gemini-cli]
---
# market-research
Upstream market-research methodology: market sizing, survey/sampling design, and segmentation. The discipline here is **method + assumptions**: a TAM is never a single number, a survey is never powered only in aggregate, and a segment is never a demographic slice.
## Purpose
Market-research analysts, product marketers, and strategy teams need rigorous evidence *before* anyone optimizes a campaign or sets a strategy. This skill structures three methodology decisions:
Three deterministic tools:
1. `market_sizer.py` — Computes TAM/SAM/SOM by **both** top-down and bottoms-up methods side-by-side, reports the divergence, and flags failed triangulation. Never returns a single number.
2. `sample_size_planner.py` — Survey sample size from confidence, margin of error, and expected proportion, with the finite-population correction and **per-segment minimums** (a survey powered overall is not powered per reported segment).
3. `segmentation_scorer.py` — Scores candidate segments against Kotler's five criteria and enforces a substantiality + accessibility gate; a slice that is too small or unreachable is dropped.
## When to use
Invoke this skill when:
- A board or exec asks "how big is this market?" and you need a defensible, triangulated answer.
- You are fielding a survey and need a sample size that holds up per segment, not just overall.
- You have a list of candidate segments and need to know which are real markets vs demographic slices.
- You are synthesizing competitive intelligence and need a methodological backbone.
**Do NOT use this skill to**: measure a live campaign (attribution, ROAS, CPA → `marketing-skill/campaign-analytics`), build demand-gen / paid-media plans (`marketing-skill/marketing-demand-acquisition`), set positioning / GTM strategy (`marketing-skill/marketing-strategy-pmm`), or set pricing (`commercial/pricing-strategist`).
## Workflow
1. **Write the brief** — Fill `assets/market_research_brief_template.md` (objective, the decision this informs, sizing approach, sampling plan, assumptions register).
2. **Size the market** — Run `market_sizer.py --input market.json --method both --profile {b2b-saas|consumer|enterprise|marketplace|hardware|services}`. Reconcile the top-down/bottoms-up delta before quoting anything.
3. **Plan the survey** — Run `sample_size_planner.py --input survey.json`. Fund the per-segment floors, not just the overall n.
4. **Score the segments** — Run `segmentation_scorer.py --input segments.json --profile <same>`. Drop segments failing the substantiality/accessibility gate.
5. **Assemble the evidence pack** — Combine into a brief. Every number carries its method + assumptions + confidence.
## Scripts
| Script | Purpose | Profiles |
|---|---|---|
| `scripts/market_sizer.py` | TAM/SAM/SOM top-down AND bottoms-up + triangulation flag | b2b-saas, consumer, enterprise, marketplace, hardware, services |
| `scripts/sample_size_planner.py` | Survey n + FPC + per-segment minima | n/a (parameter-driven) |
| `scripts/segmentation_scorer.py` | Kotler 5-criteria scoring + gate | b2b-saas, consumer, enterprise, marketplace, hardware, services |
All three: stdlib-only, `--help`, `--sample`, `--output {human,json}`.
## Onboarding & customization
Run the onboarding questionnaire **once before you start** — it captures your defaults so every tool in this skill is pre-configured. Customization is the point: the answers actually change tool behavior.
```bash
python3 scripts/onboard.py # interactive (also: --defaults, --set key=value, --reset)
python3 scripts/onboard.py --show # see the questions + current effective config
```
Answers are saved to `~/.config/research-ops/market-research.json` (global) or `./.research-ops/market-research.json` (`--scope project`) and are read automatically by `config_loader.py`. They set the default market **profile**, the default survey **confidence** and **margin of error**, and the default **sizing method**. CLI flags always override saved config; `RESEARCH_OPS_NO_CONFIG=1` ignores it.
**The four questions:** market profile · survey confidence · margin of error · sizing method.
## Optimize with autoresearch (opt-in)
This skill ships an **isolated, opt-in** bridge to `engineering/autoresearch-agent`. Only when you ask to "optimize" / "reconcile the sizing" / "run a loop" does an autoresearch experiment iteratively reconcile your market model so top-down and bottoms-up triangulate. `scripts/ar_evaluator.py` is the ground-truth evaluator; it prints `tam_divergence: <fraction>` (**lower** is better).
```bash
/ar:setup --domain custom --name tam-triangulation \
--target market.json \
--eval "python3 ar_evaluator.py --target market.json" \
--metric tam_divergence --direction lower
/ar:loop custom/tam-triangulation
```
Isolated: no hard dependency — autoresearch runs only on demand, and the loop edits `market.json`, never the evaluator.
## References
- `references/market_sizing_canon.md` — TAM/SAM/SOM frameworks (Bessemer, a16z); top-down vs bottoms-up; Fermi estimation; market-model conventions; common sizing fallacies.
- `references/survey_methodology.md` — Cochran *Sampling Techniques*; Dillman *Tailored Design Method*; Groves *Survey Methodology*; question-wording bias (Schuman & Presser); AAPOR standards.
- `references/segmentation_and_ci.md` — Kotler segmentation criteria; needs-based vs firmographic; Porter Five Forces; SCIP ethics; Christensen JTBD; conjoint/MaxDiff primer.
## Assumptions
- The sizer reports both methods but cannot validate your inputs — a top-down "1% of a $40B market" is only as good as the cited source and the serviceable fraction.
- Sample-size uses the conservative p=0.5 (maximum variance) unless you supply an expected proportion.
- Segment scores are inputs you provide; the tool enforces the gates and the weighting, it does not gather the underlying evidence.
- Competitive intelligence must follow the SCIP code of ethics — no misrepresentation, no protected information.
## Anti-patterns
- **A single TAM number with no method.** Always triangulate top-down against bottoms-up.
- **Spurious precision.** Size to the decision's tolerance; "$3.7142B" implies a confidence you do not have.
- **Powering only the total.** Each reported segment needs its own sample floor.
- **Leading or double-barreled survey questions.** Pre-test wording against the bias literature.
- **Calling a demographic slice a segment.** It must be substantial AND accessible.
## Distinct from
| Neighbor | Scope | Difference |
|---|---|---|
| `marketing-skill/campaign-analytics` | Attribution, ROAS, CPA, funnel of a live campaign | That **measures spend deployed**; this is **upstream methodology** |
| `marketing-skill/marketing-demand-acquisition` | Demand-gen, paid media, channel mix | That **runs acquisition**; this **builds the evidence** |
| `marketing-skill/marketing-strategy-pmm` | Positioning, GTM, category | That **sets strategy**; this **sizes and segments the market** |
| `commercial/pricing-strategist` | Pricing model + WTP + packaging | That **sets price**; this **sizes the market** |
| `product-research` (sibling) | User/product discovery methods | That studies **users**; this studies **the market** |
## Quick examples
```bash
python3 scripts/market_sizer.py --sample
python3 scripts/sample_size_planner.py --population 62000 --confidence 0.95 --moe 0.05
python3 scripts/segmentation_scorer.py --sample --output json
```
The sample market triangulates a ~$1.47B top-down SAM against the bottoms-up figure and flags the divergence; the segmentation sample drops the "solopreneurs who might want analytics" slice for failing the substantiality and accessibility gates.
## Forcing-question library (Matt Pocock grill discipline)
Walked one at a time by `/cs-grill-research-ops` or the orchestrator. Recommended answer + canon citation per question. Never bundled.
1. **"Is your TAM top-down or bottoms-up — and have you computed it both ways to triangulate?"**
Recommended: both; reconcile the delta before quoting a number.
Canon: Bessemer / a16z market-sizing; Fermi estimation.
2. **"What decision will this market size actually drive — and at what precision does it matter?"**
Recommended: size to the decision's tolerance, not to a spurious-precision number.
Canon: market-model conventions (Gartner/Forrester); decision-driven analysis.
3. **"What's your target margin of error and confidence — and does your sample clear it per segment, not just overall?"**
Recommended: power each reported segment, not only the total.
Canon: Cochran *Sampling Techniques*; AAPOR standards.
4. **"Are your survey questions free of leading and double-barreled wording?"**
Recommended: pre-test the wording; cite the bias source.
Canon: Schuman & Presser; Dillman *Tailored Design Method*.
5. **"Do your segments pass measurable / substantial / accessible / actionable — or are they just demographic slices?"**
Recommended: drop segments that fail substantiality or accessibility.
Canon: Kotler segmentation criteria.
Walk depth-first. Lock 1-2 before opening 3-5. After all are answered, invoke `market_sizer.py` → `sample_size_planner.py` → `segmentation_scorer.py`.
Starter prompts for the main use cases—copy and use them directly.
Locate the package, inspect the four onboarding questions, and save a market profile and survey defaults. Use immediately after installation or when starting research for a different market.
Use the installed market-research Skill. Locate its actual directory and confirm SKILL.md, scripts/, references/, and assets/ exist. From my research project directory, run python3 <skill-directory>/scripts/onboard.py --show. Ask me to confirm [PROFILE], survey confidence, margin of error, and sizing_method=both, then save them with --scope project. Keep subsequent analysis in this project directory so it reads the same config. Do not start autoresearch.[PROFILE]Build two estimates from your market inputs and explain the TAM gap before recommending a planning range. Use before deciding whether a category or geography warrants further validation.
Use the installed market-research Skill for [MARKET] using [MARKET_JSON] and [SOURCES]. Check every top_down and bottoms_up field against market_sizer.py SAMPLE, including geography, annual period, currency, and fraction units. Ask for missing inputs rather than accepting zero defaults. Run python3 <skill-directory>/scripts/market_sizer.py --input [MARKET_JSON] --method both --profile consumer --output json. Report both TAM/SAM/SOM sets, TAM divergence, assumptions, sources, and unresolved differences. Do not change evidence simply to reduce the gap.[MARKET][MARKET_JSON][SOURCES]Calculate the overall sample and each group’s quota from a survey specification. Use when results must be reported separately for several customer groups.
Use the installed market-research Skill to review [SURVEY_JSON]. Check population, confidence, margin_of_error, expected_proportion, segment_moe, and segments with population_share values that sum to 1. With --input, survey values must be in the JSON; CLI --confidence and --moe do not override it in this version. Run python3 <skill-directory>/scripts/sample_size_planner.py --input [SURVEY_JSON] --output json. Explain overall FPC, per-segment floors, recommended quotas, and their sum. Check feasibility against each segment population. Estimate invitations separately using [RESPONSE_RATE], and flag coverage and non-response bias.[SURVEY_JSON][RESPONSE_RATE]Apply the five scoring criteria and inspect the reasons for TARGET, WATCH, and DROP. Use when candidate segments have documented needs, size, and acquisition channels.
Use the installed market-research Skill with [SEGMENTS_JSON] and [EVIDENCE]. Check that each segment has all five 0–100 scores: measurable, substantial, accessible, differentiable, actionable. Do not invent scores for missing evidence. Run python3 <skill-directory>/scripts/segmentation_scorer.py --input [SEGMENTS_JSON] --profile consumer --output json. Explain the weighted score and the substantial/accessibility gates. For each TARGET or WATCH, propose one test within [BUDGET]; do not treat a score as proven demand.[SEGMENTS_JSON][EVIDENCE][BUDGET]Combine the calculations, source notes, and assumptions using the included template. Use when the team needs to decide whether to proceed, test, or defer.
Use the installed market-research Skill and assets/market_research_brief_template.md to assemble [RESULT_FILES] for [DECISION]. Preserve both sizing methods and their disagreement. Include any survey quotas, segment verdicts, public competitive evidence, source dates, assumptions register, and confidence statement. Mark unused sections as not applicable. Separate calculated results from judgment, and name the evidence still needed before committing budget.[RESULT_FILES][DECISION]The sizing and segmentation scripts default some missing values to zero; sizing can also fall back to embedded sample data when no input file is supplied. Validate complete inputs and always pass --input for real work. The human sizing display uses a dollar sign, so label other currencies explicitly in JSON-based reports.
The planner estimates completed responses for proportions. It does not send surveys, recruit respondents, correct coverage or non-response bias, or validate that quotas fit small populations. With JSON input, edit survey parameters in the file itself.
onboard.py saves globally under ~/.config/research-ops/ or under the current project with --scope project. Project config is read from the process working directory. Inspect existing settings before overwriting or resetting them. The calculation scripts contain no store API integration.
The separate autoresearch-agent integration can edit market.json to reduce the TAM gap. It is not installed by copying this Skill alone. A smaller gap does not validate the sources; preserve the original data and review each proposed assumption change.
The instructions can be read in chat, but the documented workflow requires the full Skill folder and local Python execution. Install scripts, references, and assets with SKILL.md.
The included calculations use Python’s standard library and local JSON files. They contain no store API integration. Your agent subscription or model usage is separate.
No. research-ops-skills is a broader plugin containing Market Research and other research skills. Use the manual single-folder method for this Skill alone.
The Skill declares 2.9.0 at commit 6d2f02ea077e, checked October 25, 2026. The containing plugin declares 2.14.1. Marketplace installation may retrieve a newer version.
You supply market values, customer counts, survey parameters, and segment scores with supporting sources. The Skill calculates and structures the evidence; it does not prove demand or collect survey responses.
Maintainer of the claude-skills open-source library. Market Research is one Skill in its Research Ops collection.
Repository-wide stars and forks, checked October 25, 2026. These are not installs, reviews, or performance results for Market Research.
Content checked:
No reviews yet.