Userflow

View saved version →

---
name: userflow-adoption-agent-topics
description: Read what people actually asked a Userflow Adoption Agent over a time window (default last 30 days) and turn it into a shareable HTML report of plainly-named topics, split into what the agent couldn't answer, what got thumbs-down, and what came up most — every topic expandable to the real conversations behind it. Use this skill whenever a user with the Userflow MCP connected asks "what are people asking the agent", "what are the top topics in the Adoption Agent", "what is the assistant failing to answer", "where is the agent getting negative feedback", "cluster our agent conversations", "analyse Adoption Agent questions", "what are the knowledge gaps in our agent", "summarise AI assistant conversations", or wants any topic, theme, cluster, gap, or failure analysis of an Adoption Agent / AI Assistant / assistant flow. Also trigger when a picker widget from this skill sends a prompt like "Build the Adoption Agent topic report for ... over ...". Requires the Userflow MCP connector.
---

# Userflow Adoption Agent topic report

Turn an Adoption Agent's raw conversation log into a report a PM or support lead can act on: a set of clearly-named topics, sorted into the three questions people actually want answered — **what is the agent failing to answer, what is it getting yelled at for, and what does it get asked most** — with every topic opening up to the real conversations underneath.

The audience is anyone running an Adoption Agent, not just analysts. So topic names have to read like something a colleague would say out loud, and every number has to be traceable to conversations the reader can inspect.

## Requirements

The **Userflow MCP connector** must be connected. If it isn't, say so and stop — there is no useful fallback.

## The flow at a glance

1. **Pick the agent and window** — one picker widget; assistant flow names are heavily duplicated, so never resolve by name alone.
2. **Size the job** — one analytics call gives denominators and tells you how much to pull.
3. **Pull the conversations** — three paginated pulls (disliked, unanswered, general).
4. **Cluster it yourself** — from what users actually wrote. Do not inherit the API's topic model.
5. **Build the report** — one self-contained HTML artifact with expandable topics.
6. **Write insights** — a few paragraphs of prose after the artifact, never inside it.

Read `references/api-notes.md` before the first data call. It documents the field semantics and pagination traps that will otherwise silently corrupt the report — several of them look like working data until you check. Read `references/artifact-template.md` at step 5.

---

## Step 1 — Pick the agent and the window

Call `describe_session` for `env_id`. Default to Production; only ask if the account has several plausible environments and the user hasn't said.

Call `list_flows` with `types: "assistant"`. Expect a lot of them, mostly drafts — real accounts accumulate test copies. **Names repeat**: an account can hold three flows called "Userflow Adoption Agent" and four called "Userflow AI Assistant". Resolving by name would silently analyse an abandoned draft, so the picker exists to make the user choose a specific UUID.

Render a picker widget (Visualizer, `interactive` module): the assistant flows as selectable rows, published first, then by `edited_at` descending. Each row needs enough to disambiguate identically-named flows — state, publication count, last edited date, and the first 8 characters of the UUID. Add window chips (7 / 30 / 90 days / custom, default **30 days**) and a "Build topic report ↗" button whose `sendPrompt` carries the flow name, UUID, and window. Then end the turn.

Flows with `total_publications: 0` have almost certainly never taken traffic. Keep them selectable but visually de-emphasised, so someone who wants a draft can still pick one and get an honest empty report rather than being blocked.

## Step 2 — Size the job before pulling

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

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

View saved version →

---
name: userflow-announcement-creator
description: Create an in-app announcement in Userflow through a guided, conversational flow — gather context (a short summary, OR a linked doc/ticket via a connected MCP or Cowork, OR pasted content), draft and refine the copy with the user, set the notification level (silent / badge / boosted → pop-out, modal, or notification), optionally target specific users, show a confirmation card, create the unpublished draft via the Userflow MCP, hand back the Builder link, and offer to publish. Use this whenever a user with the Userflow MCP connected wants to "create an announcement", "announce a feature / update / release / fix", "post an in-app announcement", "draft an announcement", "let users know about X in Userflow", or turn a release note / changelog entry / Jira ticket / Notion doc into a Userflow announcement. Requires the Userflow MCP connector.
---

