Update to Supermetrics Marketing Agent

{
  "description": "Content and SEO analysis from live data: Search Console and organic performance, content-to-conversion attribution, paid promotion of content, newsletters, video and content gaps. Use for SEO audits, content ROI and editorial planning.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 252
    },
    {
      "relative_path": "assets/content_attribution_summary.md",
      "size_in_bytes": 3464
    },
    {
      "relative_path": "assets/content_gap_brief.md",
      "size_in_bytes": 3384
    },
    {
      "relative_path": "assets/content_promotion_brief.md",
      "size_in_bytes": 3771
    },
    {
      "relative_path": "assets/icon-small.png",
      "size_in_bytes": 2921
    },
    {
      "relative_path": "assets/newsletter_review.md",
      "size_in_bytes": 3260
    },
    {
      "relative_path": "assets/seo_audit_report.md",
      "size_in_bytes": 2728
    },
    {
      "relative_path": "assets/video_content_report.md",
      "size_in_bytes": 3093
    },
    {
      "relative_path": "references/content-marketer-guide.md",
      "size_in_bytes": 6974
    },
    {
      "relative_path": "scripts/content_attribution.py",
      "size_in_bytes": 3723
    },
    {
      "relative_path": "scripts/content_gap_analyzer.py",
      "size_in_bytes": 5496
    },
    {
      "relative_path": "scripts/content_promotion_ranker.py",
      "size_in_bytes": 5977
    },
    {
      "relative_path": "scripts/newsletter_performance.py",
      "size_in_bytes": 5721
    },
    {
      "relative_path": "scripts/seo_audit.py",
      "size_in_bytes": 6453
    },
    {
      "relative_path": "scripts/video_content_ranker.py",
      "size_in_bytes": 5102
    }
  ],
  "name": "seo-and-content-performance",
  "skill_md_contents": "---\nname: seo-and-content-performance\ndescription: Content and SEO analysis from live data: Search Console and organic performance, content-to-conversion attribution, paid promotion of content, newsletters, video and content gaps. Use for SEO audits, content ROI and editorial planning.\n---\n\n# Seo and content performance\n\n## Workflows\n\n### Paid promotion content analysis\n**When to use:** the user is deciding which content assets deserve the majority of next quarter's paid promotion budget. Usually triggered by quarterly planning or after a batch of new content has accumulated data.\n\n**Platforms typically involved:** LinkedIn Ads and Facebook Ads primarily. Google Ads sometimes if promoting content in search.\n\n### Step 1 — Pull the data\n> Pull the last 60 days of LinkedIn Ads and Facebook Ads campaigns promoting downloadable content, filtered to campaigns containing [the user's naming convention — Content_, Whitepaper_, Ebook_, etc.].\n\nAsk the user about the naming convention if it's unclear. Data should be at the ad / asset level, not just campaign level.\n\n### Step 2 — Rank the assets\nUse `scripts/content_promotion_ranker.py` (columns: `asset_name`, `platform`, `spend`, `clicks`, `impressions`, optional `leads`; `--min-spend` defaults to 100). The script ranks by composite engagement (CPC + CTR + lead rate where available) and outputs a sorted list.\n\nA note on metrics: CPC and CTR are engagement metrics, not conversion metrics. They tell you the audience is interested. Whether the asset converts that interest into a lead is a separate question. For ranking which assets to put paid behind, engagement is the right framing.\n\n### Step 3 — Visualize the ranking\nThe question the chart needs to answer: **which assets are worth more paid budget, and why?**\n\nA sorted horizontal bar chart of the composite promotion score works well as the primary visualization, with bars colored by asset type (whitepaper, ebook, guide, report) so format trends are visible.\n\nIf the user wants the multi-dimensional view, a grouped bar chart with one cluster per asset showing CPC, CTR, and lead rate side-by-side surfaces the trade-offs — an asset might win on CTR but lose on lead rate.\n\n### Step 4 — Qualitative read on the winners\n> Identify the top two best-performing assets and explain why their messaging is likely resonating with the target audience.\n\nThis is the most useful part of the output for next-quarter content planning. Look at the winning assets and identify the actual angle — pain point, social proof, transformation, status, ROI. Use `assets/content_promotion_brief.md` to structure the deliverable. When the user picks which assets to fund, the `campaign-management` skill can apply the budget changes with their approval.\n\n### Step 5 — Output\nDefault: markdown inline. If the user wants a doc to share with leadership for next-quarter planning, use the `docx` skill.\n\n### Common variations\n- **Organic vs paid** — different workflow; organic and paid content perform on different signals. Suggest running paid first, then a separate organic audit.\n- **Include cost per lead, not just engagement** — if the user has lead-volume data per asset, the ranker accepts it. But sample sizes get small fast at the asset level for leads; CPC/CTR usually has more reliable signal.\n\n---\n\n### Organic content and SEO performance audit\n**When to use:** the user wants to understand which content is winning vs decaying in organic search. Identifies posts to expand, posts to update, and posts to sunset.\n\n**Platforms typically involved:** Google Search Console (`GW`, mandatory) + Google Analytics 4 (`GAWA`, for engagement on top of impressions/clicks). Optional: Ahrefs (`AHRF2`) or Semrush (`SR`) for keyword positions and backlink data, Bing Webmaster Tools (`BW`) for Bing coverage.\n\n### Step 1 — Pull search performance over time\n> Pull the last 6-12 months of Search Console performance by page (and query if needed): impressions, clicks, average position, CTR, split by month. Search Console keeps 16 months of data.\n\nFor posts published in the last 6 months, the trend captures the launch curve (newer posts haven't matured yet). For older posts, the trend captures growth vs decay.\n\n### Step 2 — Pull on-page engagement\n> Pull GA4 data for the same pages (landing page): sessions, engaged sessions, average engagement time, key events.\n\nIf GA4 has key events on the relevant actions (form fills, newsletter signups, demo bookings), pull those per page. Search Console reports full URLs while GA4's `landingPage` is a path; normalize before joining.\n\n### Step 3 — Classify each page\nUse `scripts/seo_audit.py` (columns: `page`, `month` as YYYY-MM, `impressions`, `clicks`, `average_position`, optional `sessions`, `engaged_sessions`, `conversions`). The script classifies each page into:\n- **Growing**: impressions and clicks trending up\n- **Stable**: predictable monthly volume\n- **Decaying**: impressions or clicks trending down significantly (often signals stale content)\n- **Stuck on page 2-3**: average position 11-30 (fixable with on-page work)\n- **Underperforming**: engagement rate under 30% despite traffic (content-quality issue; needs the GA4 columns)\n\n### Step 4 — Visualize the portfolio\nThe question the chart needs to answer: **which pages are growing, which are at risk, and where should I focus content effort?**\n\nA scatter plot works well: x-axis = monthly impressions trend (% change), y-axis = monthly clicks trend. Dots sized by current monthly clicks, colored by classification. The user sees at a glance which pages are climbing and which are slipping.\n\nA secondary view: top 20 decaying pages ranked by absolute click loss vs peak month. These are the urgent updates.\n\n### Step 5 — Build the audit report\nUse `assets/seo_audit_report.md` (offer a live Studio dashboard via the `manage_dashboards` if the user wants to track this monthly). The recommendations should split into:\n- **Update now** (decaying pages with high historical traffic)\n- **Refresh** (stable pages that could grow with a content refresh)\n- **Sunset** (low-traffic, low-quality pages dragging average performance)\n- **Expand** (growing pages where related content could capture additional queries)\n\n### Common variations\n- **Add backlink context** — if Ahrefs is connected, pages with strong backlinks deserve preservation effort; pages with no backlinks may be sunset candidates.\n- **Compare to competitors** — if Semrush or Ahrefs is connected, surface which competitor pages outrank the user's on key queries; gives a roadmap for what the user's pages need to address.\n- **Branded vs non-branded** — separate branded query performance from non-branded. Branded performance is a vanity metric for content; non-branded is the real test.\n\n---\n\n### Content-to-conversion attribution\n**When to use:** the user wants to credit specific content pieces with influencing conversions — not just direct-conversion attribution, but the broader \"what content moved this person closer to converting\" question.\n\n**Platforms typically involved:** Google Analytics 4 (content engagement) + CRM (HubSpot, Salesforce) for the conversion side when available.\n\n### Step 1 — Pull content engagement\n> Pull GA4 data for content URLs: sessions, engaged sessions, average engagement time, scrolled users (90% scroll, if enhanced measurement is on), and key events.\n\nFor pages that aren't conversion targets (blog posts, resource pages, podcast pages), engagement signals matter more than conversions.\n\n### Step 2 — Pull touch data\nGA4 path explorations and conversion paths are UI-only; the GA4 API doesn't return page-level paths. Use what the API does give:\n- **First touch:** GA4 `landingPage` with key events, or HubSpot contact `first_page_seen` / `first_conversion` (`HSCON`).\n- **Last touch:** HubSpot contact `recent_conversion` (the last form and page before converting).\n- **Middle touch:** only from the CRM's page-view history or an export the user provides. If unavailable, say so and score on first and last touch only.\n\n### Step 3 — Compute the content attribution table\nUse `scripts/content_attribution.py` (columns: `content_url`, `sessions`, `engaged_sessions`, optional `avg_engagement_time_seconds`, `first_touch_conversions`, `middle_touch_conversions`, `last_touch_conversions`). Outputs per content piece:\n- Total sessions\n- Engaged sessions (sessions meeting the engagement threshold)\n- Conversions where this content was the first touch\n- Conversions where this content was a touch in the path\n- Influence score (composite of presence in conversion paths)\n\n### Step 4 — Visualize content influence\nThe question the chart needs to answer: **which content pieces show up most often in conversion paths, even when they're not the last touch?**\n\nA bar chart of \"conversions influenced\" (presence in conversion path) per content piece, with bars shaded by share of those that were first-touch vs middle-touch vs last-touch. Often surprising — long blog posts appear in many paths as middle-touch even when they're never the last touch.\n\n### Step 5 — Build the attribution summary\nUse `assets/content_attribution_summary.md`. The audience is typically the content team + their marketing leadership counterpart.\n\n### Common variations\n- **Time-to-conversion by content type** — does engaging with this content type accelerate the conversion timeline? Pull average days from first content engagement to conversion per content type.\n- **Per-persona content paths** — if persona data is available, the same content may have very different attribution patterns per persona.\n- **Repurposing signals** — if a top-converting content piece is in a single format (e.g. long blog post), surface \"convert this to a webinar / podcast / video\" as a recommendation.\n\n---\n\n### Newsletter and email content performance\n**When to use:** the user runs a content-driven newsletter or email program and wants to understand which content types, topics, and formats drive the most engagement and downstream conversion.\n\n**Platforms typically involved:** an email marketing platform (Mailchimp, Klaviyo, Brevo, HubSpot Marketing Email, Campaign Monitor, Omnisend, ActiveCampaign). CRM for downstream conversion if available. Treat open rates with care: Apple Mail Privacy Protection inflates opens, so lean on clicks and click-to-open.\n\n### Step 1 — Pull campaign performance\n> Pull the last 30-60 email campaigns from [email platform]: subject line, send date, list segment, opens, open rate, clicks, click-through rate, unsubscribes.\n\nIf the user can tag campaigns by content type (newsletter, promotional, educational, product update), pull the tag too. Otherwise, ask whether they can provide one.\n\n### Step 2 — Pull list growth and segment data\n> Pull the same period's list-growth data: new subscribers per day/week, segments they joined, source if available.\n\nNet list growth (new subscribers − unsubscribes) is often more informative than open rates for content programs.\n\n### Step 3 — Analyze patterns\nUse `scripts/newsletter_performance.py` (columns: `campaign_name`, `send_date`, `subject_line`, `recipients`, `opens`, `clicks`, `unsubscribes`, optional `segment`, `content_type`, `conversions`, `revenue`). The script:\n- Computes engagement metrics per campaign type\n- Tags subject line features (length class, question, number, emoji) so you can compare open rates by pattern\n- Carries the segment through so you can compare segments\n- Flags campaigns with anomalously high unsubscribe rates (signal of poor content fit)\n\n### Step 4 — Visualize the patterns\nThe question the chart needs to answer: **what kinds of newsletters does my audience actually engage with?**\n\nA bar chart of open rate by content type works as a starting point. A second view: a scatter plot with subject line length on the x-axis and open rate on the y-axis, sized by send volume, colored by content type. Surfaces whether length correlates with open in this audience.\n\nFor unsubscribe analysis: a horizontal bar chart of campaigns ranked by unsubscribe rate — campaigns at the top are losing list members fastest and deserve attention.\n\n### Step 5 — Build the review doc\nUse `assets/newsletter_review.md`. The audience is the user themselves or their content team. For a monthly review, offer a live Studio dashboard (with `manage_dashboards`).\n\n### Common variations\n- **Subject line A/B testing analysis** — if the user runs A/B tests, surface which variants won and what patterns emerge.\n- **Send-time analysis** — different audiences open at different times; surface the best send time by segment.\n- **Content-to-conversion** — combine with CRM data: of subscribers who engaged with the newsletter regularly, what % became customers vs the non-engaged segment?\n\n---\n\n### Video content performance\n**When to use:** the user produces video content and wants to understand cross-platform performance — what's working on YouTube vs TikTok vs Instagram Reels vs LinkedIn — and where to invest more production effort.\n\n**Platforms typically involved:** YouTube (`YT2`) + organic social platforms (TikTok Organic `TIKBA`, Instagram Insights `IGI` via the `instagram_insights` tool, LinkedIn Pages, Pinterest Organic, X Organic, Threads Insights). For paid video: ad platforms.\n\n### Step 1 — Pull cross-platform video data\n> Pull video performance from [connected platforms] for the last 60-90 days: views, watch time, completion rate, engagement (likes/comments/shares), and follower/subscriber growth.\n\nEach platform reports metrics differently — YouTube has average view duration and average view percentage, TikTok has average view time and completion rate, Instagram reports views and reach. Normalize as best as possible; document where direct comparison isn't possible.\n\n### Step 2 — Pull downstream data if available\nFor videos with click-through (CTAs to landing pages), pull session data from GA4. For videos that drive subscribers, pull email-list-growth data if relevant.\n\n### Step 3 — Rank by composite engagement\nUse `scripts/video_content_ranker.py` (columns: `title`, `platform`, `publish_date`, `views`, `completion_rate`, `engagement_rate`, optional `clicks`, `conversions`). Composite engagement combines:\n- Views (volume signal)\n- Completion or retention rate (quality signal — % of viewers who finish)\n- Engagement rate (likes + comments + shares / views)\n- Clicks and conversions are carried through in the output but not scored\n\nThe script scores each video by percentile within its own platform (so a TikTok with 50k views isn't compared directly to a LinkedIn video with 500) and ranks videos within each platform. Compare across platforms by these within-platform scores.\n\n### Step 4 — Visualize the portfolio\nThe question the chart needs to answer: **which content themes and formats are working, and where?**\n\nA grouped bar chart with the user's top 10 videos per platform works well for platform-by-platform review. For cross-platform: a scatter plot with views on the x-axis and completion rate on the y-axis, dots colored by platform and sized by engagement.\n\n### Step 5 — Build the performance report\nUse `assets/video_content_report.md`. The output should surface:\n- Which themes win across platforms (universal-appeal content)\n- Which themes are platform-specific\n- Which format-platform combinations are highest-leverage\n- Production recommendations (length, structure, hook patterns) based on the winners\n\n### Common variations\n- **Hook analysis** — for short-form video specifically, the first 3 seconds determine retention. Pull only the top performers and surface what their hooks have in common.\n- **Posting cadence vs performance** — does posting daily produce better aggregate results than posting weekly? Cross-reference posting frequency with average performance.\n- **YouTube long-form vs Shorts** — separate analysis. Different audiences, different success criteria.\n\n---\n\n### Content gap analysis\n**When to use:** the user is planning the next quarter or year of content and wants to identify topic gaps — queries the audience is searching for that the user's content doesn't address, or where competitors outrank.\n\n**Platforms typically involved:** Google Search Console (`GW`, user's own queries) + Ahrefs (`AHRF2`) or Semrush (`SR`) for competitor keywords. Google Trends (`GT`) and Google Ads Keyword Planner (`GAKEY`) for query volume and trend.\n\n### Step 1 — Pull the user's ranking keywords\n> Pull all keywords the user's site ranks for from [Search Console / Ahrefs / Semrush]: keyword, current position, monthly search volume, current URL.\n\n### Step 2 — Pull competitor or industry benchmark keywords\nAsk the user: which 3-5 competitors should be in scope?\n\n> Pull ranking keywords for [competitor 1, competitor 2, ...] from [Ahrefs / Semrush]. For each competitor: keyword, position, URL.\n\n### Step 3 — Compute the gap\nUse `scripts/content_gap_analyzer.py` (columns: `keyword`, `monthly_volume`, `user_position`, `competitor_position` or one `competitor_<name>_position` column per competitor, optional `search_intent`). The script keeps keywords where:\n- a competitor ranks in the top 10 (`--competitor-top`)\n- the user ranks below position 30 (`--user-threshold`) or not at all\n- monthly volume is at least 100 (`--min-volume`)\n\nOutputs ranked keyword gaps with: keyword, monthly volume, best competitor position, user status (position or \"not ranking\"), and a suggested content type from the `search_intent` column. Remove competitor brand terms yourself; the script doesn't filter them, and it doesn't use Google Trends data.\n\n### Step 4 — Visualize the opportunity\nThe question the chart needs to answer: **what's the volume of search demand we're not capturing, and how concentrated is the opportunity?**\n\nA horizontal bar chart of the top 30 gap keywords by monthly search volume works as the primary view. Color-code by suggested content type (informational, commercial, etc.) so the user can plan content programs by theme.\n\nA secondary view: cumulative-volume curve — the top 10 gap keywords represent how much of the total gap volume? Often 70-80%, meaning a small number of content pieces can capture most of the opportunity.\n\n### Step 5 — Build the content brief\nUse `assets/content_gap_brief.md`. The output should be production-ready: each prioritized keyword should have a suggested content format (blog post, landing page, video) and a 2-sentence content angle.\n\n### Common variations\n- **Topic clustering** — instead of keyword-by-keyword, cluster the gaps into topic clusters and recommend pillar pages.\n- **Quick wins** — surface keywords where the user already ranks page 2-3 but a content update could push to page 1. These are faster than net-new content.\n- **Featured snippets and PAA** — if the data is available, surface queries where competitors win featured snippets or People Also Ask boxes. These are higher-leverage than position-only competitions.\n\n---\n\n## Ad hoc analysis\n\nFor one-off content questions outside these seven workflows (\"which referral source has the highest engagement on our top blog post?\", \"is there a relationship between word count and bounce rate?\", \"which CTA variant on our pricing page is converting best?\"), write fresh analysis code. The \"Choosing the right visualization\" framework in the SKILL.md tells you which chart family fits.\n\n---\n\n## A note on content metrics ladders\n\nWhen the deliverable is going to a non-content audience (executives, finance), frame metrics as a ladder rather than absolute numbers: engagement (CTR, time-on-page) → consumption (downloads, video completion) → conversion (form fills, demo requests) → revenue (pipeline created, deals influenced). Different content lives at different rungs and should be measured accordingly. A blog post measured on direct revenue attribution will always look like a failure; measured on engagement and consumption, it can be the highest-leverage piece in the portfolio.\n\n## Background\n\nChart choices, principles and gotchas for this area: [references/content-marketer-guide.md](references/content-marketer-guide.md).\n\n## Before you analyze\n\n- Load saved targets, budgets and known context with `manage_business_context` (`action: get`) and judge results against them, not generic benchmarks.\n- Query correctly: follow the `marketing-data-queries` skill for discovery, field IDs and platform quirks.\n- Check tracking first. If platform conversions and GA4 or backend numbers disagree by more than 20%, or spend continues with zero conversions, say so before any optimization advice.\n- Pull, then analyze, as separate steps. Run one heavy query at a time.\n- Evidence discipline: treat changes on fewer than ~10 conversions as noise, ignore items under 1,000 impressions, don't call learning-phase campaigns failures, check for shared budgets before budget advice, and re-pull before conceding a disputed number.\n- Answer shape: conclusion, business impact, next actions, then \"How I got this\" (one line per data pull).\n- Helper scripts in `scripts/` take a CSV and print a table. Run them if you can execute code; otherwise compute the same thing directly. Templates in `assets/` shape the final deliverable.\n\n## After the analysis\n\n- Analysis only recommends. If the user wants to act (pause, budget shift, negatives), use the `campaign-management` skill, with explicit approval for each change.\n- For a recurring or shareable result, offer once to publish it as a live Supermetrics Studio dashboard with `manage_dashboards` (static preview first, then the live upload).\n"
}