our-claude-skills/custom-skills/61-gtm-editor/code/SKILL.md

---
name: gtm-editor
description: >
  GTM implementation toolkit. Creates, updates, and modifies GTM tags, triggers,
  variables via API. Generates Custom HTML with ES5 compliance. Handles workspace
  lifecycle, DOM analysis for trigger design, and dataLayer code generation.
  Triggers on "create GTM tag", "generate dataLayer", "modify trigger", "update variable",
  "inject tracking code", "write custom HTML", "manage GTM", "design tags",
  "create conversion tag", "set up tracking".
  NOT for auditing (use gtm-audit) or validation/QA (use gtm-validator).
---

# GTM Editor Skill

Create, modify, and deploy GTM configurations via API. Generates ES5-compliant Custom HTML tags.

## Available Tools

### GTM Container Management (DTM Agent MCP)
- `dtm_status` — Check auth and active account/container
- `dtm_set_account` / `dtm_set_container` — Switch context
- `dtm_list_tags` / `dtm_get_tag` / `dtm_create_tag` / `dtm_update_tag` / `dtm_delete_tag`
- `dtm_list_triggers` / `dtm_get_trigger` / `dtm_create_trigger` / `dtm_delete_trigger`
- `dtm_list_variables` / `dtm_get_variable` / `dtm_create_variable` / `dtm_delete_variable`
- `dtm_list_folders` / `dtm_list_workspaces` / `dtm_get_workspace_status`
- `dtm_list_versions` / `dtm_get_live_version` / `dtm_create_version`

### Browser Analysis (Chrome DevTools MCP)
- `navigate_page` — Load page for DOM analysis
- `evaluate_script` — Inspect forms, buttons, links, CSS selectors
- `take_snapshot` — Get page structure for trigger design
- `list_network_requests` — Verify tags fire after changes

### Reporting (Notion MCP)
- Write implementation plans and tag configurations to Notion

## Core Capabilities

### 1. Tag Creation via GTM API

Create tags directly in GTM — no manual pasting. The API handles workspace lifecycle automatically (auto-creates new workspace if current one is published).

**GA4 Event Tags:**
```
GA4 event tags use type "gaawe" with:
  - eventName: the GA4 event name (snake_case)
  - measurementIdOverride: {{GA4 Measurement ID variable}} (NOT measurementId)
  - eventParameters: list of name/value maps
```

**CRITICAL: measurementIdOverride, NOT measurementId**
GA4 event tags inherit from config — use `measurementIdOverride` to reference the measurement ID variable. The API rejects `measurementId`.

### 2. Trigger Design from DOM Analysis

Analyze page DOM to design precise triggers:

```javascript
// Extract forms
(function(){var forms=document.querySelectorAll('form');return JSON.stringify(Array.from(forms).map(function(f){return{id:f.id,action:f.action,fields:Array.from(f.querySelectorAll('input,textarea,select')).map(function(el){return{name:el.name,type:el.type,id:el.id}})}}));})()

// Extract CTAs and buttons
(function(){return JSON.stringify(Array.from(document.querySelectorAll('a[class*="btn"],button,[role="button"]')).map(function(el){return{text:(el.textContent||'').trim().substring(0,50),href:el.href||'',classes:el.className,id:el.id}}));})()
```

**Trigger types:**
| Type | Use For | Key Parameter |
|------|---------|---------------|
| `linkClick` | `<a>` elements | `autoEventFilter` with CSS selector |
| `click` | Any element | `filter` on Click ID/Classes |
| `formSubmission` | Form submit | `filter` on Form ID |
| `customEvent` | dataLayer events | `custom_event_filter` on `{{_event}}` |
| `scrollDepth` | Scroll tracking | `verticalThresholdsPercent` |
| `timer` | Time on page | `interval`, `limit` |
| `domReady` | DOM loaded | No filter needed |

### 3. Custom HTML Generation (ES5 MANDATORY)

GTM Custom HTML uses a JavaScript compiler that does NOT support ES2020+.

**FORBIDDEN:**
```javascript
// NO: optional chaining, arrow functions, const/let, template literals,
//     destructuring, spread, async/await
```

**REQUIRED:**
```javascript
// YES: var, function(){}, string concatenation, explicit property access
(function() {
  var form = document.getElementById('contact-form');
  if (!form) return;
  form.addEventListener('submit', function() {
    window.dataLayer = window.dataLayer || [];
    window.dataLayer.push({
      'event': 'generate_lead',
      'lead_type': form.querySelector('#requestType').value
    });
  });
})();
```

### 4. Workspace Lifecycle Management

GTM workspaces become **read-only after publishing**. The DTM Agent auto-handles this:
- If create/update fails with "Workspace is already submitted"
- Auto-creates a new workspace
- Retries the operation
- Caches the workspace ID for subsequent calls

**You don't need to manage workspaces manually.** Just call `dtm_create_tag` etc. and it works.

### 5. DataLayer Code Generation

Generate dataLayer push code for common tracking scenarios:

**E-commerce:**
```javascript
// purchase event
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({ ecommerce: null }); // Clear previous
window.dataLayer.push({
  'event': 'purchase',
  'ecommerce': {
    'transaction_id': /* order ID */,
    'currency': 'KRW',
    'value': /* total */,
    'items': [{ item_id: '', item_name: '', price: 0, quantity: 1 }]
  }
});
```

**Forms/Leads:**
```javascript
window.dataLayer.push({
  'event': 'generate_lead',
  'lead_type': /* form type */,
  'form_id': /* form element ID */
});
```

## Korean Market Patterns

| Context | Pattern |
|---------|---------|
| Currency | KRW (no decimals) |
| Payment buttons | 장바구니, 결제하기, 주문하기, 문의하기 |
| Payment methods | 카카오페이, 네이버페이, 토스, 신용카드 |
| Platforms | Kakao Pixel (`track.kakao.com`), Naver Analytics (`wcs.naver.net`) |

## Supported Tag Types

| GTM Type | Name | Platform |
|----------|------|----------|
| `googtag` | Google Tag | GA4 config |
| `gaawe` | GA4 Event | GA4 events |
| `gclidw` | Conversion Linker | Google Ads |
| `awct` | Ads Conversion | Google Ads |
| `html` | Custom HTML | Any (Meta, PostHog, Kakao, etc.) |
| `cvt_MQDKZ` | Clarity | Microsoft Clarity |
| `cvt_WF3R3` | Amplitude | Amplitude |

## FB Conversions API Integration

When creating tags that should trigger FB CAPI:
1. Check existing FBEventName mapping table (Regex Table variable)
2. If your custom event isn't mapped, add a new rule: `event_name → FB_Standard_Event`
3. Key mappings: `generate_lead → Lead`, `purchase → Purchase`, `page_view → PageView`

## Workflow

1. **Analyze**: Use Chrome DevTools to inspect the page (or receive from gtm-audit Mode D)
2. **Design**: Determine events, triggers, variables needed
3. **Create**: Use DTM Agent MCP tools to create in GTM
4. **Verify**: Hand off to gtm-validator for QA
5. **Document**: Write implementation details to Notion

## Rules

- Always use `dtm_status` first to verify auth and active container
- Always use `measurementIdOverride` for GA4 event tags (NOT `measurementId`)
- All Custom HTML must be ES5-compatible
- Use `--dry-run` conceptually — verify trigger selectors via Chrome DevTools before creating
- Rate limit: space API calls 1 second apart in batch operations
- Never delete tags without explicit user confirmation — move to Archive folder instead
- After creating tags, suggest user run gtm-validator to verify