refactor(gtm-audit): Update desktop skill to use Chrome DevTools + DTM Agent MCP workflow

- 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 <noreply@anthropic.com>
2026-01-03 01:56:47 +09:00
parent b859d0a266
commit 12ae63e0a7
2 changed files with 209 additions and 150 deletions
--- 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/
--- 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