# Userflow Announcement Creator

Guide the user from a rough idea (or a linked doc/ticket) to a finished, ready-to-publish
Userflow announcement. This is a **conversational, step-by-step** skill: move through the phases
below in order, and **pause for the user at each ✋ checkpoint** — never barrel ahead and create or
publish anything without an explicit yes.

The single most important habit: **create is not publish**. `create_flow` only saves an unpublished
draft and returns a Builder link. Nothing is live until the user confirms and you call
`set_flow_publication`. When in doubt, do less and ask.

## Before you start

1. Confirm the **Userflow MCP** is connected (its tools are available). If not, tell the user this
   skill needs the Userflow connector and stop.
2. Resolve the **environment**. Call `describe_session` to list environments. If there's exactly
   one, use it. If there are several (e.g. production vs. a test env), ask which one this
   announcement is for, and pass that `env_id` on every subsequent Userflow call that accepts it.
   Default to the user's usual working environment if they've made it clear in conversation.

Don't over-explain the plumbing — a brief "Which environment — production?" is enough.

---

## Phase 1 — Gather the context

Ask the user for the source material, offering three ways to provide it:

> "What's this announcement about? You can give me a short summary, share a link to a doc or ticket
> that has the context (Notion, Jira, a Google Doc, etc.), or just paste the content in."

**If they share a link**, fetch it with the matching connected tool — Notion for a Notion page,
the Atlassian tools for a Jira issue or Confluence page, Google Drive for a Doc, Intercom, etc., or
`web_fetch` for a public URL. In Cowork, read an attached/linked file directly. If you can't access
it (no connector, permissioned, returns nothing), say so plainly and ask them to paste the relevant
part instead — don't guess at the contents.

**If they give a summary or paste text**, work from that.

