Event Tracking Skill

event-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:

1. analyze a site
2. group pages by business intent
3. prepare schema context
4. review the event schema
5. generate GTM config
6. sync to a GTM workspace
7. verify in Preview Mode or the Shopify manual flow
8. publish with more confidence

What You Get

For a given website, this skill can help you:

• analyze page structure, shared UI, platform signals, and existing dataLayer usage
• organize pages into business-purpose groups before defining events
• generate a reviewable GA4 event schema and stakeholder-friendly event spec
• turn the approved schema into GTM-ready tags, triggers, and variables
• sync to GTM, verify before publish, and keep the whole flow artifact-driven
• support both generic websites and Shopify storefronts with different verification paths

Installation

Recommended repo-local setup:

./setup

That installs dependencies, builds the CLI, and runs a basic environment check.

Install with skills.sh (Recommended)

Use this if you want to install the skill into your local agent skills directory and start using it right away.

npx skills add jtrackingai/event-tracking-skill

Manual Installation / Local Development

Use this if you want to inspect the source, run the CLI directly, or work on the skill locally.

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

npm ci also installs Playwright's Chromium browser, which is required by the crawl and preview steps.

After setup, use the checked-in wrapper from the repo root:

./event-tracking --help

If the package is installed or linked as a binary, the public command name is event-tracking.

dist/cli.js is an internal implementation path, not the documented command surface.

Documentation Map

• README.md for installation, quick start, and the public command surface
• ARCHITECTURE.md for artifact lifecycle, branch behavior, and system boundaries
• DEVELOPING.md for maintainer commands, edit rules, and release checks
• docs/README.codex.md for Codex-oriented install, update, and troubleshooting notes
• docs/skills.md for the umbrella skill and phase-skill map
• SKILL.md for the agent-facing workflow contract

Skill Family

The repository now has:

• one umbrella skill: event-tracking-skill
• six phase-oriented subskills under skills/

Use 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, 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.

Exported Skill Bundles

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.md
• agents/openai.yaml
• the references/ files that the skill may need, including exported architecture.md and skill-map.md where relevant

The exported bundles rewrite command examples to the public event-tracking command name. Inside this repository, keep using ./event-tracking.

Install Into Codex

To install the exported bundles into the default Codex skills directory, run:

npm run install:skills

For a development-friendly install that updates in place as dist/skill-bundles/ changes, use link mode:

npm run install:skills -- --mode link

Default target resolution:

• $CODEX_HOME/skills when CODEX_HOME is set
• otherwise ~/.codex/skills

Useful variants:

npm run install:skills -- --target-dir /tmp/codex-skills
npm run install:skills -- --mode link --target-dir ~/.codex/skills
npm run install:skills -- --skill event-tracking-skill --skill tracking-schema
./setup --install-skills
./setup --install-skills --mode link

The installer can either copy or link the exported bundles into the target directory, so rerun the export or install step after skill text or metadata changes.

Use docs/README.codex.md for a Codex-specific install/update workflow, including the new link mode and optional .codex/INSTALL.md bootstrap path.

Quick Start

Use It As A Skill

If 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, schema review, GTM generation, sync, preview, and publish.

Use It As A CLI

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 pageGroups in ./output/example_com/site-analysis.json, continue with the same artifact directory:

./event-tracking confirm-page-groups ./output/example_com/site-analysis.json
./event-tracking prepare-schema ./output/example_com/site-analysis.json
./event-tracking validate-schema ./output/example_com/event-schema.json --check-selectors
./event-tracking generate-spec ./output/example_com/event-schema.json
./event-tracking confirm-schema ./output/example_com/event-schema.json
./event-tracking generate-gtm ./output/example_com/event-schema.json --measurement-id G-XXXXXXXXXX
./event-tracking sync ./output/example_com/gtm-config.json
./event-tracking preview ./output/example_com/event-schema.json --context-file ./output/example_com/gtm-context.json
./event-tracking publish --context-file ./output/example_com/gtm-context.json --version-name "GA4 Events v1"

Important workflow note:

• prepare-schema requires pageGroups to already be filled in site-analysis.json and explicitly confirmed
• after grouping pages, run ./event-tracking confirm-page-groups <artifact-dir>/site-analysis.json
• for generic sites, event-schema.json is authored after prepare-schema from schema-context.json
• for Shopify sites, prepare-schema bootstraps event-schema.json automatically if it does not already exist

The full workflow used by the skill is documented in SKILL.md.

Common Entry Points

You do not need to run the full flow every time.

| Intent | Start From | Minimum Inputs | Typical Command(s) | | --- | --- | --- | --- | | Inspect current progress | Any artifact directory or file inside it | artifact directory or file path | ./event-tracking status <artifact-dir> | | Analyze a new site | Step 1 | URL, output root | ./event-tracking analyze <url> --output-root <dir> | | Review or approve page groups | Step 2 | site-analysis.json | update pageGroups, then ./event-tracking confirm-page-groups <artifact-dir>/site-analysis.json | | Author or review schema | Step 3 | confirmed site-analysis.json | prepare-schema, edit event-schema.json, validate-schema, generate-spec, confirm-schema | | Generate GTM config from an approved schema | Step 4 | event-schema.json, measurement ID | ./event-tracking generate-gtm <artifact-dir>/event-schema.json --measurement-id <id> | | Sync an approved GTM config | Step 5 | gtm-config.json | ./event-tracking sync <artifact-dir>/gtm-config.json | | QA an existing GTM workspace | Step 6 | event-schema.json, gtm-context.json | ./event-tracking preview <artifact-dir>/event-schema.json --context-file <artifact-dir>/gtm-context.json | | Publish an already-verified workspace | Step 7 | gtm-context.json | ./event-tracking publish --context-file <artifact-dir>/gtm-context.json --version-name "GA4 Events v1" |

If a user already has an artifact directory, resume from the earliest unmet prerequisite instead of restarting from analyze.

Required Inputs

Before running the full workflow, prepare:

• target website URL
• output root directory for generated artifacts
• GA4 Measurement ID
• optional Google tag ID

The artifact directory is required for every downstream step and is derived as <output-root>/<url-slug>.

Workflow

The current workflow mixes agent-led review steps with CLI execution steps.

| Step | Owner | What It Does | Command / Output | | --- | --- | --- | --- | | Analyze | CLI | Crawls the site and captures pages, shared UI, warnings, detected events, and platform signals | ./event-tracking analyze <url> --output-root <output-root> -> site-analysis.json | | Page Grouping | Agent or user | Fills pageGroups in site-analysis.json by business purpose before schema preparation | updated site-analysis.json | | Page Group Confirmation | User + CLI | Reviews the current page groups and records explicit approval for the current pageGroups snapshot | ./event-tracking confirm-page-groups <artifact-dir>/site-analysis.json -> updated site-analysis.json | | Prepare Schema Context | CLI | Compresses grouped analysis for schema authoring and bootstraps Shopify artifacts when needed | ./event-tracking prepare-schema <artifact-dir>/site-analysis.json -> schema-context.json, Shopify bootstrap files | | Schema Authoring And Review | Agent or user + CLI validation | Creates or refines event-schema.json, validates selectors, generates a readable spec, and records schema approval | validate-schema, generate-spec, `confir