name: event-tracking-skill description: Use when you need end-to-end GA4 + GTM tracking delivery across discovery, schema, sync, and verification phases. compatibility: > Requires Node.js 18+, npm, and Playwright Chromium for browser-backed steps. Analyze, selector validation, preview, and GTM sync must run outside sandboxed environments. GTM sync uses interactive Google OAuth and caches credentials in the artifact directory. Optional anonymous telemetry is opt-in and can be disabled with DO_NOT_TRACK=1 or EVENT_TRACKING_TELEMETRY=0.

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.

Auto-Update

This installed root skill can self-check for newer GitHub versions before you continue.

Before doing any task in this bundle:

1. Resolve the directory that contains this installed SKILL.md. Installer-managed copies usually live under the skills directory configured by your agent environment, such as $CODEX_HOME/skills/event-tracking-skill or an equivalent runtime-managed path.
2. Run node "<bundle-dir>/runtime/skill-runtime/update-check.mjs" --json.
3. If the result status is update_available, immediately run node "<bundle-dir>/runtime/skill-runtime/self-update.mjs" --apply.
4. If the update succeeds, read <bundle-dir>/SKILL.md again before continuing so you are using the refreshed instructions.
5. If the result status is disabled, treat this bundle as a local development link or repo checkout and continue without updating.

Skill Family

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.

Shared Contract

1. 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. This bundle assumes Node.js 18+, npm, and Playwright Chromium are available for browser-backed commands.
2. 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>/.
3. If the user already provides an artifact directory or one of its files, resume from the earliest unmet prerequisite instead of restarting from analyze.
4. Use ./event-tracking status <artifact-dir-or-file> whenever the current checkpoint or next step is unclear.
5. Use ./event-tracking runs <output-root> when the user wants to find recent site runs and does not remember the artifact directory.
6. Google OAuth client metadata is embedded in the CLI and may be overridden with GOOGLE_OAUTH_CLIENT_ID / GOOGLE_OAUTH_CLIENT_SECRET.
7. 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.
8. Run prompt-driven OAuth / GTM selection commands with an interactive TTY from the start. In practice, run sync with TTY enabled unless the user already provided exact --account-id, --container-id, and --workspace-id values. Do not first try non-interactive sync and then retry with TTY.
9. GTM OAuth credentials are cached per artifact at <artifact-dir>/credentials.json; local migration code may also clear or import older credential files when the user asks to reuse or clear stored auth.
10. Anonymous usage telemetry is opt-in. It stores consent in the local user config, never sends full URLs, file paths, selectors, GTM/GA IDs, OAuth data, or raw errors, and is disabled by DO_NOT_TRACK=1 or EVENT_TRACKING_TELEMETRY=0.
11. 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.
12. 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.
13. Use ./event-tracking scenario <artifact-dir> --set <scenario> [--sub-scenario ...] [--new-run] for metadata-only adjustments when you should not alter execution flow.
14. Use ./event-tracking scenario-check <artifact-dir> when the question is "is this scenario ready" rather than "what is the next workflow checkpoint".
15. Use ./event-tracking scenario-transition <artifact-dir> --to <scenario> [--reason ...] when the user wants an auditable handoff between scenarios.
16. Do not continue past the phase boundary the user asked for. Stop after the requested phase unless the user explicitly asks to continue.

Conversation Intake

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 status
• new_setup: net-new tracking implementation from scratch; prefer run-new-setup, then follow its recommended next step
• tracking_update: revise or extend an existing implementation; prefer run-tracking-update
• upkeep: routine maintenance, review, or incremental QA on an existing setup; prefer run-upkeep
• tracking_health_audit: audit-only assessment of current live tracking; prefer run-health-audit
• analysis_only: crawl/bootstrap/discovery only without committing to the full workflow yet; route to tracking-discover and stop after analyze

Rules:

