creating-surveys

Files (3)

• SKILL.md
• examples.md · references/
• response-rates.md · references/

SKILL.md (first lines)

# Creating surveys

Create a useful draft from the user's goal, then verify its audience and delivery
before launch. The workflow can run through MCP without opening the survey editor.

## Choose the delivery and questions

Infer the name, purpose, and questions from the request. Ask only for missing
information that changes who receives the survey or how it is delivered.

| User's goal                             | Survey type       | Delivery requirement                                 |
| --------------------------------------- | ----------------- | ---------------------------------------------------- |
| Feedback inside an app                  | `popover`         | A supported PostHog SDK with surveys enabled         |
| Always-available feedback button        | `widget`          | SDK support and a widget configuration               |
| A shareable hosted form                 | `external_survey` | A hosted survey link; no in-app targeting            |
| A custom form built in application code | `api`             | The app renders questions and captures survey events |

Inspect the current tool schema for question types, scales, branching,
and translations instead of guessing their JSON shapes. Minimal starting points
are in [examples](references/examples.md).

### Design for responses

These choices go with higher response rates in in-app surveys. Apply the
question advice by default. Recommend the trigger and audience advice, and ask
before adding a trigger or audience the user did not request, since both change
who receives the survey. The evidence and its limits are in
[response rates](references/response-rates.md).

- **Trigger on the moment you are asking about.** Recommend showing the survey
  after the event that marks it, such as a completed checkout or a used feature,
  through `conditions.events`. Event-triggered surveys get about twice the
  responses of page-based ones. A URL condition alone does about as well as
  showing the survey on every page. Confirm the event exists in the project
  before using it.
- **Make the first question one click.** Start with a single choice or a short
  rating. Surveys that open with an open-text question get about a fifth of the
  responses. Ask "why" in an optional open question after it.
- **Keep it short.** About 4 in 10 people who start a two- or three-question
  survey stop before the end. Prefer one to three questions unless the user
  requests more.
- **Turn partial responses on** with `enable_partial_responses: true`, so the
  first answer is kept when someone stops. It defaults to off when a survey is
  created through the API.
- **Recommend a targeted audience.** Surveys shown to a person or cohort
  audience get more responses than surveys shown to everyone.
- **Keep any popup delay under 15 seconds.** Longer delays go with fewer
  responses.

Survey names, questions, and appearance text are public content. Do not copy
private customer details into them without making that visibility clear first.

## Verify the audience and appearance

- Use `conditions` for URL, event, device, and linked-flag-variant conditions.
  Resolve existing event and flag identifiers before using them. A URL condition
  does not define a person or cohort audience.
- Use `targeting_flag_filters.groups[].properties[]` for person, group, or cohort
  targeting. Groups are alternative rules; properties within a group must all
  match. Preserve the intended audience when translating the request.
- Cohorts containing behavioral filters cannot be used directly for survey
  targeting. Explain the restriction and offer a supported static snapshot or
  another equivalent audience definition. A snapshot does not update with the
  original cohort. Get agreement before making that tradeoff; never drop a rule
  or broaden the audience to make a failed request pass.
- Hosted forms (`external_survey`) do not use in-app display conditions or
  targeting flags. Do not attach those fields to a hosted form.
- Omit `appearance` unless customization is needed. `whiteLabel: true` requires
  the organization's white-labelling entitlement (Enterprise). Do not infer it
  from a request for custom colors. Verify entitlement before setting it.
  `surveyPopupDelaySeconds` must be non-negative.
- Leave optional fields unset when unused. Do not fill them with `null` as a
  substitute for omission; question fields and nested objects have different
  nullability rules.

## Create and review the draft

Call `posthog:survey-create` with the resolved configuration. Omit `start_date`
for a draft. If the user already asked for immediate launch, continue through
the readiness check and launch without asking for the same approval again.

Keep the returned survey `id`. Subsequent survey tools use `id`, not a question
ID, feature flag ID, or survey name.

Read the saved survey with `posthog:survey-get`. Review the questions, type,
audience, schedule, response limit, and branding with the user. Show the MCP
survey app when the client supports it; otherwise give a concise text review.
Always include the returned `_posthogUrl`. A saved configuration is not evidence
that an in-app popup has rendered successfully.

For changes, call `posthog:survey-update` after fetching the saved survey.
Questions, conditions, appearance, targeting, and translations may replace
nested values. Preserve unchanged fields and existing question IDs, which link
questions to collected responses. Omit IDs only for new questions.

## Launch and verify delivery

Before `posthog:survey-launch`, confirm:

- The user authorized launch for the reviewed audience and configuration.
- The survey is not archived and has no `end_date` in the past. If reopening an
  existing survey, unarchive it or clear/extend its end date only as authorized.
- For in-app delivery, surveys are enabled in the project and the app's SDK
  supports the requested features. Event-triggered surveys need the actual
  triggering event in the app. Creating an event name in configuration does not
  instrument that event.
- For `api` surveys, the application implementation handles display and event
  capture. Creating and launching the definition does not implement that code.

Use `posthog:survey-launch` with `id`, then verify the returned state. Report
whether the survey is a draft, launched, or awaiting an SDK/setup step. For hosted
forms, return a verified public form URL when available; `_posthogUrl` is the
management page and is not a respondent link.

Use `posthog:survey-stats` or `posthog:surveys-responses-list` to check subsequent
activity. Zero responses immediately after launch do not prove delivery failed.
For a survey that should have been shown, follow `debugging-surveys`.

## Recover from errors

From PostHog/skills, MIT.