Update to Wistia

{
  "name": "wistia-engagement-tools",
  "description": "Audits a Wistia video's engagement (play rate, avg view time, drop-off point, re-watched segments), classifies its type and goal, and recommends where to add or move an interactive feature — lead capture form, CTA, or annotation link — using Wistia's State of Video benchmark data. Use whenever the user asks to \"audit engagement,\" wants to know \"where should I put a CTA / lead capture form / annotation link,\" asks \"why are people dropping off this video,\" wants to \"improve conversion,\" or references an \"engagement audit/report/tools\" workflow. Applies to videos meant to drive leads, conversion, or engagement, with 10+ plays (fewer is a caveat, not a blocker). Also trigger for a bulk/account-wide version (\"audit engagement across my videos,\" \"which videos need a CTA\"). Do NOT trigger for general analytics questions with no engagement-feature angle — use Wistia tools directly.",
  "included_files": [
    {
      "relative_path": "assets/retention-chart-template.html",
      "size_in_bytes": 4434
    },
    {
      "relative_path": "references/state-of-video-benchmarks.md",
      "size_in_bytes": 7507
    }
  ],
  "skill_md_contents": "---\nname: wistia-engagement-tools\ndescription: >\n  Audits a Wistia video's engagement (play rate, avg view time, drop-off point,\n  re-watched segments), classifies its type and goal, and recommends where to add or\n  move an interactive feature — lead capture form, CTA, or annotation link — using\n  Wistia's State of Video benchmark data. Use whenever the user asks to \"audit\n  engagement,\" wants to know \"where should I put a CTA / lead capture form /\n  annotation link,\" asks \"why are people dropping off this video,\" wants to \"improve\n  conversion,\" or references an \"engagement audit/report/tools\" workflow. Applies to\n  videos meant to drive leads, conversion, or engagement, with 10+ plays (fewer is a\n  caveat, not a blocker). Also trigger for a bulk/account-wide version (\"audit\n  engagement across my videos,\" \"which videos need a CTA\"). Do NOT trigger for general\n  analytics questions with no engagement-feature angle — use Wistia tools directly.\n---\n\n# Wistia Engagement Tools\n\n## Welcome message\n\nShow this to the user before starting the workflow:\n\n> Let's see how your video is really being watched: play rate, where people drop off, what they rewatch. Then I'll recommend where a lead capture form, call-to-action (CTA), or annotation link would do the most good.\n>\n> Point me to the video (or say \"all videos\"). Works best at 10+ plays; below that, I'll just flag it as a caveat, not a dealbreaker.\n>\n> You'll get a placement recommendation, backed by that video's own data and Wistia's benchmarks.\n\n---\n\nDiagnoses how a video is actually being watched, then recommends where to place a lead\ncapture form, CTA, or annotation link based on that video's own drop-off/re-watch data\n*and* Wistia's State of Video benchmarks for videos like it.\n\nAll Wistia actions use the Wistia MCP tools — call `tool_search` for the relevant tool\nfamily before using it, since these are deferred tools and their exact parameters aren't\nin context by default. Read `references/state-of-video-benchmarks.md` before Step 4 —\nit has the exact tables this skill's recommendations are built from; don't try to recall\nthe numbers from memory. `assets/retention-chart-template.html` has the retention-curve\nchart used in Step 5 — read it when you get there rather than rebuilding the chart from\nscratch each time.\n\n**This skill can modify a live video's engagement features in Step 6.** Never call an\n`update-*-customizations` tool without explicit, per-change confirmation — see Step 6.\n\n---\n\n## Step 0: Scope — single video or bulk scan\n\nDefault to a single video (the user names it, pastes a URL, or you're mid-conversation\nabout a specific one). If the user asks for an account-wide or multi-video audit\ninstead:\n\n1. Ask for a date range (default: last 90 days) and how many candidate videos to\n   consider (default: top 25 by plays).\n2. Call `show-account-top-content` with `group_by: media`, `sort_by: plays`, the date\n   range, and that `per_page`.\n3. Run Steps 1–5 for each video that clears the qualification bar (below). Skip Step 6\n   (applying changes) in a loop — surface all recommendations together at the end and\n   let the user pick which video(s) to act on, then apply one at a time per Step 6.\n4. Bulk runs default to a saved artifact (see Step 7) rather than a chat report — there's\n   no need to ask when there's more than one video.\n\nFor a single video, continue below directly.\n\n---\n\n## Step 1: Qualify the video\n\nConfirm the video is meant to drive leads, conversion, or engagement — if that's not\nobvious from context, ask the user rather than assuming. This skill isn't useful for\npurely informational or internal-only videos with no engagement goal.\n\nCheck play count via `show-media-aggregated-stats`. **10 plays is a soft floor, not a\nhard gate**: below it, continue the audit but flag prominently in the report that the\nsample size is small and the recommendation is lower-confidence.\n\n---\n\n## Step 2: Pull current engagement data\n\nFor the target video (`mediaId` = hashed ID), gather:\n\n- **Play rate, average view time (percent watched), plays** — `show-media-aggregated-stats`\n  and/or `show-media-analytics` (needs `start_date`/`end_date`; default to all-time or\n  last 90 days if the user has no preference — ask if ambiguous).\n- **Drop-off point and re-watched segments** — `show-media-engagement`. This returns a\n  per-second (or per-bucket) retention curve:\n  - **Drop-off time** = the point where the retention curve falls off sharply (not just\n    the very end — look for the steepest sustained decline, which is often earlier than\n    where the curve finally bottoms out).\n  - **Drop-off rate** = the percentage of viewers lost by that point (100% minus\n    retention at that timestamp).\n  - **Re-watched areas** = any segment where the curve rises or plateaus above the\n    surrounding trend (viewers replaying that section) — report timestamp ranges, not\n    just \"yes/no.\"\n\nReport these five figures plainly before moving on:\n1. Play rate\n2. Average view time\n3. Drop-off rate\n4. Drop-off time\n5. Re-watched areas (if any — it's fine to report \"none detected\")\n\n---\n\n## Step 3: Classify type and goal, confirm with the user\n\nDetermine the video's likely type from two sources:\n\n- **Metadata** — title, description, folder/project name via `get-medias` or the\n  media's existing details.\n- **Transcript** — pull captions via `get-captions` (`media_id` = the video's hashed\n  ID) and skim for content cues (e.g. \"welcome to our webinar,\" \"here's how to set\n  up...,\" testimonial-style first-person praise).\n\nMap your best guess to one of the **11 fixed video types** in the reference file (don't\ninvent new categories — pick the closest fit). Then ask the user to confirm, using\n`ask_user_input_v0` where available:\n\n1. **Video type** — present your best guess plus 2-3 plausible alternatives from the\n   fixed taxonomy.\n2. **Goal** — Lead generation / Conversion (drive action) / Engagement (authority-\n   building), defaulting to your best guess based on type (e.g. testimonials often lean\n   conversion, tutorials often lean engagement) but let the user override.\n\nDon't proceed to Step 4 with an unconfirmed type/goal — the recommendation logic depends\non both.\n\n---\n\n## Step 4: Recommend placement\n\nRead `references/state-of-video-benchmarks.md` now if you haven't already this session.\n\n1. Determine the video's **length bucket** (<1 min, 1-3, 3-5, 5-30, 30-60, 60+).\n2. Look up **expected engagement rate** for this video's (type, length) cell in table 1.\n   Compare to the video's actual engagement rate from Step 2 — say plainly whether it's\n   under/over/in-line with the benchmark.\n3. Map the confirmed **goal** to a feature: Lead generation → lead gen form, Conversion\n   → CTA, Engagement → annotation link.\n4. Use table 6 (lead gen form click-through by placement × length) to find the\n   best-performing placement row for this video's length bucket. Apply this table to\n   whichever feature was chosen in step 3, and say explicitly that table 6 is built from\n   lead-gen-form data being used as a proxy when the feature isn't a lead gen form.\n5. Cross-check against the video's **own** drop-off point from Step 2 — if the\n   benchmark-recommended placement lands after the video's typical drop-off point, flag\n   this tension explicitly rather than silently picking one. In that case recommend\n   placing the feature at or just before the drop-off point instead, and explain why\n   you're overriding the raw benchmark.\n6. For CTAs specifically, also sanity-check against the 2025 qualitative rules (table 7)\n   as a tiebreaker.\n7. If there's a re-watched segment from Step 2, call it out as a secondary candidate\n   spot for an annotation link regardless of the primary recommendation — high\n   re-watch usually means high interest, which is exactly where a clickable link\n   performs best.\n\nState the recommendation as a specific timestamp or range (e.g. \"around 4:10, in the\nvideo's 4th quarter\"), not just a vague zone.\n\n---\n\n## Step 5: Report\n\nRender the retention curve as an inline chart before the text summary. Call\n`visualize:read_me` with `modules: [\"chart\"]` if you haven't loaded it this\nsession, then use `assets/retention-chart-template.html` as the base for\n`visualize:show_widget` — fill in its placeholders from the `engagement_data`\narray (Step 2), the video duration, any re-watch zones, and the recommended\nplacement from Step 4. Skip the recommendation marker only if Step 4 hasn't\nrun yet (e.g. reporting mid-workflow before type/goal confirmation). Don't\nrepeat the chart's content in your prose afterward — narrate the\nrecommendation and reasoning, not the numbers already on screen.\n\nSingle video, chat report by default:\n\n```\n📹 [Video title] — [type] · [goal] · [length bucket]\n📊 Plays: [N] [⚠️ below 10 — low-confidence flag if applicable]\n▶️ Play rate: [X]%\n⏱️ Avg view time: [X]% watched\n📉 Drop-off: [X]% of viewers by [timestamp]\n🔁 Re-watched: [timestamp range(s), or \"none detected\"]\n\nBenchmark comparison: [actual]% vs [expected]% engagement for [type] at this length\n([above/below/in line with] benchmark)\n\n💡 Recommendation: Add a [feature] at [timestamp] ([placement label], based on [X]%\nclick-through for [length bucket] videos at that position)\n[Secondary note on re-watched segment, if any]\n[Note on any tension between benchmark placement and actual drop-off point, if any]\n```\n\nAfter the report, offer to save it as an artifact even for a single video (per Step 0,\nartifacts are the default for bulk but always optional for single-video runs — just\nask).\n\n---\n\n## Step 6: Apply (only with explicit per-change confirmation)\n\nIf the user wants to act on the recommendation, confirm the exact change before calling\nanything — restate feature, timestamp/placement, and any text/URL needed, and get a\nclear yes. Never batch-apply without confirming each one, even in a bulk run.\n\n- **Lead gen form**: `update-lead-capture-customizations` — `provider: wistia_form` (or\n  the account's CRM provider if they use HubSpot/Marketo/Pardot), `settings.time` set to\n  the recommended placement.\n- **CTA**: `update-engagement-customizations` with `plugin.postRoll-v1` — set `on: true`,\n  `time` to the recommended placement (or `\"end\"`), plus `text`/`link` from the user.\n- **Annotation link**: `update-engagement-customizations` with `plugin.midrollLink-v1` —\n  set `on: true` and add an entry to `links` with `time`, `text`, `url`, `duration`.\n\nAfter applying, confirm success and remind the user these changes are live immediately.\n\n---\n\n## Handling gaps and edge cases\n\n- **Video has no transcript** → classify from metadata alone, flag lower confidence on\n  the type guess, still ask the user to confirm.\n- **`show-media-engagement` returns sparse/noisy data** (very low plays) → say so\n  plainly rather than inventing a precise drop-off timestamp; give a rough zone instead\n  (\"somewhere in the first third\") and lean harder on the play-count caveat from Step 1.\n- **Video doesn't fit any of the 11 types well** → pick the closest and say so\n  explicitly when confirming with the user, rather than silently forcing a bad fit.\n- **User's stated goal doesn't match the feature they explicitly asked for** (e.g. goal\n  is \"lead generation\" but they asked specifically about annotation links) → go with\n  what the user explicitly asked for, but note the mismatch and mention the benchmark\n  case for the goal-aligned feature instead.\n- **Video already has an engagement feature in place** → check current state via\n  `show-lead-capture-customizations` / the engagement customizations before\n  recommending — recommend *moving* it if placement is suboptimal rather than assuming\n  none exists.\n- **Bulk run with no qualifying videos** (none meet the \"drive leads/conversion/\n  engagement\" intent) → say so, don't force recommendations onto videos with no\n  engagement goal.\n"
}