event-tracking-skill

Use this skill as the end-to-end coordinator for GA4 + GTM tracking delivery. Use it when: • the user needs a full GA4 + GTM implementation flow, from analysis to go-live readiness • the request spans multiple workflow phases (discovery, schema, sync, verification, publish) • the correct entry point is still unclear and you need this skill to route to the right phase Do not assume the user wants the full workflow. <!-- event-tracking auto-update bootstrap:start -->

This installed root skill can self-check for newer GitHub versions before you continue. Before doing any task in this bundle: • Resolve the directory that contains this installed SKILL.md. For Codex installs it is usually $CODEX_HOME/skills/event-tracking-skill or ~/.codex/skills/event-tracking-skill. • Run node "<bundle-dir>/runtime/skill-runtime/update-check.mjs" --json. • If the result status is update_available, immediately run node "<bundle-dir>/runtime/skill-runtime/self-update.mjs" --apply. • If the update succeeds, read <bundle-dir>/SKILL.md again before continuing so you are using the refreshed instructions. • If the result status is disabled, treat this bundle as a local development link or repo checkout and continue without updating. <!-- event-tracking auto-update bootstrap:end -->

The skill family is split into one umbrella skill plus seven phase skills: • tracking-discover for crawl coverage, platform detection, and fresh artifact bootstrap • tracking-group for page-group authoring and approval • tracking-live-gtm for auditing the real live GTM runtime before schema generation • tracking-schema for schema preparation, review, validation, and approval • tracking-sync for GTM config generation and sync • tracking-verify for preview QA and optional publish handoff • tracking-shopify for Shopify-specific schema, sync, install, and verification rules If the request is already bounded to one phase and that phase skill is available, route there instead of inlining the full runbook here. Once site-analysis.json indicates Shopify, keep discovery and grouping shared, then let tracking-shopify own the Shopify-specific branch.

• Use the repo-local wrapper ./event-tracking for CLI commands in this repository. If the wrapper reports that dist/cli.js is missing, run npm run build first. • Keep one artifact directory per site (<output-root>/<url-slug>). Each iteration inside that artifact should use a distinct run ID with snapshots under versions/<run-id>/. • If the user already provides an artifact directory or one of its files, resume from the earliest unmet prerequisite instead of restarting from analyze. • Use ./event-tracking status <artifact-dir-or-file> whenever the current checkpoint or next step is unclear. • Use ./event-tracking runs <output-root> when the user wants to find recent site runs and does not remember the artifact directory. • Google OAuth client metadata is embedded in the CLI and may be overridden with GOOGLE_OAUTH_CLIENT_ID / GOOGLE_OAUTH_CLIENT_SECRET. • Any Playwright-backed or OAuth-triggering step must run outside a sandboxed environment by default. In practice, treat analyze, validate-schema --check-selectors, preview, and sync as non-sandbox commands, and do not first attempt them in the sandbox before retrying after interception. • Never auto-select a GTM account, GTM container, or GTM workspace on the user's behalf. Always show candidates and require explicit confirmation unless the user already provided the exact ID for that step. • Prefer scenario-first entry commands for user-facing flows: run-new-setup, run-tracking-update, run-upkeep, run-health-audit. Use start-scenario when the user wants a labeled scenario run without immediate template execution. • Use ./event-tracking scenario <artifact-dir> --set <scenario> [--sub-scenario ...] [--new-run] for metadata-only adjustments when you should not alter execution flow. • Use ./event-tracking scenario-check <artifact-dir> when the question is "is this scenario ready" rather than "what is the next workflow checkpoint". • Use ./event-tracking scenario-transition <artifact-dir> --to <scenario> [--reason ...] when the user wants an auditable handoff between scenarios. • Do not continue past the phase boundary the user asked for. Stop after the requested phase unless the user explicitly asks to continue.