Pull out what an announcement needs: what changed, who it's for, why it matters, and any link or
action users should take. If something important is missing (e.g. there's no obvious user benefit),
ask one short follow-up rather than inventing it.

---

## Phase 2 — Draft and refine the copy

Write the announcement as a **title** plus a short **body**. Keep it clear, specific, and benefit-led
— lead with what the user gets, not internal jargon. If the `userflow-brand-copy` skill is
available, follow its voice rules; otherwise default to concise, friendly, plain language.

✋ **Show the draft and get a read on it.** Present the title and body in the chat (plain, readable —
not raw JSON) and ask:

> "Here's a first draft. Does this capture it? Want any changes to **tone**, **length**, or
> **messaging**?"

Iterate until the user is happy. Small, fast loops beat one giant rewrite. Only move on once they've
confirmed the copy is good.

> Note: image handling is intentionally out of scope for this skill. If the user asks for an image,
> tell

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

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

View saved version →

---
name: userflow-banner-creator
description: Create an in-app banner in Userflow through a guided, conversational flow — gather context from a short summary, pasted content, attached file, public page, or linked document/ticket in a connected app; draft and refine short banner copy; add an optional CTA; configure placement and behavior; optionally target users; show a confirmation card; create an unpublished draft through Userflow MCP; return the Builder link; and offer to publish. Use whenever a user with Userflow MCP connected asks to create or add an in-app banner, announce maintenance, a promotion, or an update in a page-top or page-bottom bar, or turn a note, ticket, or document into a Userflow banner. Requires the Userflow MCP connector.
---

# Userflow Banner Creator

Guide the user from a rough idea (or a linked doc/ticket) to a finished, ready-to-publish Userflow
**banner** — a bar embedded directly into their app's page. This is a **conversational, step-by-step**
skill: move through the phases in order and **pause at each ✋ checkpoint**. Never create or publish
without an explicit yes.

The core habit, same as any content-creation flow: **create is not publish**. `create_flow` saves an
unpublished draft and returns a Builder link; nothing is live until the user confirms and you call
`set_flow_publication`.

## How banners differ from announcements

Banners embed **directly into the page DOM**, so — unlike announcements — there is **no notification
level** (silent/badge/boosted) and **no Resource Center dependency**. The banner-specific choices are
**placement** (where it sits) and **behavior** (sticky / overlay / animate). Copy should be **short —
one line is ideal**.

## Before you start

1. Confirm the **Userflow MCP** is connected. If not, say so and stop.
2. Resolve the **environment** via `describe_session` (e.g. Production vs. Staging). One env → use it;
   several → ask which. The banner *draft* is account-level, but you'll need the env for the
   live-banner priority check and for publishing.

---

## Phase 1 — Gather the context

Ask for the source material, offering three ways:

> "What's the banner for? Give me a short summary, share a link to a doc or ticket with the context
> (Notion, Jira, a Google Doc, etc.), or paste the content in."

If they share a **link**, use the matching connected app for private content (for example Notion,
Atlassian for Jira/Confluence, or Google Drive), use browser or web access for a public page, and read
files attached to the current task directly. If the required app is unavailable or access fails, say
so and ask them to paste the relevant text. If they give a summary or pasted text, work from that.

Banners carry one short message and maybe one action — pull out the single thing users need to know
and any link/action they should take.

---

## Phase 2 — Draft and refine the copy

Write **short** banner copy — ideally one line. Lead with the point; cut everything else. If a
bundled Userflow brand-copy skill is available, follow its voice rules; otherwise use concise,
direct, friendly product copy and preserve any tone requirements the user provides.

✋ Show the draft (plain, readable — not JSON) and ask:

> "Here's the banner text. Good? Want changes to tone, length, or wording? And should it have a
> **button** — e.g. 'Learn more' linking somewhere, or a 'Dismiss' button?"

If they want a CTA, capture the button text and its action — most commonly **navigate** to a URL, but
also **start a flow**, **dismiss** the banner, track an event, or set an attribute. See
`references/mcp-reference.md` → *Buttons*. Iterate until the copy and button are right.

---

## Phase 3 — Placement and behavior

Banners always need a placement. **Always ask** (offer it as a dropdown of choices):

- **Top of page** → `embed_mode: "body_first"`
- **Bottom of page** → `embed_mode: "body_last"`
- **Anchor to a specific element** → hand off to the Builder (see below)

**Element-anchored placement i

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

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

View saved version →

---
name: userflow-flow-compare
description: Compare two Userflow flows of the same type side by side in an interactive dashboard — views, completions, completion rate, step-funnel drop-off, missing element errors, trends, and improvement insights. Use this skill whenever the user with the Userflow MCP connected asks to "compare flows", "compare these two flows/announcements/checklists", "which flow performs better", "flow A vs flow B", "benchmark my onboarding flows", or wants any head-to-head performance comparison of Userflow content. Also trigger when a picker widget from this skill sends a prompt like "Compare these two ... flows over ... Build the comparison dashboard". Requires the Userflow MCP connector.
---

# Userflow flow compare

Compare two flows of the same type over a chosen date range, producing an inline comparison dashboard with metrics, funnels, trends, and insights.

The interaction has two phases, usually across two turns:
1. **Picker phase** — fetch all flows, render an interactive picker (type → two searchable flow dropdowns → date range → Compare button).
2. **Dashboard phase** — triggered by the picker's resulting prompt (or by a user who names both
   flows directly), pull analytics and render the comparison dashboard plus written insights.

If the user already named two flows and a range in their message, skip the picker and go straight to the dashboard phase (resolve names via `list_flows` with `flow_name` and verify both are the same type; if types differ, say so and re-render the picker pre-scoped so they can fix one or both).

## Setup (both phases)

1. Confirm the connected Userflow MCP exposes `list_flows`, `describe_session`, `query_flow_metrics`,
   `query_usage_metrics`, and `get_flow_details`. If required analytics tools are unavailable, say so
   and stop before promising a dashboard.
2. Call `describe_session` once to get `env_id`. Default to the Production environment; only ask the user if there are multiple non-obvious environments.

## Phase 1 — picker

