Supermetrics Marketing Agent

View saved version →

---
name: ad-creative-performance
description: Analyze ad creative from live data: ad fatigue (rising frequency, falling CTR), creative concept tests, winning hooks and formats, and refresh recommendations for Meta, TikTok, LinkedIn and Google ads. Use when ads are tiring, a creative test needs a verdict, or the creative team needs a brief.
---

# Ad creative performance

## Workflows

### Ad fatigue and frequency check
**When to use:** the user suspects ad creatives are burning out — previously strong ads losing CTR, climbing frequency, rising CPC. Often ends with notifying the creative team about which ads need refresh.

**Platforms typically involved:** Facebook Ads (`Frequency`), TikTok Ads (`frequency`), Google Ads (`avg_impr_frequency_per_user`). LinkedIn Ads has no frequency field; compute impressions ÷ reach (`approximateUniqueImpressions`).

### Step 1 — Pull the data
> Pull the last 30 days of performance data grouped by ad name, with impressions, frequency, CTR, and CPC.

Include `ad_id` if the user will need to act on this in-platform.

Frequency can't be summed or averaged across days (daily values understate it). Pull it per ad for the recent window as a separate query and put that value in the `frequency` column of the recent-window rows before running the script.

### Step 2 — Identify fatigued ads
Use `scripts/ad_fatigue_detector.py`. Default thresholds: frequency >3.5 and CTR decline >20% week-over-week. If the user wants different thresholds, accept them and pass to the script.

### Step 3 — Visualize the fatigue landscape
The question the chart needs to answer: **which ads are fatigued, how severely, and how much spend is exposed to the problem?**

The most informative visualization for this is usually a scatter plot — frequency on the x-axis, recent CTR on the y-axis, dot size weighted by spend, dot color encoding a third dimension (CPC trend, or simply flagged vs not). Shade or label the fatigue zone explicitly. The user sees at a glance which ads are in trouble and which are still healthy.

Alternative when the user has few ads (under 10): a horizontal bar chart ranking ads by severity, with spend annotated next to each bar.

Whichever you pick, name the worst offender explicitly when surfacing the chart — don't make the user visually scan.

### Step 4 — Refresh recommendations
For each flagged ad, state what's happening (frequency X, CTR down Y%, CPC up Z%) and what to do (pause, refresh creative, refresh copy only, swap thumbnail). Prioritize by spend impact — the $5k/week ad needs attention before the $50/week one.

### Step 5 — Notify the creative team
Build the email body using `assets/creative_refresh_email.md`. The default delivery is markdown inline so the user can review and send themselves. If the user wants it as a doc, use the `docx` skill. If Gmail is connected and the user wants it as a draft, offer to save it there.

### Common variations
- **No frequency threshold known** — use 3.5 as a sensible default or compute +1 standard deviation above the account's typical range.
- **Just top 10 fatigued ads** — limit the script output and the chart to top N by spend or severity.

---

### Creative concept testing and iteration
**When to use:** the user is running a creative test (multiple variants of an ad in the same campaign) and wants to identify winners and generate new variations.

**Platforms typically involved:** Facebook Ads, LinkedIn Ads, sometimes TikTok Ads.

### Step 1 — Pull the data
> Pull the last 14 days for [campaign name] across [platforms], broken down by individual ad name and ad format.

Format matters here — is video beating static? The field differs by platform (Facebook Ads `creative_object_type`, Google Ads `AdFormatType`); name the column `ad_format` for the script. Facebook Ads also returns `creative_thumbnail_url`.

### Step 2 — Rank by efficiency
Use `scripts/cpa_ranker.py` with `--group-by ad_format` to get both: top ads by CPA and the format-level comparison.

### St

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

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

View saved version →

---
name: b2b-pipeline-analysis
description: B2B demand gen analysis from live ad, GA4 and CRM data (HubSpot, Salesforce, Pipedrive): lead-gen efficiency, pipeline and revenue by channel, MQL-to-SQL by source, ABM engagement, and email plus paid funnels. Use for pipeline contribution, lead quality and ABM questions.
---

# B2b pipeline analysis

## Workflows

### Lead generation efficiency comparison
**When to use:** the user is comparing efficiency of B2B advertising platforms for lead capture, typically LinkedIn vs Facebook. Output is usually a one-page summary for the demand gen team or a leadership recommendation.

**Platforms typically involved:** LinkedIn Ads and Facebook Ads primarily. Sometimes Google Ads for B2B search.