• Do not ask the user to choose between scenario and analyze. scenario is run-intent orchestration metadata; analyze is only one execution step.
• If intent is ambiguous, ask one short plain-language intake question using user-facing terms such as "new setup", "update existing tracking", "upkeep", "health audit", "analyze only", or "resume an existing run".
• If the user gives a fresh URL and asks to set up tracking, default to new_setup.
• If the user gives a fresh URL and only asks to inspect the site, analyze structure, or review current tracking signals, default to analysis_only.
• If the user gives an artifact directory or workflow file, default to resume_existing_run instead of restarting from analyze.

Routing Rules

Route by user intent and current artifacts:

• fresh URL, crawl request, or no artifacts yet: start with tracking-discover
• site-analysis.json with missing or unconfirmed pageGroups: route to tracking-group
• confirmed site-analysis.json with detected live GTM container IDs but no live baseline review yet: route to tracking-live-gtm
• confirmed site-analysis.json or an in-progress event-schema.json: route to tracking-schema
• gtm-config.json: route to tracking-sync
• gtm-context.json: route to tracking-verify, with publish treated as a separate explicit action
• Shopify platform confirmation: keep shared early stages, then hand off to tracking-shopify

If only the root skill is available, follow the same routing logic directly and stop at the matching phase boundary.

Stop Rules

• Do not bypass page-group approval before prepare-schema.
• For key decision checkpoints, always require explicit user confirmation before continuing:
  • pageGroups (before confirm-page-groups and before prepare-schema)
  • event-schema.json (before confirm-schema and before generate-gtm)
  • GTM target selection (account/container/workspace during sync)
  • publish decision (before publish)
• If confirmation is missing or ambiguous, stop and ask; do not auto-proceed.
• When live GTM containers are detected on the site, do not bypass the live baseline review before schema generation.
• Do not bypass schema approval before generate-gtm unless the user explicitly wants --force.
• Treat preview QA and publish as separate decisions.
• Treat 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.
• Treat Shopify manual verification as the expected path for Shopify runs, not as a fallback error case.
• Treat 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.

Resume And Closeout

When resuming:

• prefer workflow-state.json when present
• still inspect the real artifact set if warnings indicate stale gates
• use status when the next step is unclear

When a phase or the full workflow ends, summarize:

• first give a compact, decision-ready summary in plain language
• keep the default chat summary human-readable; do not dump raw JSON, raw URL lists, or artifact inventory first
• for page grouping, summarize group count, grouping logic, and a compact group table before any file references
• for schema review, default to Event Table, then Common Properties, then Event-specific Properties
• keep tracking_health_audit and upkeep as separate summary modes even if they share rendering helpers
• only after the summary, list artifact directory, current checkpoint, key output files, next recommended command, and remaining manual actions

References

• skill-map.md for the umbrella / phase skill map
• architecture.md for lifecycle, checkpoints, and resume semantics
• output-contract.md for artifact files and gate semantics
• shopify-workflow.md for Shopify-specific branch expectations

Event Tracking Skill

event-tracking-skill is a local-first AI skill for planning, reviewing, and delivering GA4 + GTM tracking.

Use it when you want an agent to help with:

• analyzing a site before tracking work starts
• grouping pages by business purpose
• designing or reviewing a GA4 event plan
• comparing a proposed plan with an existing live GTM setup
• preparing GTM-ready outputs and verification guidance
• handling both generic websites and Shopify storefronts

This README is intentionally user-facing and conversation-first. If you need the CLI surface or maintainer workflow, use DEVELOPING.md.

What You Get

For a given website, this skill can help produce:

• a reviewable site analysis
• business-friendly page groups
• a compact, decision-ready tracking plan
• GTM-ready tracking outputs
• verification and health summaries before go-live
• artifact-backed progress that can be resumed later

Installation

Most users only need the umbrella skill.

Recommended

Clone the repository locally, then install the skill into your agent skills directory:

git clone https://github.com/jtrackingai/event-tracking-skill.git
cd event-tracking-skill
npm run install:skills

No-Clone Alternative

If you do not want to clone the repository, install the root skill directly:

