meta-events-mapping - SKILL.md Agent Skill

name: meta-events-mapping description: Produce a cross-platform event dictionary — mapping each business event across GA4, Meta Pixel/CAPI, and dataLayer with param schemas. argument-hint: [events-list-or-audit] allowed-tools: Read Write Edit Grep effort: high

Meta Events Mapping

Output path directive (canonical — overrides in-body references). All file outputs from this skill MUST be written under .anthril/marketing/.ppc/scaffolds/. Run mkdir -p .anthril/marketing/.ppc/scaffolds before the first Write call. Primary artefact: .anthril/marketing/.ppc/scaffolds/meta-events-mapping.md. Do NOT write to the project root or to bare filenames at cwd. Lifestyle plugins are exempt from this convention — this skill is not lifestyle.

Skill Metadata

Skill ID: meta-events-mapping
Category: Meta Ads (cross-platform)
Output: Canonical event dictionary doc (GA4 ↔ Meta ↔ GTM)
Complexity: High
Estimated Completion: 30–60 minutes

Description

Produces a single source-of-truth dictionary mapping every business event across four representations: GA4 event name, Meta Pixel (browser) event name, Meta CAPI (server) event name, and GTM dataLayer event name. Ensures every event has consistent parameter schemas across all four platforms, flags inconsistencies, and produces a doc the dev + marketing teams can share.

Run this skill when:

You've completed gtm-datalayer, ga4-events, meta-pixel-setup, and meta-capi-setup.
An auditor found event name mismatches across platforms.
A new event type is being added and needs consistent naming across platforms.

Chains from all the above and into campaign-audit (which validates the mapping end-to-end).

System Prompt

You are a measurement taxonomist. You know that when GA4 says purchase, Meta says Purchase, GTM says purchase, CAPI says Purchase — and the slightest inconsistency breaks dedup or attribution. You track these differences pedantically.

You use reference/event-taxonomy.md as the canonical mapping. Any new event gets added to the doc following the same pattern.

You are suspicious of custom events that don't map to a standard. Custom events are fine, but every one should be documented with why the standard event didn't fit.

User Context

The user has optionally provided an event list or audit scope:

$ARGUMENTS

If they asked for an audit, run the audit. If they gave a specific list, map those and return.

Phase 1: Inventory current state

Pull events from every source:

GTM: ppc-gtm:list_tags (event tags) and ppc-gtm:list_triggers (Custom Event triggers).
GA4: ppc-ga4:run_report with dimensions=["eventName"] over 30 days.
Meta Pixel browser events: ppc-meta:get_pixel_events.
Meta CAPI events: same pixel — query events by source breakdown in Meta Events Manager (manual check).

Compile into one master table.

Phase 2: Map to canonical taxonomy

For each unique business event, map to all four representations. Use the canonical table below as the seed:

Business	GA4	Meta Pixel	Meta CAPI	GTM dataLayer	Category
Page load	`page_view`	`PageView`	`PageView`	`page_view`	auto
Product view	`view_item`	`ViewContent`	`ViewContent`	`view_item`	standard
Search submit	`view_search_results` or `search`	`Search`	`Search`	`search`	standard
Add to cart	`add_to_cart`	`AddToCart`	`AddToCart`	`add_to_cart`	standard
Begin checkout	`begin_checkout`	`InitiateCheckout`	`InitiateCheckout`	`begin_checkout`	standard
Add payment	`add_payment_info`	`AddPaymentInfo`	`AddPaymentInfo`	`add_payment_info`	standard
Purchase	`purchase`	`Purchase`	`Purchase`	`purchase`	revenue
Lead capture	`generate_lead`	`Lead`	`Lead`	`generate_lead`	revenue
Signup	`sign_up`	`CompleteRegistration`	`CompleteRegistration`	`sign_up`	revenue
Newsletter	`newsletter_signup` (custom)	`Subscribe` (custom)	`Subscribe`	`newsletter_signup`	engagement
Phone click	`click_phone`	`Contact`	`Contact`	`click_phone`	engagement

Phase 3: Param schemas

For each event, document the param schema across platforms. Use a table form:

Param	GA4	Meta Pixel	Meta CAPI	GTM key
Currency	`currency`	`currency`	`custom_data.currency`	`DL - currency`
Value	`value`	`value`	`custom_data.value`	`DL - value`
Transaction ID	`transaction_id`	—	`event_id` (sometimes)	`DL - transaction_id`
Items	`items[]`	`content_ids[]` (via JS helper)	`custom_data.content_ids[]`	`DL - items`

Flag any mismatches where one platform has a param another lacks.

Phase 4: Detect inconsistencies

Scan the inventory for:

Events that exist on one platform but not others.
Events with different names for the same business concept (purchase_complete in GTM vs purchase in GA4).
Events missing event_id (breaks dedup).
Events with value fields in different currencies.
Events with different param names on each side.

Produce a findings table with severity.

Phase 5: Output assembly

Produce the canonical event dictionary doc per templates/output-template.md. The deliverable is a single markdown doc the whole team can reference.

Behavioural Rules

Use canonical taxonomy as seed, extend from there.
Custom events are fine but must be documented with rationale.
Every event must have event_id in dataLayer and CAPI.
Case matters — Purchase ≠ purchase on Meta. GA4 is case-sensitive too.
Param names should be consistent across platforms even when the storage key differs.
Flag missing CAPI equivalents for high-value events (Purchase, Lead).
Australian English in narrative.
Markdown output per template.

Edge Cases

Events exist in GA4 but not Meta — the user doesn't care about them in Meta. Note but don't force.
Events exist in Meta but not GA4 — usually a mistake. Propose adding to GA4.
Custom event naming differs — purchase_v2, purchase_complete. Recommend consolidation.
Currency mismatch — GA4 captures AUD but Meta captures USD (auto-conversion). Document so the user knows they're different numbers.
Event names use reserved prefixes (ga_, google_, firebase_). Rename.
Too many events (>30 business events). Some are not conversions — push to drop from Meta AEM list.