### Step 1 — Pull the data with campaign filter
> Pull the last 60 days of campaign performance from LinkedIn Ads and Facebook Ads, filtered to campaigns containing the phrase [Lead Gen / LG_ / MQL_ / whatever the user's convention is].

The filter phrase is specific to the user's naming convention. Ask if unclear. The data needs to be at the ad / asset level, not just campaign level — different assets in the same campaign often perform very differently.

### Step 2 — Compare CPL and lead conversion rate
Use `scripts/lead_efficiency.py` (columns: `platform`, `spend`, `clicks`, `impressions`, `leads`). Outputs platform-level CPL, lead-to-click ratio, CTR, and a comparison summary. For LinkedIn Lead Gen Forms, the lead count is the `oneClickLeads` field.

### Step 3 — Visualize the comparison
The question the chart needs to answer: **which platform is more efficient, and by how much?**

A simple sorted bar chart of CPL by platform works as the primary visualization. If the user wants the multi-dimensional view, a small dashboard-style group (CPL, lead conversion rate, CTR, total leads) with the platforms side-by-side makes the trade-offs visible — sometimes the cheaper platform produces fewer leads, or the lower-CPL platform has worse lead quality. Name the trade-off explicitly when surfacing the visualization.

If the user has tagged the ad creatives, a secondary chart ranking individual ads by efficiency (across both platforms) surfaces the actual winners, which is often more useful than the platform-level average.

### Step 4 — Identify what's working in the winners
> Identify the top two best-performing ad creatives across both platforms based on conversion rate, and explain why their messaging is likely resonating with the target audience.

This is the qualitative step. Look at the winning ad copy and identify the actual angle — pain point, social proof, status, ROI claim. The output is a brief on what's resonating, which the user can take into the next round of creative.

Use `assets/lead_efficiency_summary.md` to structure the final deliverable.

### Step 5 — Output
Default delivery is markdown inline. If the user wants a Word doc, use the `docx` skill.

### Common variations
- **Add Google Ads search to the comparison** — search and social lead gen aren't directly comparable on raw CPL. Frame as "intent-driven (search) vs interruption-driven (social)" rather than head-to-head.
- **Cost per MQL, not cost per lead** — needs CRM data. If a HubSpot or Salesforce connector is active, pull MQL counts by source. Without one, ask the user how they'll get the data.
- **Compare to last quarter** — re-run for the prior 60-day window and overlay both periods on the chart.

---

### Pipeline contribution by channel
**When to use:** the user is in B2B and wants to credit marketing channels with the pipeline they actually create — not just leads. This is the single most-requested demand gen analysis when a CRM connector is available.

**Platforms typically involved:** ad platforms (LinkedIn Ads, Google Ads, Facebook Ads) + a CRM connected in Supermetrics (HubSpot, Salesforce, Pipedrive, Zoho CRM, Close CRM, Odoo CRM). Useful fields: HubSpot `deal_amount`, `deal_stage`, `original_source`; Salesforce `opportunit

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

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

View saved version →

---
name: budget-pacing-allocation
description: Check ad budget pacing and plan reallocation from live data: month-to-date spend vs budget with a month-end forecast per channel, cross-channel ROAS benchmarking, and modelled budget shifts with diminishing returns. Use for "are we on track", "where should the next euro go" and reallocation proposals.
---

# Budget pacing and allocation

## Workflows

### Budget pacing and financial forecasting
**When to use:** the user wants to know if monthly (or quarterly) ad spend is on track and what month-end totals will be. Often mid-month when there's still time to course-correct.

**Platforms typically involved:** whichever platforms have meaningful spend. For B2B usually Google Ads, LinkedIn Ads, Facebook Ads. For ecommerce, add Pinterest and TikTok.

### Step 1 — Pull month-to-date data
> Pull the daily ad spend and total conversions for the current period across [the connected ad platforms].

Daily granularity is required — the pacing script computes the run rate as the month-to-date daily average. If spend ramped mid-month, say so and project from the recent daily rate instead.

### Step 2 — Forecast period-end
Use `scripts/budget_pacing.py`. Pass in the period target budget per channel; ask the user if they haven't shared it. The script outputs period-end projections and the variance vs. target.

### Step 3 — Visualize pacing
The question the chart needs to answer: **are we on track, and where's the risk?**

The most useful visualization for this is usually a line chart per channel: cumulative spend (solid line) vs. target trajectory (dashed line, a straight line from $0 at period start to target at period end). Channels below the dashed line are underspending; above it are overspending. Shade the gap red or green based on which side of the target the channel is on.

Alternative when the user has many channels (8+): a horizontal bar chart of variance percent, sorted by absolute variance, color-coded by direction.

### Step 4 — Flag pacing issues
The script flags channels off-pace by more than ±15% (configurable). Surface the flagged channels with their projected period-end and a one-line recommendation per channel — slow down bidding, increase daily caps, redistribute budget.

### Step 5 — Output
Default delivery is the chart in chat plus a markdown summary. Pacing is checked repeatedly, so offer once to publish it as a live Studio dashboard (with `manage_dashboards`). If the user wants a spreadsheet for the planning team, use the `xlsx` skill.

### Common variations
- **"What if we hold spend flat for the rest of the period?"** — re-run the projection with the daily run rate frozen. The script supports a `--freeze-from` date.
- **Compare to last period's pacing curve, not just the target** — pull prior-period daily data and overlay both lines on the chart. Often more useful than the abstract target line.
- **Project conversions, not just spend** — the script does both. If conversion volume is the actual concern, lead with that visualization.

---

### Cross-channel ROAS benchmarking
**When to use:** the user is deciding how to allocate next period's budget across platforms and needs a defensible cross-channel comparison.

**Platforms typically involved:** Google Ads, Facebook Ads, LinkedIn Ads at minimum. For ecommerce: add TikTok, Pinterest, sometimes Amazon Ads.

### Step 1 — Pull the data
> Pull the total spend, revenue, and ROAS for the last 60 days across [the connected ad platforms].

Surface the attribution model for each platform. If the user doesn't know, name the issue explicitly in the deliverable — comparing Facebook's 7-day-click / 1-day-view ROAS to data-driven ROAS in Google is apples to oranges and a finance partner will spot it.

### Step 2 — Rank and compare
Use `scripts/roas_ranker.py`. The script ranks channels, computes the best-to-worst spread, and outputs a budget-reallocation recommendation with the diminishing-returns caveat baked in.

### Step 3 — Visualiz

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

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

View saved version →

---
name: campaign-management
description: The shared safety rules and payload shape for writing advertising campaigns through the Supermetrics MCP server — read before write, created paused, approval levels, per-field targeting updates, checking write_status. Use when the user wants to launch a campaign, change a budget or bid, pause or enable ads, edit targeting or manage creatives on ChatGPT Ads or Snapchat, when writing across several platforms at once, or for any campaign change on Google Ads, Meta Ads, Microsoft Advertising, TikTok Ads or LinkedIn Ads.
---

# Campaign management with Supermetrics

These tools spend real money. Treat every write as consequential.

Platform payload details (Google Ads, Meta, Microsoft, TikTok, LinkedIn) are in the `marketing-data-queries` skill's `references/<platform>.md` files.

## Before writing anything

1. Campaign writes must be enabled per advertising account at
   [hub.supermetrics.com/write-settings](https://hub.supermetrics.com/write-settings), where the
   account owner also sets an approval level: no human approval, going live, budget + going live,
   or all live changes. If a write fails with a permissions error, that is usually why.
2. Read before you write. `campaign_and_resource_get` shows current state — campaigns,
   ad groups, ads, keywords, audiences, budgets. Never update a campaign you have not read.
3. Check business context with `manage_business_context` (`action="get"`, plus `ds_id`
   and `account_id`). Naming conventions, budget ceilings and excluded campaigns live there.

## Safety rules

- **New campaigns are always created paused.** This is enforced by the platform layer;
  do not try to work around it.
- **Only set `status: "ENABLED"` when the user has explicitly approved that specific
  campaign going live.** Enabling starts spend immediately.
- **Google Performance Max**: enabling the campaign is not enough — its asset groups are
  paused too. Enabling those is a second, separately approved step.
- **`targeting` updates per field.** On update, omitted targeting fields are kept; each field
  you send replaces that whole list, so send its complete value (all locations, all
  interests), and `[]` clears it (not on Snapchat). For Google and Microsoft keywords,
  `ad_groups[].add_keywords` / `remove_keywords` append and remove without touching the rest.
  TikTok and LinkedIn: target existing ad groups through `ad_groups[].targeting`.
- **Confirm budgets in writing** before submitting. State the amount, the currency and
  whether it is daily or lifetime.

## Creating a campaign

Use `manage_campaign` without a `campaign_id`. `budget_amount` is required. Structure:

- Campaign level: name, budget, bidding strategy, dates, campaign-level targeting.
- `ad_groups[]`: ad sets or ad groups. Omit `id` to create, include `id` to update.
- `ad_groups[].ads[]`: each needs a name and a `creative` (headlines, descriptions,
  `final_urls`). Meta ads additionally require `page_id` in the ad's `platform_settings`.

Creatives accept, in order of preference: `asset_url` (a public URL), `asset_id` (already
in the ad account — find them via `campaign_and_resource_get` with
`resource_type="assets"`), or `upload_ref` from `creative_picker`. If the user has no
creative yet, open `creative_picker` to browse, upload, AI-generate or import one.

Platform quirks worth knowing before you build the payload:

- **Google Ads**: 3–15 headlines (30 chars), 2–4 descriptions (90 chars), `final_urls`
  required. Performance Max images must be 1.91:1, 1:1 or 4:5 — 16:9 and 9:16 are rejected.
- **Meta**: budget sits on the campaign under CBO, on each ad set under ABO. Carousels use
  `carousel_cards`, not `assets`.
- **TikTok**: video creatives must use `asset_id`; a URL will not work.
- **LinkedIn**: single image only.

## Updating

Pass `campaign_id` to update. Only the fields you send change. Campaign type and objective
are fixed at creation and cannot be changed afterwards.

Partial success is p

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

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

View saved version →

---
name: campaign-performance-review
description: Review paid campaign performance from live data: week-over-week changes with causes and actions, a daily morning check (yesterday vs the 7-day average), and attribution differences between platforms. Use for weekly reviews, daily standups and "what changed" questions across Google Ads, Meta, LinkedIn, TikTok and Microsoft Ads.
---

# Campaign performance review

## Workflows

### Week-over-week campaign optimization
**When to use:** the user wants to spot efficiency decline (rising CPC, dropping conversion rate, climbing CPA) before it eats the monthly budget. Common phrasings: "compare last week to the week before," "is performance dropping," "what changed in the campaign."

**Platforms typically involved:** LinkedIn Ads, Facebook Ads, Google Ads. Confirm if the user has specific platforms in mind.

### Step 1 — Clarify the comparison (only if ambiguous)
If the user hasn't specified the time window or scope, use a multiple-choice question tool if available to clarify:
- Time window: rolling 7-day, calendar week, last 30 days, etc.
- Scope: campaign level, ad set level, or ad level

Skip if the user's phrasing already makes it obvious.

### Step 2 — Pull the data
> Pull performance data for the [campaign name] running on [platforms] for [current period] and [prior period]. Include spend, impressions, clicks, CTR, CPC, conversions, and CPA.

If the user mentioned specific KPIs (ROAS, leads, video views), include those too.

### Step 3 — Run the comparison
Use `scripts/wow_comparison.py` to compute the deltas. The script flags metrics that moved more than ±10% by default.

### Step 4 — Visualize the changes
Build an inline chart. The question the chart needs to answer: **what changed, and by how much?**

Decide the chart based on what's being compared:
- Comparing the same metrics across two time periods, one campaign at a time → horizontal bar chart of percentage changes, one bar per metric, color by business meaning (improvement vs decline)
- Comparing multiple campaigns side-by-side → grouped bars or small multiples (one mini-chart per campaign)
- Trend over many weeks rather than two snapshots → line chart with a reference line for the baseline period

Whatever you build, sort by the metric of interest (don't leave alphabetical), highlight flagged metrics with an outline or marker, and name the headline above the chart ("CTR dropped on 4 of 5 campaigns this week" — not "Performance data").

### Step 5 — Recommendations
> Generate recommendations: which specific ads to pause, where to shift the remaining budget, and what demographic segments are overperforming.

Build from `assets/optimization_doc.md`. Be specific: name ads, give dollar amounts, identify segments by their actual labels (age 25–34, mobile, iOS).

### Step 6 — Package the deliverable
Default delivery is inline markdown — fast, no friction. If the user reviews this weekly, offer once to publish it as a live Studio dashboard (with `manage_dashboards`). If the user asks for something they can share or save, the right tool depends on what they want:
- A Word doc to send around → use the `docx` skill
- A spreadsheet to sort and filter → use the `xlsx` skill
- A message to post in Slack (if a Slack connector is available) → adapt the recommendation to Slack tone (shorter, no formal greeting)

Don't overwhelm the user with options up front. Pick the sensible default and let them redirect.

### Common variations
- **By ad set instead of campaign** — re-run step 2 grouped by ad set (Facebook Ads `adset_name`, Google Ads `Adgroupname`).
- **Just one platform** — drop the cross-channel framing in step 4.
- **Compare to last month instead** — swap the time windows in step 2; the rest is identical.
- **Add lead quality from a CRM** — if a HubSpot or Salesforce connector is active, pull MQL conversion rate by source and join with the ad-platform CPA. The combined view ("$50 ad CPA but only 8% become MQLs vs another channel's

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

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

View saved version →

---
name: ecommerce-roas-analysis
description: Ecommerce paid acquisition analysis from live ad and store data: blended and per-platform ROAS with day-of-week patterns, promo anomaly detection, SKU-level performance, new vs returning customer ROAS, AOV and basket composition, subscription retention cohorts and pre-promo planning. Use for Shopify and other online stores advertising on Google, Meta and TikTok.
---

# Ecommerce roas analysis

## Workflows

### Cross-platform ROAS and purchase behavior
**When to use:** the user is doing a periodic (usually monthly) review of paid acquisition efficiency across their main ecommerce platforms, and wants to surface day-of-week patterns to inform bid strategy.

**Platforms typically involved:** Google Ads and Facebook Ads at minimum. Sometimes TikTok Ads, Pinterest Ads, Snapchat Ads, Amazon Ads.

### Step 1 — Pull the data
> Pull the last 30 days of daily ad spend and purchase conversion value from [Google Ads, Facebook Ads, etc.].

Daily granularity matters — day-of-week analysis requires it. Make sure data has conversion value (revenue), not just count. If conversion value isn't populated, this workflow can't run as designed; surface that and offer the count-based version instead.

### Step 2 — Compute blended ROAS
Use `scripts/blended_roas.py`. The script computes blended ROAS daily, weekly, and by day-of-week. Mention the double-count caveat once when introducing the number, not repeatedly.

### Step 3 — Visualize the trend and patterns
Two questions worth surfacing, often as two charts:

**"Is ROAS trending up, down, or stable?"** A line chart of daily blended ROAS over the 30-day window, with a horizontal reference line at the period average. The chart makes drift visible — ROAS that's volatile day-over-day tells a different story than ROAS drifting in one direction.

**"Which days of the week perform best?"** This is the prime case for a heatmap: rows = day of week (Monday-Sunday), columns = a single column if data is daily-only, or hour columns if hourly data is available. Cell color = ROAS or conversion rate, with a diverging red-to-green scale centered on the period average. Above-average days appear green, below-average appear red, intensity shows magnitude.

If a heatmap is overkill for the user's data shape, a sorted horizontal bar chart of average ROAS by day of week works as the fallback.

### Step 4 — Budget weighting recommendation
> Build a strategic plan for adjusting weekly budget allocation to weight spending more heavily toward the days demonstrating the strongest purchase intent.

Use `assets/dow_budget_strategy.md`. The recommendation should propose a weighting (e.g. Tuesday +20%, Friday -15%) and explicitly flag what would invalidate the strategy — usually a promo period scrambling normal patterns.

### Step 5 — Output
Default delivery: charts in chat plus a markdown recommendation. For a ROAS view the team will reopen, offer once to publish it as a live Studio dashboard (with `manage_dashboards`). If the user wants a Word doc to share with the team, use the `docx` skill.

### Common variations
- **Add TikTok, Pinterest** — same workflow, expand the platform list. Watch for platforms with low spend producing noisy daily numbers.
- **Compare to prior 30-day period** — pull a second window and overlay both lines on the trend chart.
- **Break down by product category** — needs product-level data from Shopping/catalog feeds. Available if the user runs Shopping campaigns; not available if they run purely image/video.

---

### Promotional campaign anomaly detection
**When to use:** the user is running a high-stakes promo (BFCM, holiday sale, flash sale) and wants to catch cost-per-purchase anomalies before they burn the day's budget.

**Platforms typically involved:** Facebook Ads most often (BFCM spend concentrates there for many DTC brands). Google Ads where applicable.

### Step 1 — Pull yesterday's promo data
> Pull yesterday's data for the [promo campaign filte

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

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

View saved version →

---
name: event-and-webinar-roi
description: Field and event marketing analysis from live data: pre-event channel ROI, post-event geo-lift, event portfolio, event-driven pipeline, account engagement, webinar funnels and partner event ROI. Use for conferences, field events, webinars and gated content.
---

# Event and webinar roi

## Workflows

### Pre-event channel ROI
**When to use:** the user is days or weeks from an event, wants to know where to put the remaining promotion budget, and needs to update the regional team on the plan.

**Platforms typically involved:** LinkedIn Ads and Google Ads most commonly. Facebook Ads occasionally.

### Step 1 — Pull the data
> Pull the last 30 days of performance data for campaigns containing [user's event naming convention — Event_, Webinar_, etc.] across [LinkedIn Ads, Google Ads, etc.].

Ask the user about the naming convention if unclear. Look for spend, clicks, and registrations (sometimes called conversions depending on platform setup).

If ad-platform registration numbers diverge significantly from the event platform (Zoom, Eventbrite, ON24 — not Supermetrics sources, so ask for the count or an export), flag the discrepancy before proceeding — the comparison is misleading otherwise.

### Step 2 — Compare cost per registration
Use `scripts/registration_cost_compare.py` (columns: `channel`, `spend`, `clicks`, `registrations`). The script warns when conclusions are based on fewer than 30 registrations per channel — the threshold below which CPR differences are likely noise.

### Step 3 — Visualize the comparison
The question the chart needs to answer: **which channel is generating registrations more efficiently, and how confident are we?**

A sorted horizontal bar chart of cost-per-registration works as the primary visualization, with bars sorted ascending (cheapest first). When sample sizes are small for one or more channels, distinguish those bars visually — lower opacity, a hatched pattern, or a "low confidence" badge next to the label — so the user doesn't over-trust low-N comparisons.

For richer context, a paired bar chart per channel showing CPR + registration rate side-by-side surfaces the trade-offs (sometimes the cheaper channel also has lower-quality engagement).

If the user is tracking pacing toward a registration target, a line chart of cumulative registrations vs target trajectory makes the gap visible.

### Step 4 — Recommend budget shift
The recommendation should be concrete: dollar amount, source channel, destination channel, expected lift in registrations. If sample size is low, recommend a smaller hedged shift (e.g. 15% rather than 50%) and explain why.

### Step 5 — Update the regional team
Use `assets/regional_team_update.md`. The message is short — Slack-length even if delivered as email.

If a Slack connector is active, the update typically goes there directly to the regional team's channel. If not, default to inline markdown the user can copy. If the user wants to act on the budget shift, the `campaign-management` skill can apply it with their approval.

### Common variations
- **"What if we extend the campaign?"** — model expected additional registrations at current CPR. The script accepts a `--projected-days` flag.
- **Paid vs organic separately** — if the user has tagging that separates them, run the comparison separately rather than averaging.
- **Add cost per attendee** — needs post-event attendance data, which doesn't exist yet pre-event. If the user has historical attendance rates by channel, model expected attendees but state the assumption.

---

### Post-event geo-targeted follow-up
**When to use:** the user just ran an in-person event in a specific region and wants to quantify whether it drove digital engagement lift locally.

**Platforms typically involved:** Facebook Ads, LinkedIn Ads at minimum. Google Ads if search campaigns ran. Campaigns need geo-targeting configured.

### Step 1 — Pull the regional data
> Pull the performance data from the l

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

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

View saved version →

---
name: executive-marketing-report
description: Leadership-level marketing reporting from live data: 90-day executive overviews, efficiency vs goals, CAC and LTV unit economics, annual planning and new-channel business cases, delivered as decks, memos or live Supermetrics Studio dashboards. Use for CMO, board and quarterly updates.
---

# Executive marketing report

## Workflows

### The 90-day executive overview
**When to use:** the user is preparing a quarterly review or cross-channel summary for a CMO, leadership team, or board. The output is usually a slide deck, often accompanied by a printable handout.

**Platforms typically involved:** LinkedIn Ads, Facebook Ads, Google Ads at minimum, often expanded to TikTok Ads, Microsoft Ads, and any display or programmatic platforms the user runs.

### Step 1 — Pull the data
> Pull the last 90 days of performance data from [the connected ad platforms]. Include spend, impressions, clicks, conversions, conversion value or revenue, CPA, and ROAS, broken down by channel and by week.

Weekly granularity matters — trends are visible, not just totals. Leaders often have specific KPIs (MQLs, SQLs, pipeline value) they want surfaced; confirm before going deeper.

### Step 2 — Visualize the headline
The first chart the user sees should answer: **what's the story this quarter?** Build a high-level summary visualization before drilling into channel-level detail.

Options that work well at this layer:
- A small dashboard-style group of headline metric cards (total spend, total revenue, blended ROAS, total conversions) with the period-over-period change next to each
- A simple weekly line chart showing blended ROAS or total spend trend over the 90 days
- A stacked bar showing channel-mix of spend and a paired stacked bar showing channel-mix of revenue (mismatches between the two are the most useful finding)

Pick one — don't build all three. The headline is one thing, not three.

### Step 3 — Channel-level detail
For each channel with meaningful spend, surface the key metrics: spend, revenue, conversions, ROAS, CPA, share of total spend, share of total revenue.

When the comparison is "which channel is pulling its weight?", a side-by-side chart of spend-share vs revenue-share per channel makes mismatches obvious immediately — channels well above the diagonal are over-delivering, channels below it are under-delivering.

### Step 4 — Recommendations
Use `scripts/exec_summary_builder.py` to produce a structured outline of the deck content. The script handles the slide skeleton; the user's analysis fills in the callouts and recommendations.

Build from `assets/exec_deck_outline.md`. Recommendations should be specific: name a channel, name a dollar amount or percent shift, name the expected impact.

### Step 5 — Build the deck
Use the `pptx` skill, if available, to produce the actual `.pptx` file. Read the SKILL.md first — slides have layout rules and visual conventions that don't apply to documents.

Embed the visualizations from steps 2 and 3 inside the deck. Don't put long text on slides — bullets and callouts only. The deck is a talking aid.

### Step 6 — Companion deliverables (only if asked)
For a quarterly review the team will reopen, offer once to publish it as a live Studio dashboard (with `manage_dashboards`). If the user wants a handout to accompany the deck, use the `docx` skill to produce a Google Doc–style summary. If they want a CMO email, build from `assets/cmo_email.md` and deliver inline as markdown (so they can edit before sending). If Gmail is connected, offer to save as a draft.

### Common variations
- **Just the executive summary, skip channel deep-dives** — collapse to one summary visualization + one cross-channel comparison + recommendations.
- **Quarter-over-quarter framing** — pull a second 90-day window from the prior quarter and add a QoQ comparison visualization (slopegraph works well for this).
- **Add a specific campaign deep-dive** — drop in one focused slide betwee

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

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

View saved version →

---
name: funnel-and-tracking-audit
description: Reconcile what ad platforms report with what GA4 and the CRM or store recorded, find tracking breaks, implausible CPAs and broken UTMs, and diagnose where traffic leaks between click and conversion. Use before trusting optimisation advice, or when platform and GA4 numbers disagree.
---

# Funnel and tracking audit

## Workflows

### The traffic-to-conversion audit
**When to use:** the user wants to see which channels drive engaged traffic that actually converts on-site, not just cheap clicks. The output usually ends with an update to sales leadership justifying a budget reallocation.

**Platforms typically involved:** Google Ads, LinkedIn Ads, and Google Analytics 4. GA4 is mandatory — without it this workflow can't run.

### Step 1 — Pull ad platform data, then GA4
> Pull the last 30 days of spend and click data from the Google Ads and LinkedIn Ads accounts. Then pull sessions and key events (conversions) for the same period from Google Analytics 4, by session source / medium.

Two separate pulls. Do ad platforms first, confirm the data, then GA4 split by `sessionSourceMedium` or `sessionCampaignName` (not default channel grouping, which lumps LinkedIn and Facebook into "Paid Social"). Map GA4 rows to the same channel names as the ad data before reconciling. If GA4 isn't connected, stop and tell the user this workflow requires it.

### Step 2 — Reconcile
Use `scripts/funnel_reconciler.py --ad-platform ads.csv --ga4 ga4.csv`. The script joins by channel name (the `channel` column in both files must use identical values) and computes the divergence between platform-reported and GA4-measured outcomes. Channels where the click-to-session gap exceeds 25% get flagged as likely UTM/tracking issues.

### Step 3 — Visualize the reconciliation
The question the chart needs to answer: **where's the leak — is each channel converting the traffic it bought, or losing it somewhere?**

For a small number of channels (3–5), a paired bar chart per channel works well: one bar for the ad platform metric (e.g. platform-reported CPA), one bar for the GA4 measurement of the same thing (GA4-measured CPA). Big gaps between the pairs are the story. Channels with tracking flags get an amber outline.

When the user wants the funnel view explicitly, a descending bar chart showing impressions → clicks → sessions → conversions makes drop-off rates visible at each stage.

Whichever you build, name the headline above the chart — "Two of four channels have tracking issues" or "Facebook traffic doesn't convert post-click" — don't make the user infer the story.

### Step 4 — Recommendation
> Write a short paragraph recommending how budget should be reallocated next period to prioritize the channel driving the highest-quality website traffic.

The recommendation should name a specific dollar amount, a source channel, a destination channel, and the expected impact on **GA4-measured** conversions (not just ad-platform conversions — that's the whole point).

### Step 5 — Update sales leadership
Build from `assets/sales_leadership_email.md`. Default delivery is markdown inline. If the user wants it as a Word doc, use the `docx` skill. If Gmail is connected, offer to save as a draft. If leadership wants to see this every month, offer to publish it as a live Studio dashboard (see the `manage_dashboards`).

### Common variations
- **Adobe Analytics instead of GA4** — same workflow shape; Supermetrics has Adobe Analytics support, ask whether it's connected.
- **Use last-click instead of GA4's default attribution** — GA4's default is data-driven; the model is a property-level setting, so the API returns whatever the property uses. Session-scoped dimensions (`sessionSourceMedium`) are last-click by nature; ask the user which view they want and note the choice in the deliverable.
- **Join with CRM lead-quality data** — if HubSpot or Salesforce is connected, pull MQL conversion rate by source and join with the reconciliation. 

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

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

View saved version →

---
name: get-started
description: First-run onboarding for Supermetrics. Use right after the user connects Supermetrics, when they ask how to get started or what data they can access, when they want to connect Google Ads, Meta, GA4, LinkedIn or another platform, or when a Supermetrics call fails because they aren't signed in or a source isn't connected.
---

# Get started with Supermetrics

Take the user from install to their first real answer in as few turns as possible. Do each step only if the previous one succeeded.

## 1. Check sign-in

Call `manage_user_and_team` with `action: get_info`.

- **Tool not available or auth error:** the Supermetrics connector isn't connected or signed in. Ask the user to connect or reconnect Supermetrics in their AI app's connector or app settings and sign in with their Supermetrics account (new users get a 14-day free trial, no card). Then stop and wait. Never ask for an API key or password in chat.
- **Signed in, but `license` holds an error, or a tool returns a license or trial error:** don't loop on sign-in. Say so plainly and follow the note in the response; buying is at https://supermetrics.com/pricing, and the plan must include the AI Chats destination. For details, call `supermetrics_guide` with `mode: license_and_trials`.
- **Success:** greet them by name and team in one line.

## 2. See what's connected

Call `data_source_discovery` with `compress: true`; each source's `authentication_status` shows what's connected. Then call `accounts_discovery` for the connected platforms the user cares about. Summarise in one short list: connected platforms and account counts. Don't dump every source.

If nothing relevant is connected, ask which platform they want first (Google Ads, Meta Ads, GA4, LinkedIn Ads, TikTok Ads, Microsoft Ads, Shopify, HubSpot…) and call `manage_user_and_team` with `action: login_data_source` and its `ds_id`. Give them the login link and wait. Never describe clicking through menus; hand over the link. For platform-specific connection help, call `supermetrics_guide` with `mode: connect_data_source`.

## 3. First answer

Once at least one account is connected, run one small useful report straight away — last 7 days vs the previous 7 for spend, clicks, conversions and cost per conversion (or sessions and conversions for GA4) — and show it as a compact chart or table.

## 4. Save their goals

Ask what they're optimizing for (target CPA, ROAS or monthly budget). Save it with `manage_business_context` (`action: save`, tags like `targets`) so later analyses judge results against it. Skip this if a profile already exists.

## 5. Point to what's next

Suggest three questions tailored to what they connected, for example a wasted-spend audit, a weekly performance review, budget pacing, or launching a campaign. Mention that results can be published as a live Supermetrics Studio dashboard.

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

View saved version →

---
name: live-dashboards
description: Plan, build and publish live, shareable marketing dashboards in Supermetrics Studio with manage_dashboards — pages that re-query the user's data on every view and can include campaign management actions. Use when the user asks for a dashboard, a report the team can reopen, a shareable link, or a recurring view (weekly review, pacing, KPIs), and to edit or find existing Studio dashboards.
---

# Live dashboards in Supermetrics Studio

A Studio dashboard is a page stored in Supermetrics Studio that fetches the user's data every time someone opens it, so a shared link always shows current numbers. Dashboards aren't limited to reading data: they can also include campaign management, such as pausing or enabling a campaign or changing a budget straight from the page. The `manage_dashboards` tool uploads, reads, edits and lists them.

**The `manage_dashboards` tool description and its parameter descriptions are the technical source of truth.** Follow them exactly for the code: how to call `smQuery`, how to parse its response, region markers, query keys, date and comparison parameters, `allowed_tools`, `allowed_accounts`, patch types and BigQuery. This skill covers when to offer a dashboard, how to plan it, and what makes it useful.

## When to use

- The user asks for a dashboard, a live report or a link to share.
- An analysis will be reopened: a weekly performance review, a daily check, budget pacing, a monthly SEO or channel review, a client report. Offer a live dashboard once at the end of that analysis; don't push it again if declined.
- The user wants to change, find or see the history of a dashboard they already have.

A one-off question needs a table or chart in the chat, not a dashboard.

## Workflow: new dashboard

### 1. Agree what it's for
Settle this in one short exchange at most, using what the conversation already tells you:
- **Question it answers** — "are we on budget this month?", "how did paid media do this week?", "which campaigns need attention?". One dashboard, one main question.
- **Audience** — the user, their team, leadership or a client. Leadership wants few numbers and trends; a media buyer wants campaign-level detail.
- **Sources and accounts** — which data sources and account IDs. Use `data_source_discovery` and `accounts_discovery` if not known.
- **Controls** — a date range by default; account, channel or campaign selectors and a period comparison if the audience will use them.
- **Actions** — whether viewers should be able to act on what they see, for example pause a campaign from the table or adjust a budget next to its pacing figure.

### 2. Prove the data first
Run each query once with `data_query` and `get_async_query_results`, using exact field IDs from `field_discovery`. Fix wrong fields, missing accounts or connection errors now; a broken query inside a published dashboard only shows an error to every viewer. The results also feed the preview.

### 3. Show a static preview
Build the dashboard with the numbers from step 2 written in and show it in the chat. Keep it close to what will be published, so the user is approving the real layout.

### 4. Confirm, then publish
Ask whether to publish it as a live Studio dashboard, unless the user already asked for a link. Then rebuild the data layer for Studio as the tool instructions describe and upload. Never upload the static preview.

### 5. Hand it over
Check the upload response and act on anything the tool instructions say to fix before sharing. Then give the user the link and one sentence on how to use it ("updates on every view; change the date range at the top").

## Workflow: change an existing dashboard

1. Find it with `list` (filter by a word from the title) unless you have its ID.
2. `get` the current code, then `edit` with the smallest patch that does the job, as the tool instructions describe. Add a short `change_summary`.
3. Use `changelog` when the user asks what changed or when.

## Campaign managem

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

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

View saved version →

---
name: marketing-data-queries
description: How to query live marketing data through Supermetrics without failed queries — discovery, report types, field IDs, date ranges, filters and reading results — for Google Ads, Meta Ads, GA4, LinkedIn Ads, TikTok Ads, Microsoft Advertising, Instagram, Shopify, HubSpot, Search Console and every other connected source. Use before any data_query, for cross-channel or blended questions, and whenever a query errors or returns no data.
---

# Querying marketing data with Supermetrics

Never answer a performance question from memory. Supermetrics returns live data — query it.


## Platform references

Before querying one of these platforms, read its reference file for field IDs, report types, combinations that fail and data-freshness lags:

| Platform | Reference |
|---|---|
| Google Ads (`AW`) | [references/google-ads.md](references/google-ads.md) |
| Meta Ads (`FA`) | [references/meta-ads.md](references/meta-ads.md) |
| Google Analytics 4 (`GAWA`) | [references/google-analytics-4.md](references/google-analytics-4.md) |
| LinkedIn Ads (`LIA`) | [references/linkedin-ads.md](references/linkedin-ads.md) |
| TikTok Ads (`TIK`) | [references/tiktok-ads.md](references/tiktok-ads.md) |
| Microsoft Advertising (`AC`) | [references/microsoft-ads.md](references/microsoft-ads.md) |
| Instagram Insights (`IGI`) | [references/instagram-insights.md](references/instagram-insights.md) |

For any other source, use the workflow below with `field_discovery`.

## The workflow

Follow these steps in order. Skipping discovery is the most common cause of failed queries.

1. **`data_source_discovery()`** — list sources and their auth status. Pick the one the
   user means. If they say "Facebook" or "Meta", that is `FA`; "Google Ads" is `AW`;
   "GA4" is `GAWA`.
2. **`data_source_discovery(ds_id=X)`** — read that source's configuration before
   querying. It tells you what the next steps must be:
   - `has_account_list: true` → call `accounts_discovery(ds_id=X)` for account IDs.
   - `has_report_type_selection: true` → choose a `report_type` and pass it in `settings`.
   - `has_fields: true` → call `field_discovery(ds_id=X)` to get valid field IDs.
   - `is_date_range_required: true` → set a date range (nearly always true).
3. **`field_discovery(ds_id=X, filter="...")`** — filter rather than dumping every field.
   `filter="cost,click,conversion"` is far more useful than the full catalogue.
4. **`data_query(...)`** — dimensions before metrics in `fields`. All fields must belong
   to the same report type.
5. **`get_async_query_results(schedule_id=...)`** — if the query returns a schedule ID
   instead of rows, poll immediately and keep polling until `completed`.

## Business context

Before analyzing a specific account, call `manage_business_context` with `action="get"`
and the `ds_id` (plus `account_id` where relevant). Teams store reporting conventions
there — which campaigns to exclude, which attribution window to use, how to segment.
Applying them is the difference between a correct answer and a plausible one.

If the user states a durable preference mid-conversation ("always exclude brand
campaigns", "we report in EUR"), offer to save it with `action="save"`.

## Writing good queries

- **Dates**: prefer relative ranges (`last_30_days`, `last_month`, `this_month_inc`).
  For anything relative to "now", call `get_today` first — do not assume the date.
- **Comparisons**: `compare_type="prev_range"` or `"prev_year"` answers "how does that
  compare?" in one query instead of two. Other values: `prev_year_weekday`, or `custom` with
  `compare_start_date`/`compare_end_date`. `compare_show` picks `perc_change` (default),
  `abs_change` or `value`.
- **Filters**: `filters="country == US AND clicks > 100"`. Operators include `==`, `!=`,
  `>`, `>=`, `=@` (contains), `=~` (regex), `[]` (in list).
- **Row limits**: default is 1000. Raise `max_rows` for long date ranges broken out by day.

## Reading results

Rows come ba

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

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

View saved version →

---
name: seo-and-content-performance
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.
---

# Seo and content performance

## Workflows

### Paid promotion content analysis
**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.

**Platforms typically involved:** LinkedIn Ads and Facebook Ads primarily. Google Ads sometimes if promoting content in search.

### Step 1 — Pull the data
> 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.].

Ask the user about the naming convention if it's unclear. Data should be at the ad / asset level, not just campaign level.

### Step 2 — Rank the assets
Use `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.

A 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.

### Step 3 — Visualize the ranking
The question the chart needs to answer: **which assets are worth more paid budget, and why?**

A 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.

If 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.

### Step 4 — Qualitative read on the winners
> Identify the top two best-performing assets and explain why their messaging is likely resonating with the target audience.

This 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.

### Step 5 — Output
Default: markdown inline. If the user wants a doc to share with leadership for next-quarter planning, use the `docx` skill.

### Common variations
- **Organic vs paid** — different workflow; organic and paid content perform on different signals. Suggest running paid first, then a separate organic audit.
- **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.

---

### Organic content and SEO performance audit
**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.

**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.

### Step 1 — Pull search performance over time
> Pull the last 6-12 months of Search Console performance by page (and query if needed): impressions, clicks, average position, CTR, split by month.

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

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

View saved version →

---
name: wasted-spend-audit
description: Find wasted ad spend from live data: zero-conversion campaigns and ads, expensive CPAs, budget traps, Google and Microsoft search terms to negate, and the monthly saving. Use for "where am I wasting money", "which search terms should I exclude", "what should I pause" on Google Ads, Microsoft Advertising, Meta and other ad platforms.
---

# Wasted spend audit

## Workflows

### Search term audit and negative keywords
**When to use:** the user runs Google Ads or Microsoft Ads search campaigns and wants to find wasted spend on irrelevant queries, building a negative keyword list to upload to the platform.

**Platforms typically involved:** Google Ads (search campaigns), Microsoft Ads. This workflow doesn't apply to social platforms.

### Step 1 — Pull the search term report
> Pull the search term report from [Google Ads / Microsoft Ads] for the last 30 days, including search term, matched keyword, campaign, ad group, clicks, cost, and conversions.

Fields: Google Ads `Searchterm` (with `Keyword`, `Matchtype`), Microsoft Ads `SearchQuery`. The search term report is the granular log of actual user queries that triggered the ads — distinct from the keyword list, which is what the user bid on. Mismatch between intent and actual query is where waste lives.

### Step 2 — Audit the terms
Use `scripts/search_term_auditor.py`. The script flags queries that:
- Cost more than $X (configurable) with zero conversions
- Have CPC more than 2x the campaign average
- Match obvious irrelevance patterns (competitor brand names, "free", "jobs", "career", "wikipedia" depending on the user's industry context)

The user provides the irrelevance patterns; the script doesn't guess them. If the user doesn't have a list, suggest a starter set based on their industry and confirm.

### Step 3 — Visualize the waste
The question the chart needs to answer: **how much money are these terms costing, and which patterns are the worst?**

A horizontal bar chart of cost-per-term (top 20 worst offenders) is the most useful primary visualization. If the user has clearly grouped patterns (competitor names vs informational queries vs unrelated terms), a stacked bar chart by pattern type surfaces where the largest categories of waste live.

A pie chart or treemap of cost by pattern type works only if there are ≤5 clear categories.

### Step 4 — Build the negative keyword list
Use `assets/negative_keyword_recommendations.md`. For each proposed negative keyword, the doc includes the match type recommendation (exact / phrase / broad), the rationale (cost incurred, related queries impacted), and the campaigns where the negative should be applied.

### Step 5 — Output
Default delivery: the table as a spreadsheet ready for ad-platform upload, using the `xlsx` skill. Most ad platforms accept negative keyword bulk uploads in CSV/XLSX format. If the user prefers, deliver markdown inline.

### Common variations
- **Just one campaign** — filter to a single campaign in step 1.
- **Smaller wins** — lower `--min-cost` below its $50 default (e.g. $20).
- **Already-running negatives** — if the user provides their current negative keyword list, exclude those terms from the recommendations.

---

## Background

Chart choices, principles and gotchas for this area: [references/performance-marketer-guide.md](references/performance-marketer-guide.md).

## Before you analyze

- Load saved targets, budgets and known context with `manage_business_context` (`action: get`) and judge results against them, not generic benchmarks.
- Query correctly: follow the `marketing-data-queries` skill for discovery, field IDs and platform quirks.
- 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.
- Pull, then analyze, as separate steps. Run one heavy query at a time.
- Evidence discipline: treat changes on fewer than ~10 conversions as noise

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

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