1. Call `list_flows` with `list_all_flow_types: true`, `state: "published"`, `order_by: "edited_at"`, `order_dir: "desc"`. Keep `id`, `name`, `type`, and `first_published_at` for each flow (store `first_published_at` — you need it later for window-clipping warnings).
2. **Exclude** `tracker` (event trackers, no session funnel) and `assistant` (Adoption Agent has its own analytics) from the comparable set. Comparable types: `flow`, `checklist`, `announcement`, `launcher`, `banner`, `resource_center`.
3. Render a searchable interactive picker when that capability is available. Otherwise show a concise
   text list grouped by type and ask the user to choose two flows plus a date range. Follow the picker
   behavior in `references/dashboard-templates.md`:
   - Flow type dropdown first, with per-type published counts. Changing type clears both selections.
   - Two searchable dropdowns (text input + filtered list) scoped to the selected type — this makes a type mismatch impossible by design. A flow selected in one dropdown is hidden from the other.
   - Date range chips: Last day, Last 1 week, Last 15 days, Last 1 month, Last quarter, Last 6 months, Last year. Default: Last 1 month.
   - Keep the compare action disabled until both flows are chosen. The resulting prompt must include
     both names, UUIDs, type, and selected range.
4. End the turn after rendering — the selection arrives as the next user message.

## Phase 2 — data pull

Map the range to `last_n_days`: day→1, 1 week→7, 15 days→15, 1 month→30, quarter→90, 6 months→180, year→365. Pick `interval`: `day` when ≤31 days, `week` when ≤180, `month` otherwise.

Make exactly these calls:

1. `query_flow_metrics` with `flows: [id1, id2]`, `env_id`, `last_n_days`, `include_time_series: true`, `interval`, and `include_steps: true` (steps only return for guide flows; harmless otherwise). **On a 408 timeout, retry once with identical parameters** — retries routinely succeed. If the retry also

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

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

View saved version →

---
name: userflow-flow-segment-compare
description: Compare how a single piece of Userflow content performs across several audience segments, rendered as a dashboard — a key-metrics comparison table plus trend charts. Works for ANY Userflow flow type (guide flows, announcements, banners, checklists, launchers, resource centers, embeds), not just flows and announcements. Content is chosen from a searchable dropdown; the "segments" are whatever the user wants to compare — existing account segments, ad-hoc filters built just for this analysis, or a mix — and ad-hoc ones are never saved to the account. Use whenever a user with the Userflow MCP connected wants to "compare a flow/announcement/banner across segments", "how does [content] perform for [group A] vs [group B]", "break down [content] by audience/user type", or any per-audience performance breakdown of one piece of content. Different from userflow-flow-compare (two flows head-to-head) — here it's ONE piece of content across MANY audiences. Requires the Userflow MCP connector.
---

# Userflow Content × Segment Compare

Take **one** piece of Userflow content — any flow type — and show how it performs across **several
audiences**, ending in a dashboard: a **comparison table** of key metrics and **trend charts** of
those metrics, one line per segment. Conversational and step-by-step — **pause at each ✋ checkpoint**.

Hold onto three things:
- **Any content type.** Guide flows, announcements, banners, checklists, launchers, resource centers,
  assistants, trackers, embeds — all are "flows" with a `type` in Userflow. The metrics adapt to the
  type (see `references/mcp-metrics.md`).
- **"Segment" is loose.** A real account segment, or an ad-hoc filter the user describes just for this
  comparison. **Never create ad-hoc segments on the account** — they're query-time predicates only.
- **Read-only.** This skill only reads analytics; it writes nothing to Userflow.

## Before you start

1. Confirm the **Userflow MCP** is connected. If not, say so and stop.
2. Resolve the **environment** via `describe_session` (default to **Production** for analytics unless
   told otherwise); pass its `env_id` on every analytics call.

---

## Phase 1 — Pick the content (searchable dropdown)

Don't make the user type an exact name. Fetch the content and let them **pick from a searchable
dropdown**.

1. Call `list_flows` broadly — `list_all_flow_types: true`, `state: "published"` (published content is
   what has analytics), ordered by `edited_at` desc. Each item carries `name`, `type`, and `id`.
