Update to Userflow

{
  "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.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 511
    },
    {
      "relative_path": "references/dashboard-spec.md",
      "size_in_bytes": 3487
    },
    {
      "relative_path": "references/mcp-metrics.md",
      "size_in_bytes": 4558
    }
  ],
  "skill_md_contents": "---\nname: userflow-flow-segment-compare\ndescription: 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.\n---\n\n# Userflow Content × Segment Compare\n\nTake **one** piece of Userflow content — any flow type — and show how it performs across **several\naudiences**, ending in a dashboard: a **comparison table** of key metrics and **trend charts** of\nthose metrics, one line per segment. Conversational and step-by-step — **pause at each ✋ checkpoint**.\n\nHold onto three things:\n- **Any content type.** Guide flows, announcements, banners, checklists, launchers, resource centers,\n  assistants, trackers, embeds — all are \"flows\" with a `type` in Userflow. The metrics adapt to the\n  type (see `references/mcp-metrics.md`).\n- **\"Segment\" is loose.** A real account segment, or an ad-hoc filter the user describes just for this\n  comparison. **Never create ad-hoc segments on the account** — they're query-time predicates only.\n- **Read-only.** This skill only reads analytics; it writes nothing to Userflow.\n\n## Before you start\n\n1. Confirm the **Userflow MCP** is connected. If not, say so and stop.\n2. Resolve the **environment** via `describe_session` (default to **Production** for analytics unless\n   told otherwise); pass its `env_id` on every analytics call.\n\n---\n\n## Phase 1 — Pick the content (searchable dropdown)\n\nDon't make the user type an exact name. Fetch the content and let them **pick from a searchable\ndropdown**.\n\n1. Call `list_flows` broadly — `list_all_flow_types: true`, `state: \"published\"` (published content is\n   what has analytics), ordered by `edited_at` desc. Each item carries `name`, `type`, and `id`.\n2. Render a **searchable dropdown picker** as an interactive widget (same pattern as the\n   `userflow-flow-compare` picker): a search box plus a filterable list of items, each showing the\n   **name** and a **type badge** (Flow / Announcement / Banner / Checklist / …). On selection, the\n   widget sends a prompt back to continue (e.g. \"Analyze '<name>' [<id>] across segments\"). If an\n   interactive widget can't render, fall back to a concise text list grouped by type for the user to\n   pick from.\n3. **Capture the content type** from the chosen item — it decides the metric set. Confirm the resolved\n   name + type back to the user.\n\n---\n\n## Phase 2 — Which segments to compare?\n\nNow ask what audiences to compare (aim for 2–5 for a readable dashboard). For **each** one, it's\neither:\n\n- **An existing account segment** — call `list_segments` (`subject_type: \"user\"`) and let the user\n  pick (a searchable/multi-select picker works well here too, or a simple list). Reference it as a\n  `{ \"type\": \"segment\", \"segment_id\": \"<uuid>\" }` predicate.\n- **An ad-hoc filter** — the user describes it in plain language; you translate it into\n  attribute/event predicates. **Resolve real FQNs / event names first** (`list_attribute_definitions`,\n  `list_event_definitions`) — never invent them.\n\nA mix of existing + ad-hoc is fine. Collect them all before moving on.\n\n**One real constraint:** these analytics predicates are **user-scoped**, so existing segments you\nreference must be **user** segments. A company-level idea (e.g. \"EU companies\") is still fine — express\nit as a user predicate on a company attribute (`group/region = eu`); just don't pass a *company*\nsegment id. See `references/mcp-metrics.md` → *Scoping*.\n\n---\n\n## Phase 3 — Review the segments (before pulling any data)\n\n✋ Show the assembled comparison set as a **readable card** (not JSON):\n\n- The **content** being analyzed (name + type)\n- Each **segment**: its label, and either \"existing segment\" or the ad-hoc conditions in plain English\n  (Field · Operator · Value)\n- The **time window** and **interval** (propose a default: **last 90 days, weekly**; offer day/week/\n  month and a different range)\n\nAsk: \"Compare these against **[content]** over **[window]**? I can add, drop, or edit any segment.\"\nRemind them ad-hoc segments won't be saved to the account. Iterate until they're happy.\n\n---\n\n## Phase 4 — Pull the metrics\n\nFor **each** segment, call `query_flow_metrics` on the single content id, scoped by that segment's\npredicates, with the time series on:\n\n```\nquery_flow_metrics(\n  flows: [\"<content-id>\"],\n  predicates: [ <that segment's predicates> ],\n  include_time_series: true,\n  interval: \"<day|week|month>\",\n  last_n_days: <n>,          // or start_date/end_date\n  env_id: \"<env>\"\n)\n```\n\nIt returns the segment's `metrics` and a `time_data` array for trends, and works across content types.\n**Read the metric keys actually returned and adapt** — completion-type content (guide flows,\nchecklists) leads with a completion rate; seen/engagement-type content (announcements, banners,\nlaunchers, embeds, resource centers) leads with views and its primary engagement metric. See\n`references/mcp-metrics.md` for the per-type guidance and zero-data handling. Collect one result per\nsegment.\n\n---\n\n## Phase 5 — Build the dashboard\n\nProduce a **self-contained HTML dashboard** (a file artifact). Follow\n`references/dashboard-spec.md` for the portable visual and interaction contract. At minimum:\n\n1. **Header** — content name, type, time window, and the segments compared.\n2. **Comparison table** — one row per segment, columns = the key metrics for this content type (chosen\n   from what `query_flow_metrics` returned). Make the best/worst per column easy to spot.\n3. **Trend charts** — for each key metric, one multi-series line chart with **one line per segment**\n   over the shared time buckets.\n\nFlag any low-sample or zero-data segment so a flat line isn't misread. Save it in the current task's\ndesignated user-facing output directory, return a clickable link, then offer to iterate (add/drop a\nsegment, change window or metrics).\n\n---\n\n## Guardrails\n\n- **Never create segments on the account.** Ad-hoc filters are query-time predicates only — say so\n  when reviewing them.\n- **Never invent** attribute FQNs / event names / values — look them up and echo audiences back.\n- **Match metrics to content type** — adapt to the returned metric keys; don't show completion rate for\n  a banner or reactions for a guide flow.\n- **Don't mislead on thin data.** Flag low-sample or zero-data segments.\n- **Read-only** — never publishes or writes anything.\n- Keep it light; the dashboard is the deliverable, not a lecture.\n"
}