npx skills add jtrackingai/event-tracking-skill

For advanced install options and exported skill bundles:

• docs/README.install.md
• docs/skills.md

ClawHub Publish

If you are publishing this skill to ClawHub, publish the exported public bundle instead of the full repository:

npm run export:skills:clawhub

Then upload dist/clawhub-skill-bundles/event-tracking-skill.

That public bundle keeps the agent-facing skill docs and references, but strips the bundled auto-update runtime and other maintainer-only packaging files that trigger broader security scans.

Quick Start

Use It As A Skill

The intended experience is simple: tell your agent what you want in plain language.

Good requests usually include one or more of:

• the site URL
• whether this is a new setup, update, upkeep, or audit
• the output root for a new site run, such as ./output or /tmp/output
• an existing site artifact directory if you already have one, such as ./output/example_com
• GA4 measurement ID or GTM context when you already know them
• any scope boundary such as "stop after schema review"

For a new setup, the output root is not the artifact directory itself. The agent/CLI creates one artifact directory per site under that root, for example ./output/example_com.

Example Prompts

New setup from scratch:

Use event-tracking-skill to plan GA4 + GTM tracking for https://www.example.com.
Use ./output as the output root; create the site artifact directory under it.
Start from a fresh run and stop after the event schema is ready for review.

New setup with implementation context:

Use event-tracking-skill to set up tracking for https://www.example.com.
Use /tmp/output as the output root, so this site's artifacts go under /tmp/output/www_example_com.
GA4 Measurement ID is G-XXXXXXXXXX.
We care most about signup, pricing, contact, and demo intent.

Audit only:

Use event-tracking-skill to run a tracking health audit for https://www.example.com.
I only want to understand the current live GTM setup and whether we should repair or rebuild.
Do not continue into deployment work.

Routine upkeep:

Use event-tracking-skill to do an upkeep review for this existing run:
./output/example_com
Tell me what is still healthy, what drifted, and what needs repair.

Update an existing artifact:

Use event-tracking-skill to resume this artifact directory:
./output/example_com
Tell me the current checkpoint and continue only through schema review.

Page-group review only:

Use event-tracking-skill to review and refine the page groups in:
./output/example_com/site-analysis.json
Focus on business intent, not just URL shape.

Shopify branch:

Use event-tracking-skill for this Shopify storefront:
https://store.example.com
I want the Shopify-specific tracking path, not the generic website flow.

How To Think About It

This skill is best when you want the agent to act like a tracking lead, not just a command runner.

A typical conversation flow is:

1. inspect the site or resume an existing run
2. group pages in a reviewable way
3. draft or revise the event plan
4. review what should be reused, repaired, added, or dropped
5. continue into GTM generation and verification only when you explicitly want that

Where To Go Next

• Installation details: docs/README.install.md
• Skill family map: docs/skills.md
• Agent-facing workflow contract: SKILL.md
• CLI and maintainer workflow: DEVELOPING.md

Product Boundary

• the workflow runs locally
• browser-backed steps rely on Playwright Chromium; npm install triggers the package postinstall step that installs the browser binary
• GTM sync uses Google OAuth
• OAuth credentials are cached in the artifact directory for the current site run
• generic sites use automated preview verification
• Shopify uses the Shopify-specific branch and manual post-install validation
• optional anonymous telemetry is opt-in, stores consent in local user config, and can be disabled with DO_NOT_TRACK=1 or EVENT_TRACKING_TELEMETRY=0
• installed copy bundles can self-check GitHub for updates and reinstall the same selected bundle set

Need A More Advanced Setup?

This skill reflects the implementation workflow behind JTracking.

If you need a more advanced setup, JTracking also supports:

• richer tracking design based on business scenarios
• server-side tracking and custom loaders
• more destination and ad-platform integrations
• longer-term tracking operations and maintenance

License

This project is licensed under the Apache License, Version 2.0. See LICENSE for the full text.

Use of the JTracking name, logo, and other brand assets is not granted under this license.