1---2name: utm-check3description: >-4 Checks a B2B SaaS company's UTMs, or a GA4 traffic acquisition export, against GA4's default channel rules in the5 order GA4 applies them, finds paid traffic that lands in organic channels and everything that falls into6 Unassigned, flags naming that splits one channel into several rows, and writes one naming scheme with an old to new7 map. Returns PASS or FAIL with severities. Use it before a quarter's campaigns launch, when a channel report looks8 wrong, or when Unassigned grows. Not for conversion tracking or offline imports (use tracking-audit) or for9 pipeline by channel (use pipeline-report).10license: MIT11compatibility: >-12 Works in Claude, ChatGPT, Codex, Cursor and any agent that reads SKILL.md. Reads a connected GA4 property if the13 agent has one, otherwise an export or pasted rows. Python 3 is optional, for the channel check.14metadata:15 author: SHAKEUP16 version: "1.0.0"17 stage: check18 plugin: markops19 homepage: https://www.shakeuphq.com/skills/utm-check20---21 22# UTM check23 24Shows where each tagged link really lands in GA4, and gives the team one naming scheme that lands every channel where it belongs.25 26## Purpose27 28- One job: check UTM values against GA4's default channel group and write one scheme that fixes what fails.29- Stage: check. It ends in a verdict with severities, plus the scheme as its main output.30- It never edits an ad, a link, a GA4 setting or a CRM field. It writes the map; people change the values.31- It never guesses traffic. Sessions come from the reader's export; a link list without sessions counts each link once and says so.32 33## Use when / not34 35| Situation | Use |36| --- | --- |37| Before a quarter's campaigns launch | this skill, on the planned links |38| A channel report looks wrong, or Unassigned grows | this skill, on the GA4 export |39| A new tool, agency or team starts tagging links | this skill, then share the scheme |40| Conversions, enhanced conversions, consent or imports | `tracking-audit` |41| Pipeline per channel from the CRM | `pipeline-report`, which reads the scheme this skill writes |42 43## Inputs44 45| Input | Required | Ways to provide, in order | If missing |46| --- | --- | --- | --- |47| UTM rows: source, medium, campaign | yes | a connected GA4 property (Traffic acquisition: session source / medium, session campaign, sessions, session default channel group, last 90 days); a CSV export; pasted rows; the planned links or each platform's tracking template | ask once |48| Sessions per row | no | the same GA4 export | count each row once; Unassigned share by rows, labelled |49| GA4's reported channel per row | no | the same export | predicted channels only; mismatches not checked |50| The channels the reader reports on | no | `## Channels` in the profile; the reader | Unassigned compared with every channel instead |51| An existing naming rule | no | an accepted `utm-check` learning; the reader's document | start from the scheme in `references/ga4-channel-rules.md` |52| CRM source and medium picklists | no | CRM settings; pasted values | the map covers GA4 only; open item |53 54Use 90 days of GA4 data by default: one quarter of campaigns, long enough for a monthly newsletter to appear 3 times.55 56## Profile read57 58From `company-profile.md`: `## Channels` (active and testing channels, to map onto GA4 channels), `## Accounts and data` (analytics tool, CRM, whether GA4 is connected), `## Company` (Brand terms, so the brand's own domain isn't read as a referral partner), and every `## Learnings` entry for `utm-check` with status `noted`, `fact` or `accepted` (an accepted scheme is the scheme this run checks against).59 60No profile: ask for the channels the team runs and the analytics tool, in one message. Say that `company-profile` saves this next time.61 62## Steps63 641. **Apply learnings.** An accepted scheme or an accepted exception ("we keep `newsletter` as the medium for our own list") overrides the defaults below. Name each one that fires.65 662. **Map the reader's channels to GA4 channels.** From `## Channels`: Google Ads and Microsoft Ads to Paid Search; LinkedIn, Meta, Reddit and X ads to Paid Social; YouTube ads to Paid Video; SEO to Organic Search; founder and company posts to Organic Social; newsletters to Email; partners and review sites to Referral; podcasts to Audio. These are the channels the reader reports on.67 683. **Classify every row** with the script:69 70 ```71 python3 scripts/channel_check.py --csv ga4_export.csv --report-channels "Paid Search,Paid Social,Organic Search,Email" \72 --campaign-pattern "^\d{4}-q[1-4]_[a-z0-9-]+_[a-z0-9-]+$"73 ```74 75 Add a `paid` column (yes or no) when the reader says which links are ads: a medium like `video` doesn't show it.76 77 Without Python, use the ordered table in `references/ga4-channel-rules.md`: lowercase the source, medium and campaign, test each rule from the top, and stop at the first match. Use the site lists there; a source not on them is `unknown_source`. Say which way you ran it.78 794. **Record findings per row.**80 81 | Finding | When | Severity | Why |82 | --- | --- | --- | --- |83 | `paid_outside_paid` | The medium or source says paid (paid, cpc, ppc, cpm, ads, sponsored, boosted, retargeting, promoted), or the reader says the link is for an ad, but the row lands outside the paid channels | critical | Paid spend shows as free traffic: organic looks better and paid looks worse |84 | `unassigned` | The row lands in Unassigned | warning | Nobody reports on it |85 | `paid_other_known` | Paid traffic from a known platform lands in Paid Other because the source value isn't on Google's list (`meta`, `google.com`, `x.com`) | warning | The platform's channel undercounts |86 | `shop_trap` | The campaign name sends the row to a Shopping channel | warning | B2B traffic reported as shopping |87 | `case` | Capitals in source, medium or campaign | warning | 2 rows for one value in every report |88 | `spaces` | Spaces, "+" or "%20" in a value | warning | Values break in links and split rows |89 | `no_campaign` | A paid row with no campaign name | warning | Spend can't be tied to a campaign |90 | `campaign_pattern` | The campaign doesn't follow the scheme's pattern | warning | Reports can't filter by quarter, theme or audience |91 | `split_source` | One platform under several source values | warning | One channel spread over several rows |92 | `unknown_source` | The source isn't on the script's subset of Google's lists | note | Check it against Google's full list before trusting the channel |93 | mismatch | GA4's reported channel differs from the predicted one | note | GA4 used a rule the values can't show (auto-tagging, its referrer lists) or the subset is missing the source |94 955. **Test Unassigned against the channels that matter.**96 97 | Condition | Severity | Why |98 | --- | --- | --- |99 | Unassigned sessions are at least the sessions of a channel the reader reports on | critical | Unassigned traffic could change which channel looks bigger |100 | Unassigned above 0, smaller than every reported channel | warning | Small now, and it grows with each new tool |101 | No Unassigned rows | pass | |102 103 Rows the reader has accepted as known Unassigned (events, print) still count here, labelled.104 1056. **Write the scheme.** Start from the scheme in `references/ga4-channel-rules.md`. Keep every existing value that already lands in the right channel. Change only values with a critical or warning finding. Use the reader's campaign pattern if 80% or more of campaign rows already follow one pattern (most of the team already uses it); else use the scheme's `<year>-q<quarter>_<theme>_<audience>`.106 1077. **Write the map.** One row per value that changes: old source and medium, new source and medium, the channel it lands in now and after, the sessions affected, and where to change it (the ad platform's tracking template or URL options, the link builder, the email tool, the CRM picklist and hidden fields).108 1098. **Name what the scheme can't fix.** Traffic types with no default channel (events, print, QR codes), and channels the reader wants reported apart (ChatGPT Ads land in Paid Other): the default group can't be edited, so the fix is a rule in the property's primary channel group. Recommend it; don't make it.110 111## Check and verdict112 113| Verdict | Condition (first match wins) |114| --- | --- |115| `BLOCKED` | No UTM rows after asking |116| `FAIL` | Any critical finding: paid traffic outside the paid channels, or Unassigned at least the size of a reported channel |117| `PASS WITH NOTES` | Warnings or notes only |118| `PASS` | No findings |119 120Named stop: `BLOCKED` asks for the rows. No other stops: a FAIL still delivers the scheme and the map.121 122## Learn123 124- The reader accepts the scheme: write a `fact` learning with the scheme's sources, mediums and campaign pattern in one line, so later runs check against it.125- The reader keeps a value the check flagged ("our own newsletter stays `newsletter`"): write a `proposal` to accept it as known Unassigned.126- A source GA4 classified differently from the script: write a `fact` naming the source and GA4's channel.127 128Example: `- 2026-10-24 | utm-check | fact | Scheme accepted: linkedin/paid-social, google/cpc, newsletter/email, campaign <year>-q<n>_<theme>_<audience> | Why: reader confirmed in this run | Status: noted`129 130## Output131 132```133Verdict: <PASS | PASS WITH NOTES | FAIL | BLOCKED> · Coverage: <complete | partial (no sessions, no reported channel)> · Check: <script | by hand>134Rows: <n> · Sessions: <n or "not available"> · Unassigned: <n sessions, n% (or rows)>; reported channels not larger: <list or none>135Counts: <n> critical, <n> warnings, <n> notes136 137| Source / medium | Campaign | Sessions | Lands in | Finding | Severity | Fix |138(critical first, then by sessions)139 140Split sources: <platform: values>141The scheme: <table: use, utm_source, utm_medium, GA4 channel; campaign pattern; content and term rules>142The map: <table: old, new, channel now, channel after, sessions, where to change it>143Can't be fixed by naming: <list, with the primary channel group rule to add>144Learnings applied: <list, or none>145```146 147Then the handoff block.148 149## Hand off150 151```handoff152skill: utm-check153version: 1.0.0154verdict: FAIL155coverage: complete156for: <property or link list>, <period>157outputs:158 unassigned_share: 0.07159 paid_outside_paid_sessions: 1240160 scheme:161 linkedin_ads: linkedin / paid-social162 google_ads: google / cpc163 newsletter: newsletter / email164 campaign: <year>-q<quarter>_<theme>_<audience>165 values_to_change: 6166next: [pipeline-report, crm-feedback-loop]167open: [CRM picklists not checked]168```169 170`pipeline-report` reads `scheme` to group CRM sources the same way GA4 does. `self-reported-attribution` reads it to name the software channel beside each answer.171 172## Failure modes173 174| Problem | Do this |175| --- | --- |176| The export has "Session source / medium" in one column | Split on " / "; the script does this |177| GA4's reported channel and the prediction disagree on auto-tagged Google Ads rows | Trust GA4: those rows use platform rules |178| The reader asks what share of Unassigned is normal | There's no such figure in this skill; compare with their own last 90 days and with their smallest reported channel |179| A source looks like a search or social site but isn't on the subset | Mark `unknown_source`; ask the reader to check Google's downloadable list, or pass it with `--sources` |180| The brand's own domain appears as a referral | Note it as self-referral (a cross-domain or payment step); it's a tracking setup issue for `tracking-audit` |181| Planned links only, no traffic yet | Check every link the same way; the Unassigned test uses rows, labelled |182 183## Influenced by184 185- Google's documentation of the GA4 default channel group, the ordered rules and source lists this check applies: https://support.google.com/analytics/answer/9756891?hl=en186- SHAKEUP's UTM builder naming rule: source and medium from fixed lists, campaign as quarter, theme and audience, and the same values in the CRM.