2. Render a **searchable dropdown picker** as an interactive widget (same pattern as the
   `userflow-flow-compare` picker): a search box plus a filterable list of items, each showing the
   **name** and a **type badge** (Flow / Announcement / Banner / Checklist / …). On selection, the
   widget sends a prompt back to continue (e.g. "Analyze '<name>' [<id>] across segments"). If an
   interactive widget can't render, fall back to a concise text list grouped by type for the user to
   pick from.
3. **Capture the content type** from the chosen item — it decides the metric set. Confirm the resolved
   name + type back to the user.

---

## Phase 2 — Which segments to compare?

Now ask what audiences to compare (aim for 2–5 for a readable dashboard). For **each** one, it's
either:

- **An existing account segment** — call `list_segments` (`subject_type: "user"`) and let the user
  pick (a searchable/multi-select picker works well here too, or a simple list). Reference it as a
  `{ "type": "segment", "segment_id": "<uuid>" }` predicate.
- **An ad-hoc filter** — the user describes it in plain language; you translate it into
  attribute/event predicates. **Resolve real FQNs / event names first** (`list_attribute_definitions`,
  `list_event_definitions`) — never invent them.

A mix of existing + ad-hoc is fine. Collect them all before moving on.

**One real constraint:** these analytics predicates are **user-scoped

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

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

View saved version →

---
name: userflow-nps-summariser
description: Summarise the positive and negative comments from a Userflow NPS survey over a chosen time frame, with expandable user lists showing each respondent's comment and score. Use this skill whenever the user with the Userflow MCP connected asks to "summarise NPS", "summarise NPS feedback/comments", "what are people saying in our NPS", "NPS comment summary", "group NPS feedback", or anything about reading, digesting, or theming NPS survey responses. Also trigger when a widget from this skill sends a prompt like "Summarise NPS feedback for ... over ...". Requires the Userflow MCP connector.
---

# Userflow NPS summariser

Summarise what respondents wrote in an NPS survey — positive and negative comment themes with expandable per-user lists (comment + score). The output is deliberately comment-only: no NPS score card, no promoter/passive/detractor split, no trend chart.

Interaction, usually across three turns:
1. **Link** — ask for the NPS flow's Userflow link, extract the flow ID, verify it's genuinely an NPS survey.
2. **Time frame** — render an interactive time-range picker when available, with a text fallback.
3. **Summary** — pull raw responses, join and classify, create a portable comment-summary report,
   and add written insights.

If the user's first message already contains a link (or flow name) and a time frame, collapse the phases: verify, then go straight to the summary.

## Setup

1. Confirm the connected Userflow MCP exposes `list_flows`, `describe_session`,
   `list_flow_survey_questions`, and `list_survey_responses`. If required tools are unavailable, say
   so and stop before promising a report.
2. Call `describe_session` once for `env_id`. Default to Production; ask only if multiple non-obvious environments exist.

## Phase 1 — link and verification

Userflow has **no `nps` flow type** — the `types` filter silently ignores the value and returns everything. NPS surveys are regular flows containing an NPS question block, and flow names lie in both directions (a flow named "Trial Prompt: NPS Survey" may contain zero questions; a survey may lack an NPS block). So never trust names; always verify.

