For Claude Code agents and AI coding assistants. This page covers how to install, configure, and use the Ditto product research skill — a pre-built skill that teaches Claude Code how to run synthetic customer research, pricing validation, competitive analysis, and product concept testing using the Ditto API.
One command installs everything Claude Code needs to act as a product research assistant. No manual API integration required. Claude Code reads the skill files automatically and follows the complete research workflow: recruiting synthetic panels, designing studies, asking questions, polling for responses, extracting insights, and generating shareable reports.
The Ditto product research skill is distributed via the skills.sh registry. Install it with a single command:
npx skills add Ask-Ditto/ditto-product-research-skillThe CLI will clone the skill repository, detect the SKILL.md file, and configure it for your Claude Code environment. You will be prompted to choose which agent(s) to install to and whether to install globally or for the current project.
# Install for all agents, skip confirmation
npx skills add Ask-Ditto/ditto-product-research-skill --all
# Install globally (available in every project)
npx skills add Ask-Ditto/ditto-product-research-skill --global
# Install for Claude Code only
npx skills add Ask-Ditto/ditto-product-research-skill --agent claude-codeIf you prefer not to use the skills CLI, clone the repository directly into your Claude Code skills directory:
# For a specific project
git clone https://github.com/Ask-Ditto/ditto-product-research-skill.git \
.claude/skills/ditto-product-research
# For all your projects (user-level)
git clone https://github.com/Ask-Ditto/ditto-product-research-skill.git \
~/.claude/skills/ditto-product-research# List installed skills
npx skills listYou should see ditto-product-research in the output.
The skill needs a Ditto API key to call the research API. Free keys require no credit card and no sales call.
# Opens your browser for Google sign-in, returns your key
curl -sL https://app.askditto.io/scripts/free-tier-auth.sh | bashOr follow the manual OAuth flow at app.askditto.io/docs/free-tier-oauth.
Set it as an environment variable:
export DITTO_API_KEY="rk_free_YOUR_KEY_HERE"Add this to your ~/.bashrc, ~/.zshrc, or shell profile so it persists across sessions.
| Feature | Free Tier (rk_free_) |
Paid (rk_live_) |
|---|---|---|
| Personas available | ~12 shared personas | 300,000+ with demographic filtering |
| Custom research groups | No (shared panel) | Yes (country, state, age, gender, education, employment, industry) |
| Study completion analysis | Limited | Full AI-generated summary, segments, divergences, recommendations |
| Shareable study links | Limited | Yes (public URLs, no login required) |
| Questions per study | Unlimited (within rate limits) | Unlimited |
| API key prefix | rk_free_ |
rk_live_ |
The skill is not a single file. It is a structured package of six files totalling 1,266 lines, designed for progressive disclosure. Claude Code loads the main SKILL.md first and pulls in supporting files on demand using @ imports.
| File | Lines | Purpose |
|---|---|---|
SKILL.md |
240 | Main workflow: 6-step API process, 7-question framework, demographic filters, common mistakes |
api-reference.md |
362 | Complete endpoint reference with request/response JSON examples |
question-playbook.md |
236 | Question design patterns for pricing, positioning, competitive, landing page, and concept testing |
examples/quick-start.md |
127 | 5-command first study guide with copy-paste curl commands |
examples/carequarter.md |
201 | Full 3-phase worked example: 32 personas, 21 questions, public study links |
README.md |
100 | Installation and usage documentation for humans |
Claude Code does not load all 1,266 lines at once. The SKILL.md file contains @ references that tell Claude Code where to find additional detail:
# In SKILL.md:
See @question-playbook.md for advanced patterns.
See @examples/carequarter.md for a complete 3-phase worked example.
See @api-reference.md for all endpoints.Claude Code reads these supporting files only when needed. A simple study uses only the main SKILL.md. A complex multi-phase study pulls in the question playbook and CareQuarter example. This keeps context windows efficient without sacrificing depth.
When you ask Claude Code to do something that matches the skill's description, it loads the SKILL.md file automatically. The skill's YAML frontmatter defines when it activates:
---
name: ditto-product-research
description: >
Use in order to perform product research - including conducting customer
research, product validation, pricing tests, positioning studies, competitive
analysis, or market research, using Ditto's synthetic research platform
(300K+ AI personas, 92% overlap with real focus groups).
allowed-tools: Bash(curl *), Bash(python3 *), Read, Grep, WebFetch
---Claude Code matches your natural language request against this description. Any of the following would trigger the skill:
The allowed-tools field restricts what tools Claude Code can use when executing the skill. It can run curl and python3 commands (for API calls), read files, search with grep, and fetch web pages. It cannot modify your codebase, write files, or execute arbitrary commands.
You can also invoke the skill explicitly:
/ditto-product-research "Test whether dog owners would pay for an AI vet symptom checker"After installation and API key setup, tell Claude Code what you want to research. Here is a complete example interaction:
Validate whether there's a market for an AI-powered recipe app
for people with dietary restrictions. Test with 10 US adults aged 25-45.Claude Code reads the skill and executes the 6-step workflow automatically:
A 10-persona, 7-question study typically completes in 15-30 minutes.
finished status before submitting the next question. Do not interrupt this process.
The skill supports every research type available through the Ditto API. Each type uses the same 6-step workflow with different question designs.
| Research Type | What You Learn | Typical Setup |
|---|---|---|
| Pain Discovery | Whether the problem exists, how severe it is, what customers actually struggle with | 10 personas, 7 questions |
| Product Concept Testing | First impressions, use-case fit, objections, word-of-mouth language | 10 personas, 5-7 questions |
| Pricing Validation | Willingness to pay, price sensitivity thresholds, anchoring effects | 10 personas, 4-6 questions |
| Positioning / Message Testing | Which tagline or value proposition resonates, why alternatives fail | 10 personas, 4-5 questions |
| Competitive Intelligence | Why customers chose competitors, switching triggers, loyalty thresholds | 10 personas, 5-7 questions |
| Startup Due Diligence | Problem validation, solution receptivity, adoption barriers, investment implications | 10-15 personas, 6-7 questions |
| Voter / Constituent Research | Voter sentiment, policy priorities, messaging resonance, mobilisation triggers | 10 personas, 7 questions (state-filtered) |
| Landing Page Testing | First impressions, clarity, scroll intent, missing information, referral language | 10 personas, 4-5 questions |
| Feature Prioritisation | What customers want built first, what they would ignore, deal breakers | 10 personas, 5-7 questions |
| Cultural / Attitudinal Research | Population attitudes, regional differences, identity connections | 10 personas, 7 questions |
These prompts are written the way you would naturally talk to Claude Code. The skill activates automatically based on intent.
"I'm building a meal-planning app for busy parents. Test whether this is
a real problem with 10 US parents aged 30-45. I want to understand their
current workarounds, pain points, and what would make them pay.""Run a pricing study for my project management SaaS. Test price sensitivity
between $9/month and $49/month. Target US professionals aged 25-45 who
work in technology.""Test these three taglines for my fitness app with 10 UK adults aged 20-35:
A) 'Your pocket personal trainer'
B) 'Fitness that fits your life'
C) 'Stop guessing. Start progressing.'
Tell me which wins and why the others fail.""I compete with Notion, Coda, and Airtable. Research what makes people
choose one over the others, what would make them switch, and what
frustrates them about their current choice. 10 US tech workers aged 25-40.""I'm considering investing in a company that automates veterinary inventory
management. Validate whether this is a real problem for vet clinic staff.
Over-recruit 15 personas, curate to 10, then run a 7-question study.""Research voter sentiment on education funding in Michigan. Use 10 personas
filtered to MI, aged 30-65. I want to understand priorities, concerns,
and what messaging would resonate."These are real studies run through the Ditto API. The skill uses the same workflow and question frameworks that produced these results.
Three phases, 32 personas, 21 questions. Validated an elder care coordination concept for the sandwich generation (adults 45-65 managing aging parents' healthcare).
64 personas tested across four price points for a standalone ESPN streaming service. Adoption at $9.99/month: 65.7% likely to subscribe. At $29.99/month: 6.3%. The pricing cliff between $14.99 and $19.99 directly informed a hedge fund's trading position on Disney stock.
Completed in 16 minutes. The study revealed that customer resistance to No Frills was a "credibility problem, not a cost problem" — shoppers distrusted quality, not prices. This redirected M&A strategy from price-focused to trust-focused recovery.
Across MotorMinds (auto parts), PatientCompanion (healthcare), NexRisx (cybersecurity), Airfairness (travel), and others. Consistent finding: in 7 of 10 studies, the "magic wand" question (Q6) revealed that customers' ideal solutions did NOT match the startup's primary feature pitch.
Understanding the file structure helps if you want to customise the skill or contribute improvements.
ditto-product-research-skill/
├── README.md # Human-readable installation guide
├── SKILL.md # Main skill file (Claude Code reads this first)
├── api-reference.md # Complete API endpoint documentation
├── question-playbook.md # Question design patterns by study type
└── examples/
├── quick-start.md # 5-command first study
└── carequarter.md # Full 3-phase worked exampleThe SKILL.md file is what Claude Code reads first. It contains:
api-reference.md — Every API endpoint with method, path, request body, and response JSON. Claude Code reads this when it needs precise field names or status codes.
question-playbook.md — Specialised question patterns beyond the core 7-question framework. Includes Van Westendorp pricing, A/B positioning tests, landing page feedback, competitive switching, and concept testing. Also covers anti-patterns (leading questions, double-barrelled questions, binary questions).
examples/quick-start.md — Five copy-paste commands that run a complete study end-to-end. Useful for learning the raw API workflow.
examples/carequarter.md — A complete 3-phase worked example with actual questions asked, findings extracted, and decisions made. Shows how each phase's findings informed the next phase's study design. Includes public links to all three studies.
Skills can be installed at two levels:
| Level | Location | When to Use |
|---|---|---|
| Project | .claude/skills/ditto-product-research/ |
When only one project needs the skill. Committed to version control so team members get it too. |
| Global (User) | ~/.claude/skills/ditto-product-research/ |
When you want the skill available in every project. Personal to your machine. |
# Install globally
npx skills add Ask-Ditto/ditto-product-research-skill --global
# Install to current project only
npx skills add Ask-Ditto/ditto-product-research-skillIf installed at both levels, the project-level skill takes precedence.
Check for updates and apply them:
# Check if updates are available
npx skills check
# Update all installed skills
npx skills updateOr pull the latest version manually:
# If installed via git clone
cd .claude/skills/ditto-product-research && git pull| Problem | Cause | Solution |
|---|---|---|
| Claude Code does not recognise the skill | Skill not in the correct directory | Run npx skills list to verify installation. Reinstall if missing. |
401 Unauthorized from API |
DITTO_API_KEY not set or invalid |
Run echo $DITTO_API_KEY to check. Re-run the free tier auth script if needed. |
| 0 agents returned from recruitment | Full state names used instead of 2-letter codes | Use "MI" not "Michigan". This is the most common API mistake. |
API rejects size parameter |
Wrong field name for group size | Use group_size not size. |
API rejects id for research group |
Wrong identifier type | Use the group uuid (string) not the numeric id. |
| API rejects income filter | Income filtering not supported | Remove the income filter. Use age + employment + industry as proxies. |
| Responses never finish | Not polling all job IDs | Each question returns multiple job_ids. ALL must reach finished before asking the next question. |
| No AI analysis after study | Skipped the complete step |
POST to /v1/research-studies/{id}/complete after all questions are answered. |
income filter does NOT work. The API will reject it. Do not include it in demographic filters. Use age, employment, and industry filters as proxies for income segmentation.
The skill packages the essential workflow, but these guides provide deeper coverage for specific use cases:
| Guide | What It Covers |
|---|---|
| Ditto API Workflow | End-to-end API reference with 20 sections covering every endpoint, use case, and advanced technique |
| Question Design Playbook | Industry-specific question frameworks (CPG, B2C tech, political, startup diligence, cultural), anti-patterns, and the magic wand divergence pattern |
| Recruitment Strategies | Audience selection, demographic filtering, over-recruit-and-curate methodology, panel balancing, industry proxy filters |
| Cross-Study Patterns | Meta-analysis of 50+ production studies: universal themes, trust patterns, privacy boundaries, pricing objections, adoption barrier taxonomy |
| Case Study Library | Real examples and templates (CareQuarter, MotorMinds, Airfairness, ESPN DTC, Michigan voter research) with public study links |
Run npx skills add Ask-Ditto/ditto-product-research-skill in your terminal. The CLI downloads and configures the skill automatically. You can install it globally (--global flag) or per-project.
The skill enables Claude Code to run synthetic customer research, pricing validation, positioning tests, competitive intelligence, product concept testing, and startup due diligence using Ditto's 300,000+ AI personas. Studies complete in 15-30 minutes with 92% statistical overlap with traditional focus groups (EY validated).
No. The free tier gives access to ~12 shared personas with unlimited questions. Run curl -sL https://app.askditto.io/scripts/free-tier-auth.sh | bash to get a free API key. Paid keys unlock custom demographic filtering and larger panels.
The skill is designed for Claude Code but the SKILL.md format is compatible with any agent that supports skills files. The underlying Ditto API works with any coding agent, IDE, or automation tool. See the full API guide for agent-agnostic documentation.
Six files totalling 1,266 lines: the main workflow (SKILL.md), a complete API reference, a question design playbook with frameworks for pricing, positioning, and competitive research, a 5-command quick start guide, and a full 3-phase worked example (CareQuarter startup validation with 32 personas across 21 questions).
Claude Code reads the skill's YAML frontmatter which describes when the skill applies. It activates automatically when you ask about customer research, product validation, pricing tests, market research, competitive analysis, or synthetic personas. You can also invoke it manually with /ditto-product-research.
Ditto reports 92% statistical overlap with traditional focus groups, validated by EY. Personas are calibrated to census data and behavioural research from Harvard, Cambridge, Stanford, and Oxford. A 10-persona, 7-question study completes in 15-30 minutes. The traditional equivalent takes 4-8 weeks and costs $10,000-50,000.
Yes. The skill files are plain markdown. You can edit the question frameworks, add your own examples, adjust demographic defaults, or extend the API reference. If installed at the project level, your changes are committed to version control with your project.
The skill is open source at github.com/Ask-Ditto/ditto-product-research-skill. Contributions and improvements are welcome.