by jtrackingai
AI-powered GA4 + GTM event tracking — automates site analysis, event schema, GTM sync, preview verification, and publishing. Works with Cursor, Codex, and any AI agent.
# Add to your Claude Code skills
git clone https://github.com/jtrackingai/event-tracking-skillUse this skill as the end-to-end coordinator for GA4 + GTM tracking delivery.
Use it when:
Do not assume the user wants the full workflow.
This installed root skill can self-check for newer GitHub versions before you continue.
Before doing any task in this bundle:
SKILL.md. For Codex installs it is usually $CODEX_HOME/skills/event-tracking-skill or ~/.codex/skills/event-tracking-skill.node "<bundle-dir>/runtime/skill-runtime/update-check.mjs" --json.update_available, immediately run node "<bundle-dir>/runtime/skill-runtime/self-update.mjs" --apply.<bundle-dir>/SKILL.md again before continuing so you are using the refreshed instructions.disabled, treat this bundle as a local development link or repo checkout and continue without updating.The skill family is split into one umbrella skill plus seven phase skills:
tracking-discover for crawl coverage, platform detection, and fresh artifact bootstraptracking-group for page-group authoring and approvaltracking-live-gtm for auditing the real live GTM runtime before schema generationtracking-schema for schema preparation, review, validation, and approvaltracking-sync for GTM config generation and syncevent-tracking-skill is a local-first skill and CLI for planning, generating, validating, and syncing GA4 event tracking in Google Tag Manager.
It keeps the implementation reviewable from crawl to publish:
For a given website, this skill can help you:
dataLayer usageThere are two install paths:
npx skills add ...Most users only need the umbrella skill.
If you want the built-in installer, first clone the repo and run the installer from the repo root:
No comments yet. Be the first to share your thoughts!
tracking-verify for preview QA and optional publish handofftracking-shopify for Shopify-specific schema, sync, install, and verification rulesIf 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.
./event-tracking for CLI commands in this repository. If the wrapper reports that dist/cli.js is missing, run npm run build first.<output-root>/<url-slug>). Each iteration inside that artifact should use a distinct run ID with snapshots under versions/<run-id>/.analyze../event-tracking status <artifact-dir-or-file> whenever the current checkpoint or next step is unclear../event-tracking runs <output-root> when the user wants to find recent site runs and does not remember the artifact directory.GOOGLE_OAUTH_CLIENT_ID / GOOGLE_OAUTH_CLIENT_SECRET.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.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../event-tracking scenario <artifact-dir> --set <scenario> [--sub-scenario ...] [--new-run] for metadata-only adjustments when you should not alter execution flow../event-tracking scenario-check <artifact-dir> when the question is "is this scenario ready" rather than "what is the next workflow checkpoint"../event-tracking scenario-transition <artifact-dir> --to <scenario> [--reason ...] when the user wants an auditable handoff between scenarios.When the user enters through chat and has not yet provided a bounded phase, artifact directory, or exact command, start with an intent-first intake.
Classify the request into one of these entry intents:
resume_existing_run: the user already has an artifact directory or one of its files; inspect the artifacts and use statusnew_setup: net-new tracking implementation from scratch; prefer run-new-setup, then follow its recommended next steptracking_update: revise or extend an existing implementation; prefer run-tracking-updateupkeep: routine maintenance, review, or incremental QA on an existing setup; prefer run-upkeeptracking_health_audit: audit-only assessment of current live tracking; prefer run-health-auditanalysis_only: crawl/bootstrap/discovery only without committing to the full workflow yet; route to tracking-discover and stop after analyzeRules:
scenario and analyze. scenario is run-intent orchestration metadata; analyze is only one execution step.new_setup.analysis_only.resume_existing_run instead of restarting from analyze.Route by user intent and current artifacts:
tracking-discoversite-analysis.json with missing or unconfirmed pageGroups: route to tracking-groupsite-analysis.json with detected live GTM container IDs but no live baseline review yet: route to tracking-live-gtmsite-analysis.json or an in-progress event-schema.json: route to tracking-schemagtm-config.json: route to tracking-syncgtm-context.json: route to tracking-verify, with publish treated as a separate explicit actiontracking-shopifyIf only the root skill is available, follow the same routing logic directly and stop at the matching phase boundary.
prepare-schema.pageGroups (before confirm-page-groups and before prepare-schema)event-schema.json (before confirm-schema and before generate-gtm)sync)publish)generate-gtm unless the user explicitly wants --force.tracking-health.json as the publish gate; do not jump to publish when health is missing, manual-only, or blocked unless the user explicitly wants --force.tracking_health_audit as an audit-only scenario. Do not run GTM deployment actions (generate-gtm, sync, publish) unless the user explicitly asks to override.When resuming:
workflow-state.json when presentstatus when the next step is unclearWhen a phase or the full workflow ends, summarize:
workflow-state.jsongit clone https://github.com/jtrackingai/event-tracking-skill.git
cd event-tracking-skill
npm run install:skills
That installs event-tracking-skill into the default skills directory with installer-managed auto-update metadata.
You do not need npm ci just to install the exported skill bundles.
If you already know you want the full phase-oriented family installed together, make that explicit:
npm run install:skills -- --with-phases
This is the recommended install path for Codex and also the most portable path for other agent environments that can load skills from a local directory.
Codex defaults:
$CODEX_HOME/skills when CODEX_HOME is set~/.codex/skillsFor other agent runtimes, point the installer at that runtime's skills directory:
npm run install:skills -- --target-dir /path/to/agent/skills
If you also want the phase skills in a custom directory:
npm run install:skills -- --target-dir /path/to/agent/skills --with-phases
For local development only, if you want the installed skills to stay pointed at local exported bundles:
npm run install:skills -- --mode link
To link the full skill family during local iteration:
npm run install:skills -- --mode link --with-phases
Auto-update behavior:
copy installs are the recommended user path and can self-check for newer GitHub versionslink installs are for local development only and intentionally do not auto-update from GitHubnpm run install:skills before they gain the installed auto-update bootstrapUse docs/README.codex.md for Codex-specific defaults, update notes, and troubleshooting. Use docs/README.install.md for the full shared agent-install guide.
Use this if you want to install the skill into your local agent skills directory without cloning the repository first.
npx skills add jtrackingai/event-tracking-skill
This portable install can self-check for updates too. On the first successful self-update it rewrites the installed copy into the repo's normal copy-mode layout.
If you want the full umbrella + phase-skill family installed together from the start, use npm run install:skills -- --with-phases.
If you want the repo-local CLI, contributor setup, or local development workflow, use DEVELOPING.md instead of treating README as a maintainer guide.
The repository now has:
event-tracking-skillskills/: tracking-discover, tracking-group, tracking-live-gtm, tracking-schema, tracking-sync, tracking-verify, tracking-shopifyUse the umbrella skill for end-to-end or ambiguous requests. Use the phase skills when the user clearly wants only one part of the workflow, such as discovery, grouping, live GTM baseline review, schema review, GTM sync, preview QA, or Shopify-specific handling.
See docs/skills.md for the full map.
Root skill UI metadata now lives in agents/openai.yaml.
If you need to package these skills outside this repository, generate self-contained bundles with:
npm run export:skills
That writes per-skill bundles to dist/skill-bundles/<skill-name>/.
Each exported bundle includes:
SKILL.mdagents/openai.yamlreferences/ files that the skill may need, including exported architecture.md and skill-map.md where relevantThe exported bundles rewrite command examples to the public event-tracking command name. Inside this repository, keep using ./event-tracking.
Use scenario templates when you already know the delivery intent and want versioned run history grouped by scenario from the start.
For a brand-new URL with no artifacts yet, run-new-setup is a labeled entry point, not a replacement for analyze; it will usually point you to analyze as the first execution command.
# New implementation from scratch
./event-tracking run-new-setup ./output/example_com
# Incremental update for existing tracking
./event-tracking run-tracking-update ./output/example_com --baseline-schema ./output/example_com/schema-restore/confirmed-<hash>.json
# Routine upkeep check
./event-tracking run-upkeep ./output/example_com --baseline-schema ./output/example_com/schema-restore/confirmed-<hash>.json
# Audit-only health assessment before deciding rebuild
./event-tracking run-health-audit ./output/example_com --live-gtm-analysis ./output/example_com/live-gtm-analysis.json
Use these helpers when needed:
./event-tracking scenario <artifact-dir> --set <scenario> --new-run [--sub-scenario ...] [--input-scope ...] to relabel or branch a run without executing a workflow step./event-tracking scenario-check <artifact-dir> to validate scenario-required artifacts and return the next scenario step./event-tracking scenario-transition <artifact-dir> --to <scenario> --reason "<why>" to record scenario handoff decisions./event-tracking runs <output-root> --json to inspect recent runs with scenario summaryScenario guardrails:
tracking_health_audit is audit-only. generate-gtm, sync, and publish are blocked by default unless explicitly forced.upkeep).scenario-check is a readiness check for the current scenario contract; use status when you need checkpoint, warning, and gate details.In an agent conversation, the first turn should be an intent-first intake, not a CLI choice.
Do not ask the user whether they want scenario or analyze; ask which of these plain-language entry paths they need:
Internal mapping:
run-new-setup, run-tracking-update, run-upkeep, and run-health-auditanalyze only maps to tracking-discover / analyze and stops after discoverystatus and resume-from-current-checkpoint behaviorIf you are using this in an agent environment, call it in natural language and provide the current workflow inputs:
Use event-tracking-skill to set up GA4 / GTM tracking for https://www.example.com.
Use ./output as the output root directory.
GA4 Measurement ID is G-XXXXXXXXXX.
Google tag ID is GT-XXXXXXX if needed.
The skill creates the run artifact directory as <output-root>/<url-slug> and then walks through grouping, conditional live GTM baseline review, schema review, GTM generation, sync, preview, and publish.
Start with site analysis:
./event-tracking analyze https://www.example.com --output-root ./output
The CLI creates the artifact directory automatically as <output-root>/<url-slug>, for example ./output/example_com.
After filling and reviewing pageGroups in ./output/example_com/site-analysis.json, continue with the same artifact directory:
./event-tracking conf