1. Ask the user to paste the flow's link from the Userflow app (e.g. `https://app.userflow.com/app/<slug>/flows/<uuid>/builder`). Extract the UUID from the path. If they give a name instead, resolve it via `list_flows` with `flow_name` and confirm the match.
2. Call `list_flow_survey_questions` with the flow ID. Verify a question with `type: "nps"` exists. Capture:
   - the NPS question's `cvid` and `name`
   - every text-type question (`text`, `multiline_text`) — these are the comment sources; note their names (they reveal the flow's branching, e.g. separate "Passive feedback" and "Detractor feedback" questions)
   - whether any feedback question exists for promoters — many flows don't have one, which matters for the summary
3. If no `nps` question is found, tell the user plainly what the flow actually contains (its question types, or that it has none) and ask for a different link. Do not proceed on a name match alone.

## Phase 2 — time frame

Render an interactive picker when available: show the verified flow name, choices for Last 1 week /
15 days / 1 month / quarter / 6 months / year (default: quarter), and a Summarise action whose
resulting prompt includes the flow name, UUID, and chosen range. If interactive controls are
unavailable, present the same ranges in text and ask the user to choose one. End the turn.

## Phase 3 — data pull and joining

Map the range to a start date. **Both survey tools require full ISO 8601 datetimes** — bare dates like `2026-04-21` are rejected. Use `2026-04-21T00:00:00Z` / `2026-07-20T23:59:59Z` forms.

1. Call `list_survey_responses` with `flow_id`, `env_id`, `start_date`, `end_date`, `limit: 500`. Do **not** call `get_nps_breakdown` — the score summary is out of scope by design.
2. The result is one row per question per session. Join rows by

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

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

View saved version →

---
name: userflow-segment-creator
description: Create a condition (filter-based) segment in Userflow through a guided, conversational flow — pick user vs. company, describe the audience in plain language, translate it into real attribute/event predicates (looked up, never invented), show the conditions in a simple inline card for confirmation, name it, and create it via the Userflow MCP. Use this whenever a user with the Userflow MCP connected wants to "create a segment", "build an audience", "make a user/company segment", "segment users who…", "define a group of users/companies by conditions", or filter their audience by attributes or behavior. Requires the Userflow MCP connector. Note — the MCP only creates condition segments; manual/list (CSV-uploaded) segments are not supported and must be imported from the Userflow dashboard.
---

# Userflow Segment Creator

Guide the user from a plain-language audience description to a live **condition segment** in Userflow.
This is a **conversational, step-by-step** skill: move through the phases in order and **pause at each
✋ checkpoint**. Never create the segment until the user has seen the conditions and said yes.

## Scope (read first)

The Userflow MCP's `create_or_update_segment` creates **condition (filter) segments only** — segments
defined by attribute/event rules that evaluate membership automatically. It **cannot** create
**manual/list segments** (a fixed set of users uploaded from a file); there is no MCP tool to import
members or set attributes. If the user wants a manual/CSV-based segment, say so plainly and point them
to the Userflow dashboard's CSV import (or the REST Identify API) — then offer to help with a condition
segment instead. Don't try to fake it with a giant list of OR'd equals; that hits the nesting budget
and isn't what they want.

## Before you start

Confirm the **Userflow MCP** is connected (its tools are available). If not, tell the user this skill
needs the Userflow connector and stop. Segments are account-level, so no environment needs to be
chosen to create one (an optional match-count preview later is per-environment — handle that then).

---

## Phase 1 — User or company segment?

Ask up front, because it decides which attributes are even valid:

> "Is this a **user** segment or a **company** segment?"

This sets `subject_type` (`"user"` or `"company"`) and constrains predicates — see
`references/mcp-reference.md` → *Subject-type scoping*. In short: a **company** segment can only use
company attributes (`group/…`); a **user** segment can use user attributes, company attributes, and
company-membership attributes.

---

## Phase 2 — Describe the conditions

Ask the user to describe the audience in plain language:

> "Describe who should be in it — e.g. 'companies on an active subscription in the EU', or 'users who
> haven't completed onboarding and were last seen over 30 days ago'."

Then translate it into predicates. **Resolve real identifiers first — never invent them:**

- `list_attribute_definitions` (scope matching the subject type) → exact attribute FQNs and their
  `data_type`. Company attributes use the `group/` prefix.
- `list_event_definitions` → valid `event_name` values, if the description involves behavior.
- Build the predicate array per `references/mcp-reference.md` → *Building the conditions*.

Two things that silently break segments, so get them right:
- **Data types.** String `"true"` ≠ boolean `true`; a number stored as text won't match a numeric
  comparison. Match the attribute's real `data_type`.
- **No nested segment references.** `create_or_update_segment` rejects `type: "segment"` predicates
  anywhere in the tree. If the user says "everyone in segment X plus …", you can't nest X — expand the
  intent into attribute/event rules, or tell them that part can't be combined this way.

If the description is ambiguous ("active" = subscribed, or recently seen?), ask one short clarifying
question rather than guessing.

---

## Phase 3

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

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