Skip to content
Back to search

analytics-tracking-automation

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jtrackingai--analytics-tracking-automation/badge.svg)](/listings/jtrackingai--analytics-tracking-automation)

HTML

<a href="/listings/jtrackingai--analytics-tracking-automation"><img src="/api/listings/jtrackingai--analytics-tracking-automation/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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/analytics-tracking-automation.git
cd analytics-tracking-automation
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/analytics-tracking-automation

For advanced install options and exported skill bundles:

- [docs/README.install.md](docs/README.install.md) - [docs/skills.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/analytics-tracking-automation`.

That public bundle is a publish-safe skill bundle. It keeps the agent-facing skill docs and references while stripping bundled executable runtime files (CLI bootstrap, packaged node modules, telemetry transport, and updater runtime) that tend to trigger stricter marketplace security scans.

When users install/use this public ClawHub bundle, they must run this prerequisite first (before any `event-tracking` command):

npx skills add jtrackingai/analytics-tracking-automation

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 155 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: analytics-tracking-automation
  3. description: Use when you need GA4 + GTM tracking delivery from site discovery through publish, or when the right phase entry point is still unclear.
  4. compatibility: >
  5. Requires Node.js 18+, npm, and Playwright Chromium for browser-backed steps.
  6. analyze, validate-schema --check-selectors, preview, and sync each launch a
  7. real Chromium and/or call Google's GTM API, so they need outbound HTTP, local
  8. browser execution, and (for sync) a local loopback callback on 127.0.0.1 to
  9. receive Google's OAuth consent redirect. Run them in an environment that
  10. provides those capabilities. sync uses Google's interactive OAuth consent
  11. screen; the resulting user-owned refresh token is stored under the artifact
  12. directory and read locally by sync, preview, and publish when they call the
  13. official GTM API. A minimal anonymous startup signal is sent when the CLI
  14. command begins so operators can measure active usage. Richer anonymous
  15. diagnostics remain opt-in, are used only to improve the skill experience and
  16. workflow quality, and are not used for sensitive actions or sensitive
  17. behavior tracking.
  18. ---
  19. # Analytics Tracking Automation
  20. Use this skill as the end-to-end coordinator for GA4 + GTM tracking delivery.
  21. Use it when:
  22. - the user needs a full GA4 + GTM implementation flow, from analysis to go-live readiness
  23. - the request spans multiple workflow phases (discovery, schema, sync, verification, publish)
  24. - the correct entry point is still unclear and you need this skill to route to the right phase
  25. Do not assume the user wants the full workflow.
  26. <!-- analytics-tracking-automation auto-update bootstrap:start -->
  27. ## Auto-Update
  28. This installed root skill can self-check for newer GitHub versions before you continue.
  29. Before doing any task in this bundle:
  30. 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/analytics-tracking-automation` or an equivalent runtime-managed path.
  31. 2. Run `node "<bundle-dir>/runtime/skill-runtime/update-check.mjs" --json`.
  32. 3. If the result status is `update_available`, immediately run `node "<bundle-dir>/runtime/skill-runtime/self-update.mjs" --apply`.
  33. 4. If the update succeeds, read `<bundle-dir>/SKILL.md` again before continuing so you are using the refreshed instructions.
  34. 5. If the result status is `disabled`, treat this bundle as a local development link or repo checkout and continue without updating.
  35. <!-- analytics-tracking-automation auto-update bootstrap:end -->
  36. ## Skill Family
  37. The skill family is split into one umbrella skill plus seven phase skills:
  38. - `tracking-discover` for crawl coverage, platform detection, and fresh artifact bootstrap
  39. - `tracking-group` for page-group authoring and approval
  40. - `tracking-live-gtm` for auditing the real live GTM runtime before schema generation
  41. - `tracking-schema` for schema preparation, review, validation, and approval
  42. - `tracking-sync` for GTM config generation and sync
  43. - `tracking-verify` for preview QA and optional publish handoff
  44. - `tracking-shopify` for Shopify-specific schema, sync, install, and verification rules
  45. If the request is already bounded to one phase and that phase skill is available, route there instead of inlining the full runbook here.
  46. Once `site-analysis.json` indicates Shopify, keep discovery and grouping shared, then let `tracking-shopify` own the Shopify-specific branch.
  47. ## Shared Contract
  48. - Use the repo-local wrapper `./event-tracking` in this repository. If `dist/cli.js` is missing, run `npm run build` first.
  49. - For public/ClawHub installs, you must run this first before any `event-tracking` command: `npx skills add jtrackingai/analytics-tracking-automation`.
  50. - Keep one artifact directory per site at `<output-root>/<url-slug>`.
  51. - If the user already provides an artifact directory or one of its files, resume from the earliest unmet prerequisite instead of restarting from `analyze`.
  52. - Use `./event-tracking status <artifact-dir-or-file>` whenever the current checkpoint or next step is unclear.
  53. - Use `./event-tracking runs <output-root>` when the artifact directory is unknown but the output root is known.
  54. - Prefer high-level entry commands for user-facing flows: `run-new-setup`, `run-tracking-update`, `run-upkeep`, `run-health-audit`.
  55. - Telemetry consent is a required user-choice checkpoint for richer diagnostics. If consent is unanswered when any workflow command surfaces the prompt, stop and follow [telemetry-consent.md](references/telemetry-consent.md) as the single-source interaction contract. Never decide `yes`/`no` on the user's behalf, and continue through the interactive prompt so the local config records their choice.
  56. - Explain the purpose, what `yes` does, what `no` does, and the remaining privacy tradeoff before asking the user to reply `yes` or `no`. Do not ask a bare `yes`/`no` question with no context.
  57. - Treat workflow mode metadata as an internal workflow-state layer, not a user-facing command surface.
  58. - `analyze`, `validate-schema --check-selectors`, `preview`, and `sync` each need outbound HTTP and a real Chromium; `sync` additionally needs a local loopback callback on `127.0.0.1` for Google's OAuth consent redirect. Run them in an environment that permits those capabilities so Playwright and the OAuth callback can complete.
  59. - Run prompt-driven GTM sync with an interactive TTY from the start unless exact `--account-id`, `--container-id`, and `--workspace-id` values are already confirmed.
  60. - Never auto-select a GTM account, container, or workspace on the user's behalf.
  61. - Do not continue past the phase boundary the user asked for.
  62. ## Conversation Intake
  63. 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.
  64. Classify the request into one of these entry intents:
  65. - `resume_existing_run`: the user already has an artifact directory or one of its files; inspect the artifacts and use `status`
  66. - `new_setup`: net-new tracking implementation from scratch; prefer `run-new-setup`, then follow its recommended next step
  67. - `tracking_update`: revise or extend an existing implementation; prefer `run-tracking-update`
  68. - `upkeep`: routine maintenance, review, or incremental QA on an existing setup; prefer `run-upkeep`
  69. - `tracking_health_audit`: audit-only assessment of current live tracking; prefer `run-health-audit`
  70. - `analysis_only`: crawl/bootstrap/discovery only without committing to the full workflow yet; route to `tracking-discover` and stop after `analyze`
  71. Rules:
  72. - Do not ask the user to choose between internal workflow metadata flags and `analyze`.
  73. - 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".
  74. - If the user gives a fresh URL and asks to set up tracking, default to `new_setup`.
  75. - 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`.
  76. - If the user gives an artifact directory or workflow file, default to `resume_existing_run` instead of restarting from `analyze`.
  77. ## Routing Rules
  78. Route by user intent and current artifacts:
  79. - fresh URL, crawl request, or no artifacts yet: start with `tracking-discover`
  80. - `site-analysis.json` with missing or unconfirmed `pageGroups`: route to `tracking-group`
  81. - confirmed `site-analysis.json` with detected live GTM container IDs but no live baseline review yet: route to `tracking-live-gtm`
  82. - confirmed `site-analysis.json` or an in-progress `event-schema.json`: route to `tracking-schema`
  83. - approved `event-schema.json` without `gtm-config.json`: route to `tracking-sync` for `generate-gtm`
  84. - `gtm-config.json`: route to `tracking-sync`
  85. - `gtm-context.json`: route to `tracking-verify`, with publish treated as a separate explicit action
  86. - Shopify platform confirmation: keep shared early stages, then hand off to `tracking-shopify`
  87. If only the root skill is available, follow the same routing logic directly and stop at the matching phase boundary.
  88. ## Stop Rules
  89. - Do not bypass page-group approval before `prepare-schema`.
  90. - For key decision checkpoints, always require explicit user confirmation before continuing:
  91. - `pageGroups` (before `confirm-page-groups` and before `prepare-schema`)
  92. - `event-schema.json` (before `confirm-schema` and before `generate-gtm`)
  93. - GTM target selection (account/container/workspace during `sync`)
  94. - publish decision (before `publish`)
  95. - If confirmation is missing or ambiguous, stop and ask; do not auto-proceed.
  96. - Treat telemetry consent the same way as other explicit approval gates: if the user has not chosen `yes` or `no`, stop and ask instead of making the decision for them.
  97. - A broad request such as "full workflow", "全流程", "end-to-end", or "continue all the way" is scope authorization only. It does not count as checkpoint approval.
  98. - Never record checkpoint approval on the user's behalf with `confirm-page-groups --yes` or `confirm-schema --yes` unless the user explicitly confirms that checkpoint in the current turn.
  99. - When live GTM containers are detected on the site, do not bypass the live baseline review before schema generation.
  100. - Do not bypass schema approval before `generate-gtm` unless the user explicitly wants `--force`.
  101. - Treat preview QA and publish as separate decisions.
  102. - 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`.
  103. - Treat Shopify manual verification as the expected path for Shopify runs, not as a fallback error case.
  104. - Treat `tracking_health_audit` as an audit-only workflow mode. Do not run GTM deployment actions (`generate-gtm`, `sync`, `publish`) unless the user explicitly asks to override.
  105. ## Resume And Closeout
  106. When resuming:
  107. - prefer `workflow-state.json` when present
  108. - still inspect the real artifact set if warnings indicate stale gates
  109. - use `status` when the next step is unclear
  110. When a phase or the full workflow ends, keep the closeout answer-first:
  111. - lead with a compact, decision-ready summary in plain language
  112. - do not dump raw JSON, raw URL lists, or artifact inventory before the summary
  113. - list files, checkpoint, and next command only after the human-readable summary
  114. ## References
  115. - [skill-map.md](references/skill-map.md) for the umbrella / phase skill map
  116. - [architecture.md](references/architecture.md) for lifecycle, checkpoints, and resume semantics
  117. - [output-contract.md](references/output-contract.md) for artifact files and gate semantics
  118. - [shopify-workflow.md](references/shopify-workflow.md) for Shopify-specific branch expectations
  119. - [telemetry-consent.md](references/telemetry-consent.md) for the telemetry consent gate wording and behavior contract
README.md · README · 228 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="docs/assets/jtracking-social-preview.png" width="100%" />
  3. </p>
  4. <p align="center">
  5. <b>GA4 + GTM, done by AI. From site analysis to go live.</b><br/>
  6. Works with Cursor · Codex · Any AI Agent
  7. </p>
  8. <p align="center">
  9. <a href="#what-you-get">What You Get</a> ·
  10. <a href="#installation">Installation</a> ·
  11. <a href="#quick-start">Quick Start</a> ·
  12. <a href="#quick-debug-tips">Quick Debug Tips</a> ·
  13. <a href="https://www.jtracking.ai/skills">Website</a>
  14. </p>
  15. # Analytics Tracking Automation
  16. `analytics-tracking-automation` is a local-first AI skill for planning, reviewing, and delivering GA4 + GTM tracking.
  17. Use it when you want an agent to help with:
  18. - analyzing a site before tracking work starts
  19. - grouping pages by business purpose
  20. - designing or reviewing a GA4 event plan
  21. - comparing a proposed plan with an existing live GTM setup
  22. - preparing GTM-ready outputs and verification guidance
  23. - handling both generic websites and Shopify storefronts
  24. This README is intentionally user-facing and conversation-first.
  25. If you need the CLI surface or maintainer workflow, use [DEVELOPING.md](DEVELOPING.md).
  26. ## What You Get
  27. For a given website, this skill can help produce:
  28. - a reviewable site analysis
  29. - business-friendly page groups
  30. - a compact, decision-ready tracking plan
  31. - GTM-ready tracking outputs
  32. - verification and health summaries before go-live
  33. - artifact-backed progress that can be resumed later
  34. ## Installation
  35. Most users only need the umbrella skill.
  36. ### Recommended
  37. Clone the repository locally, then install the skill into your agent skills directory:
  38. ```bash
  39. git clone https://github.com/jtrackingai/analytics-tracking-automation.git
  40. cd analytics-tracking-automation
  41. npm run install:skills
  42. ```
  43. ### No-Clone Alternative
  44. If you do not want to clone the repository, install the root skill directly:
  45. ```bash
  46. npx skills add jtrackingai/analytics-tracking-automation
  47. ```
  48. For advanced install options and exported skill bundles:
  49. - [docs/README.install.md](docs/README.install.md)
  50. - [docs/skills.md](docs/skills.md)
  51. ### ClawHub Publish
  52. If you are publishing this skill to ClawHub, publish the exported public bundle instead of the full repository:
  53. ```bash
  54. npm run export:skills:clawhub
  55. ```
  56. Then upload `dist/clawhub-skill-bundles/analytics-tracking-automation`.
  57. That public bundle is a publish-safe skill bundle. It keeps the agent-facing skill docs and references while stripping bundled executable runtime files (CLI bootstrap, packaged node modules, telemetry transport, and updater runtime) that tend to trigger stricter marketplace security scans.
  58. When users install/use this public ClawHub bundle, they must run this prerequisite first (before any `event-tracking` command):
  59. ```bash
  60. npx skills add jtrackingai/analytics-tracking-automation
  61. ```
  62. ## Quick Start
  63. ### Use It As A Skill
  64. The intended experience is simple: tell your agent what you want in plain language.
  65. Good requests usually include one or more of:
  66. - the site URL
  67. - whether this is a new setup, update, upkeep, or audit
  68. - the output root for a new site run, such as `./output` or `/tmp/output`
  69. - an existing site artifact directory if you already have one, such as `./output/example_com`
  70. - GA4 measurement ID or GTM context when you already know them
  71. - any scope boundary such as "stop after schema review"
  72. 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`.
  73. ### Example Prompts
  74. New setup from scratch:
  75. ```text
  76. Use analytics-tracking-automation to plan GA4 + GTM tracking for https://www.example.com.
  77. Use ./output as the output root; create the site artifact directory under it.
  78. Start from a fresh run and stop after the event schema is ready for review.
  79. ```
  80. New setup with implementation context:
  81. ```text
  82. Use analytics-tracking-automation to set up tracking for https://www.example.com.
  83. Use /tmp/output as the output root, so this site's artifacts go under /tmp/output/www_example_com.
  84. GA4 Measurement ID is G-XXXXXXXXXX.
  85. We care most about signup, pricing, contact, and demo intent.
  86. ```
  87. Audit only:
  88. ```text
  89. Use analytics-tracking-automation to run a tracking health audit for https://www.example.com.
  90. I only want to understand the current live GTM setup and whether we should repair or rebuild.
  91. Do not continue into deployment work.
  92. ```
  93. Routine upkeep:
  94. ```text
  95. Use analytics-tracking-automation to do an upkeep review for this existing run:
  96. ./output/example_com
  97. Tell me what is still healthy, what drifted, and what needs repair.
  98. ```
  99. Update an existing artifact:
  100. ```text
  101. Use analytics-tracking-automation to resume this artifact directory:
  102. ./output/example_com
  103. Tell me the current checkpoint and continue only through schema review.
  104. ```
  105. Page-group review only:
  106. ```text
  107. Use analytics-tracking-automation to review and refine the page groups in:
  108. ./output/example_com/site-analysis.json
  109. Focus on business intent, not just URL shape.
  110. ```
  111. Shopify branch:
  112. ```text
  113. Use analytics-tracking-automation for this Shopify storefront:
  114. https://store.example.com
  115. I want the Shopify-specific tracking path, not the generic website flow.
  116. ```
  117. ## How To Think About It
  118. This skill is best when you want the agent to act like a tracking lead, not just a command runner.
  119. A typical conversation flow is:
  120. 1. inspect the site or resume an existing run
  121. 2. group pages in a reviewable way
  122. 3. draft or revise the event plan
  123. 4. review what should be reused, repaired, added, or dropped
  124. 5. continue into GTM generation and verification only when you explicitly want that
  125. ## Where To Go Next
  126. - Installation details: [docs/README.install.md](docs/README.install.md)
  127. - Skill family map: [docs/skills.md](docs/skills.md)
  128. - Agent-facing workflow contract: [SKILL.md](SKILL.md)
  129. - CLI and maintainer workflow: [DEVELOPING.md](DEVELOPING.md)
  130. ## Quick Debug Tips
  131. If preview troubleshooting points to selector mismatch or page-load/navigation issues, these Playwright CLI helpers are faster than repeatedly re-running the full flow:
  132. ```bash
  133. npm run debug:open -- https://www.example.com
  134. npm run debug:codegen -- https://www.example.com
  135. ```
  136. - `debug:open`: headed browser for quick visual checks (redirect loops, WAF pages, blocked content).
  137. - `debug:codegen`: interactive selector capture for fixing `event-schema.json` selectors.
  138. ## Product Boundary
  139. - the workflow runs locally
  140. - browser-backed steps rely on Playwright Chromium; `npm install` triggers the package `postinstall` step that installs the browser binary
  141. - GTM sync uses Google OAuth
  142. - OAuth credentials are cached in the artifact directory for the current site run
  143. - generic sites use automated preview verification
  144. - Shopify uses the Shopify-specific branch and manual post-install validation
  145. - a minimal anonymous startup signal is sent when an `event-tracking` command begins so operators can measure active usage; it is session-scoped and limited to technical metadata such as command name, CLI version, OS family, Node major version, and a per-invocation session identifier
  146. - richer anonymous usage diagnostics remain opt-in and the first explicit choice is stored in local user config; if enabled, future runs send higher-level workflow data such as command name, success/failure status, rough counts, site hostname, detected platform, and broad workflow checkpoints so operators can improve the product and troubleshoot reliability; if declined, future runs continue normally without these richer diagnostics until the user changes that local config choice; those richer diagnostics do not send full URLs, page paths, query strings, file paths, GTM/GA IDs, selectors, OAuth data, raw errors, or page content; the remaining privacy risk is that the site hostname and workflow metadata still reveal which domain was worked on and broad usage patterns; if a workflow prompt asks for telemetry consent and no stored preference exists, the operator must stop and let the user choose `yes` or `no` instead of answering on the user's behalf
  147. - installed copy bundles can self-check GitHub for updates and reinstall the same selected bundle set
  148. ## Need A More Advanced Setup?
  149. This skill reflects the implementation workflow behind [JTracking](https://www.jtracking.ai).
  150. If you need a more advanced setup, JTracking also supports:
  151. - richer tracking design based on concrete business flows
  152. - server-side tracking and custom loaders
  153. - more destination and ad-platform integrations
  154. - longer-term tracking operations and maintenance
  155. ## Contact Us
  156. If you run into any issues while using this skill, contact us at [support@jtracking.ai](mailto:support@jtracking.ai).
  157. We will reply as soon as we see your message.
  158. ## License
  159. This project is licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for the full text.
  160. Use of the JTracking name, logo, and other brand assets is not granted under this license.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.