From 12ae63e0a712964405d76b8f1f339950bfd73b3f Mon Sep 17 00:00:00 2001 From: Andrew Yim Date: Sat, 3 Jan 2026 01:56:47 +0900 Subject: [PATCH] refactor(gtm-audit): Update desktop skill to use Chrome DevTools + DTM Agent MCP workflow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Replace Playwright-based approach with Chrome DevTools MCP for browser inspection - Add DTM Agent MCP integration for GTM API operations - Document 4-phase workflow: Inspect → Diagnose → Configure → Verify - Add common issue patterns with diagnosis/fix guidance - Update audit checklist to reference specific MCP tools - Add .gitignore entries for pickle files and .claude/ directory 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- .gitignore | 5 + custom-skills/20-gtm-audit/desktop/SKILL.md | 354 +++++++++++--------- 2 files changed, 209 insertions(+), 150 deletions(-) diff --git a/.gitignore b/.gitignore index 0bd6715..03059c2 100644 --- a/.gitignore +++ b/.gitignore @@ -76,8 +76,13 @@ npm-debug.log* .env.local *.key *.pem +*.pickle credentials.json secrets.json +token.json + +# Claude Code local config +.claude/ # Temporary files output/ diff --git a/custom-skills/20-gtm-audit/desktop/SKILL.md b/custom-skills/20-gtm-audit/desktop/SKILL.md index 53088c2..25c58dc 100644 --- a/custom-skills/20-gtm-audit/desktop/SKILL.md +++ b/custom-skills/20-gtm-audit/desktop/SKILL.md @@ -5,201 +5,255 @@ description: Automated Google Tag Manager audit and validation toolkit. Use when # GTM Audit Skill -Automated audit workflow for GTM containers using Playwright browser automation. +Automated audit workflow for GTM containers using **Chrome DevTools MCP** for browser inspection and **DTM Agent MCP** for GTM API operations. -## Workflow Overview +## Required MCP Servers + +This skill requires the following MCP servers to be configured: + +| MCP Server | Purpose | Tools Used | +|------------|---------|------------| +| **chrome-devtools** | Browser debugging & inspection | `navigate_page`, `evaluate_script`, `list_network_requests`, `list_console_messages`, `click`, `hover`, `take_screenshot`, `performance_start_trace` | +| **dtm-agent** | GTM API operations | `dtm_status`, `dtm_list_tags`, `dtm_get_tag`, `dtm_list_triggers`, `dtm_get_trigger`, `dtm_list_variables`, `dtm_debug_performance`, `dtm_debug_preview` | + +## Critical Workflow Rule + +**ALWAYS use Chrome DevTools MCP FIRST before making GTM configuration changes.** + +GTM triggering and parameter capturing issues are highly dependent on: +- DOM structure and CSS selectors +- Dynamic element loading and timing +- DataLayer event sequences +- JavaScript execution order +- Network request timing + +## Standard Debugging Workflow ``` -1. Setup & Container Detection -2. DataLayer Validation & Monitoring -3. Form Analysis & Submission Tracking -4. E-commerce Checkout Flow Testing -5. Tag Firing Verification -6. Issue Analysis & Recommendations -7. Report Generation +┌─────────────────────────────────────────────────────────────────┐ +│ PHASE 1: INSPECT (Chrome DevTools MCP) │ +├─────────────────────────────────────────────────────────────────┤ +│ 1. navigate_page → Load target URL │ +│ 2. evaluate_script → Check window.dataLayer state │ +│ 3. list_network_requests → Identify GTM/tag requests │ +│ 4. list_console_messages → Check for JS errors │ +│ 5. click/hover → Simulate user interactions │ +│ 6. take_screenshot → Document current state │ +└─────────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────────┐ +│ PHASE 2: DIAGNOSE │ +├─────────────────────────────────────────────────────────────────┤ +│ • Identify DOM/timing/selector issues from browser state │ +│ • Compare expected vs actual dataLayer events │ +│ • Check network request payloads for missing parameters │ +│ • Review console for GTM/tag errors │ +└─────────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────────┐ +│ PHASE 3: CONFIGURE (DTM Agent MCP) │ +├─────────────────────────────────────────────────────────────────┤ +│ 1. dtm_status → Verify authentication │ +│ 2. dtm_list_tags → Review current tag configuration │ +│ 3. dtm_get_trigger → Inspect trigger conditions │ +│ 4. dtm_list_variables → Check variable mappings │ +│ 5. dtm_update_tag/trigger → Make configuration changes │ +│ 6. dtm_create_version → Create version for testing │ +└─────────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────────┐ +│ PHASE 4: VERIFY (Chrome DevTools MCP) │ +├─────────────────────────────────────────────────────────────────┤ +│ • Repeat Phase 1 inspection steps │ +│ • Confirm issue is resolved │ +│ • Document before/after comparison │ +└─────────────────────────────────────────────────────────────────┘ ``` -## Quick Start +## Chrome DevTools MCP Commands -```bash -# Full audit with all features -python scripts/gtm_audit.py --url "https://example.com" --journey full +### Essential Inspection Commands -# Form tracking audit -python scripts/gtm_audit.py --url "https://example.com/contact" --journey form +```javascript +// 1. Check dataLayer state +evaluate_script: "JSON.stringify(window.dataLayer || [], null, 2)" -# E-commerce checkout flow -python scripts/gtm_audit.py --url "https://example.com/cart" --journey checkout +// 2. Get GTM container info +evaluate_script: "Object.keys(window.google_tag_manager || {})" -# DataLayer deep inspection -python scripts/gtm_audit.py --url "https://example.com" --journey datalayer +// 3. Monitor dataLayer pushes (inject listener) +evaluate_script: ` + window.__gtmPushLog = []; + const originalPush = window.dataLayer.push; + window.dataLayer.push = function(...args) { + window.__gtmPushLog.push({timestamp: Date.now(), data: args[0]}); + return originalPush.apply(this, args); + }; +` -# With expected container validation -python scripts/gtm_audit.py --url "https://example.com" --container "GTM-XXXXXX" +// 4. Get captured pushes +evaluate_script: "JSON.stringify(window.__gtmPushLog || [], null, 2)" + +// 5. Check for GTM debug mode +evaluate_script: "window.google_tag_manager?.['GTM-XXXXXX']?.preview?.active" ``` -## Core Components +### Network Request Patterns -### 1. Container Detection - -Verify GTM installation: -- Check for `gtm.js` or `gtag/js` script presence -- Validate container ID format (GTM-XXXXXX) -- Detect multiple containers (potential conflicts) -- Check script placement (head vs body) - -### 2. DataLayer Inspection - -Monitor `window.dataLayer` array: -- Capture all push events -- Validate event structure against GA4 specs -- Check e-commerce object schemas -- Identify malformed or missing parameters - -### 3. Form Analysis & Tracking - -Comprehensive form validation: -- **Discovery**: Find all forms on page -- **Field Analysis**: Input types, required fields, validation rules -- **Interaction Simulation**: Focus, input, blur, submit -- **Event Verification**: form_start, form_submit, generate_lead -- **Error Tracking**: Validation failures, abandonment points - -### 4. E-commerce Checkout Flow - -Multi-step checkout simulation: -- **Cart**: view_cart, remove_from_cart -- **Checkout Start**: begin_checkout -- **Shipping**: add_shipping_info -- **Payment**: add_payment_info -- **Purchase**: purchase event validation -- **Funnel Analysis**: Drop-off detection between steps - -### 5. DataLayer Deep Inspection - -Advanced dataLayer validation: -- **Structure Validation**: Schema compliance checking -- **Real-time Monitoring**: Capture all pushes during journey -- **Event Sequencing**: Verify correct order of events -- **Parameter Validation**: Type checking, required fields -- **Diff Analysis**: Before/after state comparison - -### 4. Network Monitoring - -Capture outbound requests to: -| Destination | Endpoint Pattern | -|-------------|------------------| +| Tag Type | URL Pattern to Monitor | +|----------|------------------------| | GA4 | `google-analytics.com/g/collect` | +| Google Ads | `googleads.g.doubleclick.net` | | Meta Pixel | `facebook.com/tr` | | LinkedIn | `px.ads.linkedin.com` | -| Google Ads | `googleads.g.doubleclick.net` | | TikTok | `analytics.tiktok.com` | +| Kakao | `track.tiara.kakao.com` | +| Naver | `wcs.naver.net` | -### 5. Tag Verification +## DTM Agent MCP Commands -For each expected tag: -- Confirm firing on correct trigger -- Validate required parameters present -- Check parameter values match dataLayer -- Identify timing/sequencing issues +### Container Analysis -## Reference Files +```bash +# Check authentication and active container +dtm_status -- **references/ga4_events.md** - GA4 recommended event specifications -- **references/ecommerce_schema.md** - E-commerce dataLayer structures -- **references/form_tracking.md** - Form event specs and validation patterns -- **references/checkout_flow.md** - Checkout funnel event sequence -- **references/datalayer_validation.md** - DataLayer schema validation rules -- **references/common_issues.md** - Frequent problems and fixes -- **references/report_template.md** - Audit report format +# List all tags with optional filter +dtm_list_tags --name_filter "GA4" + +# Get specific tag details +dtm_get_tag --tag_id "123" + +# List triggers and their conditions +dtm_list_triggers + +# Container performance analysis +dtm_debug_performance + +# Validate container configuration +dtm_debug_preview +``` + +### Configuration Changes + +```bash +# Update tag configuration +dtm_update_tag --tag_id "123" --config {...} + +# Create new trigger +dtm_create_trigger --name "Button Click" --type "CLICK" + +# Create version for testing +dtm_create_version --name "Debug Session 2025-01-03" +``` ## Audit Checklist ### Container Health -- [ ] GTM script loads without errors -- [ ] Container ID matches expected -- [ ] No duplicate containers -- [ ] Script in correct position +- [ ] GTM script loads without errors (Chrome DevTools: console) +- [ ] Container ID matches expected (Chrome DevTools: evaluate_script) +- [ ] No duplicate containers (Chrome DevTools: network requests) +- [ ] Script in correct position (Chrome DevTools: DOM inspection) ### DataLayer Quality -- [ ] dataLayer initialized before GTM -- [ ] Event names follow conventions -- [ ] Required parameters present -- [ ] Data types correct (string/number) +- [ ] dataLayer initialized before GTM (Chrome DevTools: evaluate_script) +- [ ] Event names follow conventions (Chrome DevTools: dataLayer inspection) +- [ ] Required parameters present (DTM Agent: dtm_get_tag to check expected params) +- [ ] Data types correct (Chrome DevTools: typeof checks) - [ ] E-commerce objects cleared before new push -- [ ] No duplicate events firing +- [ ] No duplicate events firing (Chrome DevTools: network request count) -### Form Tracking -- [ ] form_start fires on first interaction -- [ ] form_submit fires on successful submission -- [ ] generate_lead fires with value (if applicable) -- [ ] Form field errors tracked -- [ ] Form abandonment detectable +### Tag Configuration +- [ ] Tags properly configured (DTM Agent: dtm_list_tags) +- [ ] Triggers have correct conditions (DTM Agent: dtm_get_trigger) +- [ ] Variables mapped correctly (DTM Agent: dtm_list_variables) +- [ ] Firing sequence appropriate (DTM Agent: dtm_debug_performance) -### E-commerce Checkout -- [ ] view_cart fires with correct items -- [ ] begin_checkout has all required params -- [ ] add_shipping_info includes shipping_tier -- [ ] add_payment_info includes payment_type -- [ ] purchase has unique transaction_id -- [ ] purchase value matches cart total +### Tag Firing Verification +- [ ] Pageview fires on all pages (Chrome DevTools: network requests) +- [ ] Events fire on correct triggers (Chrome DevTools: click + network) +- [ ] E-commerce events have required params (Chrome DevTools: request payload) +- [ ] Conversion tags fire once (Chrome DevTools: request count) -### Tag Firing -- [ ] Pageview fires on all pages -- [ ] Events fire on correct triggers -- [ ] E-commerce events have required params -- [ ] Conversion tags fire once (not duplicate) +## Common Issue Patterns -### Performance -- [ ] Tags don't block page render -- [ ] No excessive network requests -- [ ] Tag sequencing optimized +### Issue: Tag Not Firing + +**Diagnosis (Chrome DevTools MCP first)**: +1. `navigate_page` → Load the page +2. `list_network_requests` → Check if ANY request to tag endpoint +3. `evaluate_script` → Verify dataLayer event exists +4. `list_console_messages` → Check for errors + +**Fix (DTM Agent MCP)**: +1. `dtm_get_trigger` → Review trigger conditions +2. `dtm_update_trigger` → Adjust selector/event name +3. `dtm_debug_preview` → Validate configuration + +### Issue: Missing Parameters + +**Diagnosis (Chrome DevTools MCP first)**: +1. `list_network_requests` → Capture the actual request +2. Parse request payload to see what's sent +3. `evaluate_script` → Check dataLayer for expected values + +**Fix (DTM Agent MCP)**: +1. `dtm_list_variables` → Check variable configuration +2. `dtm_update_tag` → Fix parameter mappings + +### Issue: Duplicate Firing + +**Diagnosis (Chrome DevTools MCP first)**: +1. `list_network_requests` → Count requests to same endpoint +2. `evaluate_script` → Check dataLayer for duplicate pushes + +**Fix (DTM Agent MCP)**: +1. `dtm_list_triggers` → Check for overlapping triggers +2. `dtm_get_tag` → Review tag firing options + +## Performance Analysis + +Use Chrome DevTools MCP for performance: +``` +performance_start_trace → Run page load → Analyze trace +``` + +Compare with DTM Agent static analysis: +``` +dtm_debug_performance → Get container complexity grade +``` ## Output Format -Audit generates JSON report: +Audit generates structured report: ```json { "audit_metadata": { "url": "https://example.com", - "timestamp": "2025-01-15T10:30:00Z", - "container_id": "GTM-XXXXXX" + "timestamp": "2025-01-03T10:30:00Z", + "container_id": "GTM-XXXXXX", + "tools_used": ["chrome-devtools", "dtm-agent"] }, - "container_status": { - "installed": true, - "valid": true, - "position": "head", - "issues": [] + "browser_inspection": { + "dataLayer_events": [...], + "network_requests": [...], + "console_errors": [...], + "performance_metrics": {...} + }, + "gtm_configuration": { + "tags": [...], + "triggers": [...], + "variables": [...], + "container_grade": "B" }, - "tags_fired": [...], - "tags_not_fired": [...], "issues": [...], "recommendations": [...] } ``` -## Common Fix Patterns +## Integration with Other Skills -**Tag Not Firing** -1. Check trigger conditions in GTM -2. Verify dataLayer event name matches exactly -3. Confirm trigger timing (DOM Ready vs Window Loaded) -4. Test in GTM Preview mode - -**Missing Parameters** -1. Verify dataLayer.push() includes all required fields -2. Check variable configuration in GTM -3. Confirm data types match expectations - -**Duplicate Firing** -1. Check for multiple triggers on same action -2. Verify tag firing options (once per event/page) -3. Look for duplicate GTM containers - -## Integration Notes - -Works with: -- Playwright MCP tools for browser automation -- Desktop Commander for local script execution -- Can export reports to Notion via MCP +- **seo-core-web-vitals**: Use performance traces for Core Web Vitals impact analysis +- **notion-writer**: Export audit reports to Notion database +- **seo-schema-validator**: Validate e-commerce structured data alongside GTM