# Installing the Ditto Skill for Claude Code
 

**LLM summary:** Run `npx skills add Ask-Ditto/ditto-product-research-skill` to install Ditto's synthetic research skill for Claude Code, then set a free API key to start running studies.

  **Looking for Product Marketing workflows?** 

We now have a dedicated Product Marketing skill with 8 PMM-specific study frameworks (positioning validation, messaging testing, competitive intelligence, pricing & packaging, GTM validation, product launch, buyer persona development, and brand tracking).

 

Install: `npx skills add Ask-Ditto/ditto-product-marketing`

 

Full guide: [https://askditto.io/claude-code/installing-product-marketing-skill](https://askditto.io/claude-code/installing-product-marketing-skill)

 

The Product Research skill on this page is best for general customer research, concept validation, pain discovery, and startup diligence.

  

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.

  **What this enables:** Instead of writing curl commands or reading API documentation, you tell Claude Code what you want to learn and it handles the entire research workflow. "Validate whether parents of young children would pay for a meal-planning app" becomes a complete 10-persona, 7-question study with shareable results.   **Contents** 

 
1. [Installation: One Command](#install)
 
2. [Getting Your API Key](#api-key)
 
3. [What the Skill Includes](#what-is-included)
 
4. [Which Skill Should I Install?](#which-skill)
 
5. [How Claude Code Uses the Skill](#how-it-works)
 
6. [Running Your First Study](#your-first-study)
 
7. [What You Can Research](#what-you-can-research)
 
8. [Example Prompts That Work](#example-prompts)
 
9. [Real Results from Production Studies](#real-results)
 
10. [Skill File Structure](#skill-structure)
 
11. [Advanced: Global vs Project Installation](#advanced)
 
12. [Updating the Skill](#updating)
 
13. [Troubleshooting](#troubleshooting)

14. [Demographic Filter Reference](#filter-reference)

15. [Beyond Full Studies: One-Off Questions and Agent Lookup](#one-off-questions)

16. [Related Guides](#related-guides)

17. [Frequently Asked Questions](#faq)


 

  

## 1. Installation: One Command
 

The Ditto product research skill is distributed via the [skills.sh](https://skills.sh) registry. Install it with a single command:

  

```
npx skills add Ask-Ditto/ditto-product-research-skill
```

  

The 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.

 

### Quick Install (Skip Prompts)
 

```
# 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-code
```

 

### Manual Installation (Alternative)
 

If 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
```

 

### Verify Installation
 

```
# List installed skills
npx skills list
```

 

You should see `ditto-product-research` in the output.

 

## 2. Getting Your API Key
 

The skill needs a Ditto API key to call the research API. Free keys require no credit card and no sales call.

 

### Free Tier (Recommended to Start)
 

```
# Opens your browser for Google sign-in, returns your key
curl -sL https://app.askditto.io/scripts/free-tier-auth.sh | bash
```

 

Or follow the manual OAuth flow at [app.askditto.io/docs/free-tier-oauth](https://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.

 

### Free vs Paid
 

                                    
| 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, income, ethnicity, religion, and more) |
| 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_` |

  **Recommendation:** Start with the free tier. It is sufficient for learning the workflow and running initial studies. Upgrade when you need demographic filtering or larger panels.  

## 3. What the Skill Includes
 

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 |

 

## Which Skill Should I Install?
 

### Product Research Skill (this page)
 

**Best for:**

 

 
- General customer research and Voice of Customer
 
- Pain discovery studies
 
- Concept and product validation
 
- Startup customer diligence (VC use case)
 
- Landing page and ad creative testing
 
- Voter/constituent research
 
- Feature prioritisation studies
 

 

**Includes:** Main workflow (`SKILL.md`), API reference, question playbook, quick-start guide, CareQuarter 3-phase worked example.

 

**Install:** `npx skills add Ask-Ditto/ditto-product-research-skill`

 

**GitHub:** [https://github.com/Ask-Ditto/ditto-product-research-skill](https://github.com/Ask-Ditto/ditto-product-research-skill)

 

### Product Marketing Skill

**Best for:** Positioning validation (April Dunford), messaging testing (A/B/C), competitive intelligence (battlecards), pricing & packaging (Van Westendorp), GTM validation, product launch research, buyer persona development, brand perception tracking.

**Install:** `npx skills add Ask-Ditto/ditto-product-marketing` | **GitHub:** [ditto-product-marketing](https://github.com/Ask-Ditto/ditto-product-marketing) | **Full guide:** [installing-product-marketing-skill](https://askditto.io/claude-code/installing-product-marketing-skill)

### VC Customer Diligence Skill

**Best for:** Thesis-first customer diligence for VCs, angels, and PE firms. Over-recruit & curate methodology, non-leading question framework, magic wand divergence detection, industry proxy mapping, and VC-ready share links.

**Install:** `npx skills add Ask-Ditto/ditto-vc-diligence` | **GitHub:** [ditto-vc-diligence](https://github.com/Ask-Ditto/ditto-vc-diligence) | **Full guide:** [installing-vc-diligence-skill](https://askditto.io/claude-code/installing-vc-diligence-skill)

### Political Polling Skill

**Best for:** State-filtered voter research for campaigns and pollsters. Candidate sentiment, issue salience, messaging testing, and demographic cross-tabs across all 50 US states. Requires 2-letter state codes.

**Install:** `npx skills add Ask-Ditto/ditto-political-polling` | **GitHub:** [ditto-political-polling](https://github.com/Ask-Ditto/ditto-political-polling) | **Full guide:** [installing-political-polling-skill](https://askditto.io/claude-code/installing-political-polling-skill)

### Sales Enablement Skill

**Best for:** Turning one Ditto study into 7 sales deliverables: battlecards, objection handlers, proof-point libraries, one-pagers, pitch decks, ROI calculators, and demo scripts. Uses ABC/SIVA/StoryBrand/AESN quality frameworks.

**Install:** `npx skills add Ask-Ditto/ditto-sales-enablement` | **GitHub:** [ditto-sales-enablement](https://github.com/Ask-Ditto/ditto-sales-enablement) | **Full guide:** [installing-sales-enablement-skill](https://askditto.io/claude-code/installing-sales-enablement-skill)

### Voice of Customer Skill

**Best for:** Always-on VoC programme with monthly pulse checks, quarterly deep dives, longitudinal tracking, and 6 deliverables (verbatim library, theme tracker, executive brief, segment cards, action board, trend report).

**Install:** `npx skills add Ask-Ditto/ditto-voc-programme` | **GitHub:** [ditto-voc-programme](https://github.com/Ask-Ditto/ditto-voc-programme) | **Full guide:** [installing-voc-programme-skill](https://askditto.io/claude-code/installing-voc-programme-skill)

### Content Marketing Skill

**Best for:** One study, 7 content formats. Narrative arc framework for blog posts, social threads, email sequences, whitepapers, case studies, infographics, and video scripts with SEO/GEO optimisation.

**Install:** `npx skills add Ask-Ditto/ditto-content-marketing` | **GitHub:** [ditto-content-marketing](https://github.com/Ask-Ditto/ditto-content-marketing) | **Full guide:** [installing-content-marketing-skill](https://askditto.io/claude-code/installing-content-marketing-skill)

### Can I install multiple skills?


Yes. All skills work independently. Each activates on domain-specific keywords. Install the Product Research skill as your general-purpose tool, then add specialist skills for your specific workflow.

 

### Progressive Disclosure Architecture
 

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.

 

## 4. How Claude Code Uses the Skill
 

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:

 

 
- "Run a pricing study for my SaaS product"
 
- "Validate whether parents would pay for a tutoring app"
 
- "Test which positioning resonates best with Canadian millennials"
 
- "Do competitive intelligence on meal kit delivery services"
 
- "Use Ditto to research voter sentiment in Michigan"
 

 

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.

 

### Manual Invocation
 

You can also invoke the skill explicitly:

 

```
/ditto-product-research "Test whether dog owners would pay for an AI vet symptom checker"
```

 

## 5. Running Your First Study
 

After installation and API key setup, tell Claude Code what you want to research. Here is a complete example interaction:

 

### What You Type
 

```
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.
```

 

### What Claude Code Does
 

Claude Code reads the skill and executes the 6-step workflow automatically:

 

 
1. **Recruits a panel** via [`POST /v1/research-groups/recruit`](https://app.askditto.io/docs/api#tag/research-groups/POST/v1/research-groups/recruit) — Creates a research group of 10 personas filtered by country (USA), age (25-45)

2. **Creates a study** via [`POST /v1/research-studies`](https://app.askditto.io/docs/api#tag/research-studies/POST/v1/research-studies) — Sets title, objective, and links the research group

3. **Asks 7 questions** via [`POST /v1/research-studies/{id}/questions`](https://app.askditto.io/docs/api#tag/research-studies/POST/v1/research-studies/{study_id}/questions) — Designs questions using the 7-question framework (establish relevance, identify pain, quantify impact, current solutions, past attempts, magic wand, adoption barriers)

4. **Polls for responses** via [`GET /v1/jobs/{id}`](https://app.askditto.io/docs/api#tag/jobs/GET/v1/jobs/{job_id}) — Waits for each question's responses to complete before asking the next

5. **Completes the study** via [`POST /v1/research-studies/{id}/complete`](https://app.askditto.io/docs/api#tag/research-studies/POST/v1/research-studies/{study_id}/complete) — Triggers AI-generated analysis (summary, segments, divergences, recommendations)

6. **Generates a share link** via [`POST /v1/research-studies/{id}/share`](https://app.askditto.io/docs/api#tag/research-studies/POST/v1/research-studies/{study_id}/share/update) — Produces a public URL anyone can view without an API key
 

 

### What You Get Back
 

 
- A summary of findings from 10 personas
 
- Key themes and patterns across responses
 
- Direct quotes from personas (segmented by demographics)
 
- A shareable link to the full study results
 

 

A 10-persona, 7-question study typically completes in 15-30 minutes.

  **Important:** Questions must be asked sequentially. The skill handles this automatically — it polls one `job_id` from each question until it reaches `finished` status before submitting the next question (all jobs from the same question complete simultaneously, so polling one is sufficient). Do not interrupt this process.

## 6. What You Can Research
 

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 |

 

## 7. Example Prompts That Work
 

These prompts are written the way you would naturally talk to Claude Code. The skill activates automatically based on intent.

 

### Product Validation
 

```
"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."
```

 

### Pricing Study
 

```
"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."
```

 

### Positioning Test
 

```
"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."
```

 

### Competitive Intelligence
 

```
"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."
```

 

### Startup Due Diligence
 

```
"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."
```

 

### Voter Research
 

```
"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."
```

  **Tip:** Be specific about your target demographic. "US adults aged 25-45 who work in healthcare" produces more useful results than "people who might use my product." The skill translates your description into API filters automatically. For targeting beyond demographics (e.g., "pet owners", "SaaS buyers"), the API's `description` field applies AI-based matching.

## 8. Real Results from Production Studies
 

These are real studies run through the Ditto API. The skill uses the same workflow and question frameworks that produced these results.

  

#### CareQuarter: Startup Validated in 4 Hours
 

Three phases, 32 personas, 21 questions. Validated an elder care coordination concept for the sandwich generation (adults 45-65 managing aging parents' healthcare).

 

 
- **Phase 1 (Pain Discovery):** Revealed the real problem was "responsibility without authority" — not time burden as hypothesised
 
- **Phase 2 (Deep Dive):** Established trust architecture — HIPAA-only access first, named coordinator (not rotating teams), phone and paper (not apps)
 
- **Phase 3 (Concept Test):** Validated pricing ($175/month routine, $325/month complex) with 100% acceptance. Winning positioning: "Stop being the unpaid case manager"
 

 

 [Phase 1 Study](https://app.askditto.io/organization/studies/shared/UlXcv4cjValQu0qJFJrSfL5eKB1zHfc5e2cFZiLYjrA) | [Phase 2 Study](https://app.askditto.io/organization/studies/shared/x52Mu1QOwow6fbhornqjY51ug4QI-jY7daoj37ndfAw) | [Phase 3 Study](https://app.askditto.io/organization/studies/shared/IQiBzKN_q2M3-vSISd_1C7zr2XB66tV6QvVlfy8DkMo) 

   

#### ESPN DTC: Pricing Cliff Discovery
 

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.

   

#### Loblaw / No Frills: M&A Credibility Gap
 

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.

   

#### 10 Startup Due Diligence Studies
 

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.

  

## 9. Skill File Structure
 

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 example
```

 

### SKILL.md: The Entry Point
 

The `SKILL.md` file is what Claude Code reads first. It contains:

 

 
- **YAML frontmatter** — name, description (used for skill matching), and allowed tools
 
- **6-step API workflow** — complete curl examples for each step
 
- **7-question framework** — proven question sequence with rationale
 
- **Demographic filter reference** — all available filters with types, examples, and known limitations
 
- **Common mistakes** — the errors that cause the most wasted API calls
 
- **Multi-phase methodology** — when and how to run iterative studies
 

 

### Supporting Files (Loaded on Demand)
 

**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.

 

## 10. Advanced: Global vs Project Installation
 

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-skill
```

 

If installed at both levels, the project-level skill takes precedence.

 

## 11. Updating the Skill
 

Check for updates and apply them:

 

```
# Check if updates are available
npx skills check

# Update all installed skills
npx skills update
```

 

Or pull the latest version manually:

 

```
# If installed via git clone
cd .claude/skills/ditto-product-research && git pull
```

 

## 12. Troubleshooting
 

                                              
| 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`. |
| Income filter returns 0 agents | Wrong parameter name | Use `income_annual_usd_min` and `income_annual_usd_max` (not `income`). Example: `"income_annual_usd_min": 50000, "income_annual_usd_max": 100000`. |
| Filter returns 0 despite data existing | Exact string match required | Filter values must be exact matches (case-insensitive). Use `"Hispanic or Latino"` not `"Hispanic"`. Use `"Roman Catholic"` not `"Catholic"`. There is no partial or fuzzy matching. |
| Responses never finish | Not polling job IDs correctly | Each question returns multiple `job_ids`. You only need to poll ONE — all jobs from the same question complete simultaneously. Wait 45-50s before first poll. |
| No AI analysis after study | Skipped the `complete` step | POST to `/v1/research-studies/{id}/complete` after all questions are answered. |

  **Important: Filter value discoverability.** Demographic filters require exact string values (case-insensitive). The API does not support partial matching or fuzzy search. For example, `ethnicity=Hispanic` returns 0 agents, but `ethnicity=Hispanic or Latino` returns 57,760. The API docs do not currently enumerate all valid filter values, so refer to the filter reference below or the [API documentation](https://app.askditto.io/docs/api) for available values. Income filtering works via `income_annual_usd_min` / `income_annual_usd_max` (not `income`).

## 13. Demographic Filter Reference


The Ditto API supports the following demographic filters when recruiting research groups. All filter values are **case-insensitive** but require **exact string matches** (no partial or fuzzy matching).



### Core Filters


| Filter | Type | Example | Notes |
| --- | --- | --- | --- |
| `country` | string | `"USA"`, `"UK"`, `"Germany"`, `"Canada"` | Only 4 countries currently supported |
| `state` | string | `"MI"`, `"TX"`, `"CA"` | 2-letter codes only (USA). Full names return 0 agents |
| `age_min` / `age_max` | integer | `25` / `45` | Age range |
| `gender` | string | `"Male"`, `"Female"` | Binary only. `gender_identity` filter exists but has no data |
| `education` | string | `"Bachelors Degree"`, `"Masters Degree"` | Exact string required |
| `employment` | string | `"Full-time"`, `"Part-time"` | Employment status |
| `industry` | string | `"Technology"`, `"Healthcare"` | Industry sector |



### Extended Filters


| Filter | Type | Example | Notes |
| --- | --- | --- | --- |
| `income_annual_usd_min` / `income_annual_usd_max` | integer | `50000` / `100000` | Annual income range in USD. Do NOT use `income` — use the `_min`/`_max` variant |
| `ethnicity` | string | `"Hispanic or Latino"`, `"Black or African American"` | 30 distinct values from US Census / Canadian classifications. Must use full value |
| `religion` | string | `"Roman Catholic"`, `"Protestant"`, `"Islam"` | Case-insensitive. Use `"Roman Catholic"` not `"Catholic"` |
| `sex_at_birth` | string | `"Male"`, `"Female"` | Biological sex |
| `labour_status` | string | `"employed"` | Limited data availability |



### Soft Targeting with `description`

For targeting criteria that go beyond demographic filters (e.g., "pet owners", "SaaS buyers", "people who commute by car"), use the `description` field on the recruit call. This applies AI-based matching rather than strict demographic filtering:



```json
{
  "name": "SaaS Buyers Panel",
  "group_size": 10,
  "description": "People who evaluate and purchase B2B SaaS tools for their team",
  "filters": {
    "country": "USA",
    "age_min": 28,
    "age_max": 50
  }
}
```



### Filters That Do Not Work

| Filter | Status |
| --- | --- |
| `political_party` | Returns 0 agents for all values |
| `gender_identity` | Returns 0 agents for all values |



## 14. Beyond Full Studies: One-Off Questions and Agent Lookup


Not every research task requires a full study. The Ditto API also supports:



### Find a Specific Persona

Use `POST /v1/agents/find` to locate a single persona matching specific constraints (age, gender, state, occupation). Returns an agent profile with a direct chat URL.



### Search for Personas

Use `GET /v1/agents/search` to find multiple matching personas with broader filters. Useful for exploring what personas are available before recruiting a group.



### Ask a Quick One-Off Question

Use `POST /v1/research-agents/{agent_id}/questions` to ask a single question directly to a specific agent — no study setup, no group recruitment needed. Ideal for quick follow-ups, clarifications, or testing a question before running a full study.

For up to 5 agents, make one call per agent. Beyond 5 agents, use a full study workflow instead.



### Ask a Question to an Existing Group

Use `POST /v1/research-groups/{group_id}/questions` to ask a quick question to all agents in an existing research group without creating a study.



### Upload Media for Questions

Use [`POST /v1/media-assets`](https://app.askditto.io/docs/api#tag/media-assets/POST/v1/media-assets) to upload images or files, then attach them to questions using the returned `media_asset_id`. Works with both study questions and direct agent questions.

For full request/response schemas for all endpoints, see the [interactive API documentation](https://app.askditto.io/docs/api).



## 15. Related Guides
 

The skill packages the essential workflow, but these guides provide deeper coverage for specific use cases:

 

                                 
| Guide | What It Covers |
| --- | --- |
| [Ditto API Workflow](https://askditto.io/claude-code-guide) | End-to-end API reference with 20 sections covering every endpoint, use case, and advanced technique |
| [Question Design Playbook](https://askditto.io/claude-code-guide/question-design-playbook) | Industry-specific question frameworks (CPG, B2C tech, political, startup diligence, cultural), anti-patterns, and the magic wand divergence pattern |
| [Recruitment Strategies](https://askditto.io/claude-code-guide/recruitment-strategies) | Audience selection, demographic filtering, over-recruit-and-curate methodology, panel balancing, industry proxy filters |
| [Customer Segmentation Guide](https://askditto.io/claude-code-guide/customer-segmentation-guide) | Multi-group segmentation studies, behavioural segmentation, and segment prioritisation frameworks |
| [Content Marketing Engine Guide](https://askditto.io/claude-code-guide/content-marketing-engine-guide) | One-study workflow to publish seven content formats with SEO/GEO optimisation |
| [Sales Enablement Guide](https://askditto.io/claude-code-guide/sales-enablement-guide) | Turn Ditto research into sales collateral, objection handling, and proof points for reps |
| [Voice of Customer Guide](https://askditto.io/claude-code-guide/voice-of-customer-guide) | Always-on VoC programme with monthly pulse checks, deep dives, and six deliverables |
| [GTM Strategy Validation Guide](https://askditto.io/claude-code-guide/gtm-strategy-validation-guide) | Validate GTM motion, channels, pricing, and proof points across segments |
| [Product Launch Research Guide](https://askditto.io/claude-code-guide/product-launch-research-guide) | Pre-launch concept validation and post-launch sentiment measurement with launch impact reports |
| [Cross-Study Patterns](https://askditto.io/claude-code-guide/cross-study-patterns) | Meta-analysis of 50+ production studies: universal themes, trust patterns, privacy boundaries, pricing objections, adoption barrier taxonomy |
| [Case Study Library](https://askditto.io/claude-code-guide/case-study-library) | Real examples and templates (CareQuarter, MotorMinds, Airfairness, ESPN DTC, Michigan voter research) with public study links |

 

## 16. Frequently Asked Questions
 

### How do I install the Ditto skill for Claude Code?
 

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.

 

### What can the Ditto skill do in Claude Code?
 

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).

 

### Do I need a paid Ditto account to use the skill?
 

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.

 

### Does the Ditto skill work with other AI coding agents?
 

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](https://askditto.io/claude-code-guide) for agent-agnostic documentation.

 

### What is included in the skill package?
 

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).

 

### How does Claude Code know when to use the Ditto skill?
 

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`.

 

### How reliable are the results?
 

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.

 

### Can I customise the skill?
 

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.

 

### Where is the skill source code?
 

The skill is open source at [github.com/Ask-Ditto/ditto-product-research-skill](https://github.com/Ask-Ditto/ditto-product-research-skill). Contributions and improvements are welcome.

  

 **Related:** [Claude Code Docs](https://askditto.io/claude-code) | [Why Ditto for agents](https://askditto.io/claude-code/why-ditto) | [Product Marketing Skill](https://askditto.io/claude-code/installing-product-marketing-skill) | [VC Diligence Skill](https://askditto.io/claude-code/installing-vc-diligence-skill) | [Political Polling Skill](https://askditto.io/claude-code/installing-political-polling-skill) | [Sales Enablement Skill](https://askditto.io/claude-code/installing-sales-enablement-skill) | [VoC Skill](https://askditto.io/claude-code/installing-voc-programme-skill) | [Content Marketing Skill](https://askditto.io/claude-code/installing-content-marketing-skill) | [API Workflow Guide](https://askditto.io/claude-code-guide) | [Question Design](https://askditto.io/claude-code-guide/question-design-playbook) | [Recruitment Strategies](https://askditto.io/claude-code-guide/recruitment-strategies) | [Customer Segmentation](https://askditto.io/claude-code-guide/customer-segmentation-guide) | [Content Marketing Engine](https://askditto.io/claude-code-guide/content-marketing-engine-guide) | [Sales Enablement](https://askditto.io/claude-code-guide/sales-enablement-guide) | [Voice of Customer](https://askditto.io/claude-code-guide/voice-of-customer-guide) | [GTM Strategy Validation](https://askditto.io/claude-code-guide/gtm-strategy-validation-guide) | [Cross-Study Patterns](https://askditto.io/claude-code-guide/cross-study-patterns) 

 

 **API Base URL:** `https://app.askditto.io` | **API Docs:** [Interactive Reference](https://app.askditto.io/docs/api) | **Free Tier:** [Get API Key](https://app.askditto.io/docs/free-tier-oauth) | **Skill Repo:** [GitHub](https://github.com/Ask-Ditto/ditto-product-research-skill)

 

© 2026 Ditto. Synthetic Personas of the World's Population.

 

Last updated: February 2026