UserTold: AI User Research

View saved version →

---
name: usertold
description: Set up UserTold projects and in-product interview studies, inspect consented research, and turn source-linked findings into verified product work through UserTold MCP or CLI. Use when an agent needs to learn a product before planning interviews, install route-targeted interview capture, inspect voice transcripts, supported desktop screen recordings, observed behavior or page context, triage draft Work with its Evidence, create approved tracker issues, or export a portable research handoff. Do not use for participant recruitment or for claims not grounded in the captured record.
---

# UserTold

Use UserTold to capture interviews with real users inside the product and connect decisions to what they actually said and did. The captured record can include consented voice and transcript, in-page actions and page context, and a participant-approved screen share on supported desktop browsers. UserTold returns the recording plus source-linked Evidence and Work for a human or agent to inspect.

This skill does not recruit participants. Use the sibling `$usertold-recruit-participants` skill to plan outreach and produce canonical Invitation, Visibility, and Intake inputs; it does not source a panel or send outreach. Screen capture is not available on every browser or mobile device; those interviews continue with audio and in-page events. Treat permission failures, interrupted sessions, connectivity problems, weak sample coverage, and other capture gaps as explicit evidence limitations.

Preserve the boundary between source material, observed facts, generated interpretation, and delivery decisions.

## Choose the access path

1. Prefer the configured UserTold MCP server when its tools or resources are available.
2. Otherwise use the `usertold` CLI when terminal access is available.
3. If neither path is ready, ask the user to connect `https://mcp.usertold.ai/mcp` or approve installation of the published CLI. Never ask them to paste an access token into chat or a committed file.
4. Discover the live surface before acting. For MCP, inspect the current tools, resources, and prompts. For CLI, run `usertold --help --json` and the relevant group help.

Read [references/access.md](references/access.md) for concrete MCP resources, tool families, CLI commands, and recovery steps.

## Route short requests

Treat a short request as the desired outcome, not permission to inspect everything. Choose one route and keep discovery proportional.

### Bootstrap a product

1. In a repository, read at most two authoritative product documents by default, such as `README.md` and a PRD or product vision. Do not scan implementation files unless a missing fact blocks the research plan.
2. Read UserTold organization and project resources before writing. Reuse an existing matching Project; never create a duplicate.
3. Create one Project when the user asks for setup, then propose the smallest useful set of draft Studies. Do not create or activate the Studies when the request only asks for a plan.
4. Separate first-time comprehension from experienced workflow research when those audiences face different decisions.

### Configure and install Studies

1. Use `$usertold-recruit-participants` when the request names audiences, invitations, placement, or outreach.
2. If the user names audiences but not routes, derive the smallest truthful placement from product documentation and routing: the public entry surface for new visitors and the primary authenticated workflow for experienced users. State any coverage limitation instead of inventing tenure or identity signals.
3. Inspect existing Studies before creating anything. Reuse or update an intended draft instead of duplicating it.
4. Define one research question and audience per Study, validate every script, then create the Studies as drafts.
5. Activate only when the user explicitly asks for activation or approves the shown configuration.
6. Retrieve the install-once snippet from `projects.ge

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 4 — file references are metadata, not package contents.

View saved version →

---
name: usertold-recruit-participants
description: Plan participant recruitment for a UserTold Study and produce participant-readable recruitment copy plus canonical Invitation, Visibility, and neutral Intake inputs. Use when choosing whom to invite, comparing outreach channels, setting an honest reward, drafting an in-product launcher or direct-link invitation, screening without revealing qualifying answers, or translating an existing recruitment plan into UserTold configuration. Do not use to send outreach, source a participant panel, fulfill rewards, claim representative sampling, or provide legal advice.
---

# Recruit UserTold Participants

Turn a research question into a small, truthful recruitment plan for people the team can already reach. Recruitment is distribution into a UserTold Study, not a marketing funnel.

## Scale to the request

For a short in-product setup request, do not automatically expand into a full outreach campaign, reward plan, or Intake. If the user names audiences and routes, preserve those boundaries. If they name audiences but not routes, derive the public entry surface and primary authenticated workflow from the smallest authoritative product context, then state the coverage limitation. Produce only the Invitation, Visibility, and safeguards needed to create the Studies. Inspect the host application only when an exact route is required for installation. Ask only for information that blocks a truthful configuration.

Use the full recruitment packet below when the user asks how to reach, qualify, reward, or invite participants beyond the in-product placement.

## Establish the participant boundary

1. State the behavior or recent experience that makes someone relevant. Prefer “attempted checkout in the last 30 days” over a persona label.
2. State exclusions that protect the research question, participant safety, conflicts, and duplicate participation. Do not add demographic filters without a study-specific reason.
3. Name the reachable population and the resulting coverage limit. Never call a convenience sample representative.
4. Record whether recontact is needed as a separate, optional consent choice.

## Choose distribution

Read [references/channel-selection.md](references/channel-selection.md), choose one primary channel, and name one meaningfully contrasting channel. Explain why each reaches the target behavior and add one explicit sampling-bias sentence.

Email and CRM are distribution only: special URL → expanded Invitation → explicit **Start**. The participant must select Start before permissions or recording. A link is never consent. Do not claim UserTold sends email, operates a CRM, or personalizes the link to an identity.

Track source with channel-level `utm_source`, `utm_medium`, and `utm_campaign` values where the host flow preserves them. Use campaign labels, not personal data. Report response and completion by source without turning the result into a representative-sample claim.

## Set the offer

Read [references/rewards.md](references/rewards.md). State all four terms exactly:

- duration;
- reward or “No reward”;
- eligibility, including gift restrictions or alternatives;
- delivery timing and method, or “Not applicable.”

About $80/hour is marketplace orientation for human-moderated consumer interviews, not a universal rate or a calculator. AI-moderated and short in-product interviews normally use a smaller fixed reward. Participant copy must show the actual promise, such as “20 minutes · $25 gift card.” UserTold records the promise; it does not fulfill payment.

## Select presentation and timing

Choose one `presentation_mode`:

- `passive`: a compact launcher the participant opens; use for voluntary feedback or a standing bug-report route.
- `contextual`: show an expanded panel on a relevant product route; use when current product context matters.
- `direct_link`: distribute the generated `recruitment_url`; use for email, CRM, community posts, or a targeted new-feature tes

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 4 — file references are metadata, not package contents.