Content
# google-marketing-ops
> **Built for Claude Code. Works on any project — clone, fill in `local/project-context.md`, done.**
Claude Code skill for orchestrating Google Ads + Google Analytics 4 + Google Tag Manager from a single conversation. Routes user intent to the right tool, combines multiple tools when a task spans them, and provides analysis playbooks beyond raw data dumps.
> **Configuration model**: All project-specific values (GA property IDs, domains, file paths, weekly-report conventions) live in `local/project-context.md` (gitignored). The skill itself is generic and reusable across projects — clone, fill in `local/project-context.md`, done.
## What it does
| Tool | Read | Write | Underlying integration |
|---|---|---|---|
| Google Ads | ✅ | ✅ | `google-ads-api` skill (Python SDK + `~/.google-ads.yaml`) |
| Google Analytics 4 | ✅ | ❌ | [`analytics-mcp`](https://github.com/googleanalytics/google-analytics-mcp) (official Google MCP, ADC-based) |
| Google Tag Manager | ✅ | ✅ | `mcp__gtm__*` (HTTP MCP via OAuth) |
The skill itself doesn't reimplement any of these — it routes, combines, and adds an analysis layer on top.
## Why a skill (and not just MCP)
Each underlying integration exposes atomic operations. A skill is the right shape when:
1. **A task crosses multiple tools** (e.g., Ads change → GA verification → GTM debug)
2. **Raw data needs interpretation** (channel breakdown is data; "your Paid Search bounce rate jumped 30%, here's likely why" is analysis)
3. **There's a fixed SOP** (the weekly Ads-review closed loop)
Calling MCP directly works for one-off queries. Use this skill when you need orchestration.
## Architecture
```
SKILL.md # Entry routing (~150 lines)
playbooks/
├── setup-check.md # Credential & MCP health check (run this first on a new machine)
├── ads-config.md # Ads write operations (bids, keywords, negative keywords, budgets, campaigns)
├── ads-analysis.md # Ads read operations (GAQL queries, search terms, quality score)
├── ga-analysis.md # GA4 reporting (channels, landing pages, funnels, attribution)
├── gtm-debug.md # GTM tag/trigger/variable management + version publishing
├── cross-tool-flows.md # Multi-tool playbooks (Ads-after-change validation, conversion reconciliation)
└── weekly-review.md # Weekly Ads-change closed loop (report + maintenance plan + decision log)
```
`SKILL.md` is the only file always loaded. Playbooks are read on demand based on the user's task.
## Installation
### 1. Install dependencies
```bash
# Python tools
pipx install analytics-mcp # GA4 MCP
pipx install google-ads # Google Ads SDK (or pip in your project's venv)
# gcloud (for ADC authentication)
brew install --cask google-cloud-sdk # macOS
```
### 2. Authenticate
**Google Ads** — put OAuth refresh-token credentials at `~/.google-ads.yaml`:
```yaml
developer_token: "..."
client_id: "..."
client_secret: "..."
refresh_token: "..."
login_customer_id: "..."
```
**GA4** — Application Default Credentials with the right scopes:
```bash
gcloud auth application-default login \
--scopes=https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform
```
**GTM** — OAuth via Claude Code MCP:
```bash
# Configure GTM MCP (URL is provider-specific, see your MCP provider's docs)
claude mcp add --scope user --transport http gtm <gtm-mcp-url>
# Then in Claude Code, run /mcp and complete OAuth for "gtm"
```
### 3. Register GA MCP with Claude Code
```bash
claude mcp add --scope user analytics-mcp -- $(which analytics-mcp)
claude mcp list # confirm "analytics-mcp ... ✓ Connected"
```
### 4. Install this skill
Clone into your skills directory (the standard location is `~/.claude/skills/`):
```bash
cd ~/.claude/skills # or your symlinked AI_Skills repo
git clone https://github.com/<user>/google-marketing-ops.git
```
Restart Claude Code so the new skill metadata is picked up.
### 5. Verify
In Claude Code, ask:
> "跑 setup-check"
The agent should walk through all credential/MCP checks and report any gaps.
## Limitations
- **GA writes** (creating audiences, custom dimensions, event create rules) are not supported — the official `analytics-mcp` is read-only. Workarounds: edit configuration via GTM where possible, or implement a custom GA Admin API integration.
- **Ads campaign creation** is recommended via the web UI rather than API — the API requires too many fields to get right and the failure modes are expensive.
- **Cross-tool conversion numbers will not match exactly.** Ads vs GA vs GTM differ by attribution model, time zone, sampling, and de-duplication. The `cross-tool-flows.md` playbook explains the standard reconciliation; do not try to force them equal.
## Configuration
All project-specific values are in `local/project-context.md` (gitignored). Copy `local/project-context.md.example` and fill in:
- GA Property IDs (main + secondary)
- Domains (main + secondary)
- Google Ads tools repo path (if you have one with cached CSV data)
- GTM Container ID
- Weekly-report file path conventions (only if you adopt the W-week SOP from `playbooks/weekly-review.md`)
- Anything else the AI should know about your specific setup
The skill itself contains no hard-coded project values. To use across multiple projects, swap out `local/project-context.md` accordingly.
## License
TBD before open-source. Recommend MIT or Apache-2.0.
## Contributing
Issues and PRs welcome once open-sourced. The skill is intentionally lean — please don't add bundled scripts unless you've observed the same pattern repeated across 3+ playbooks (YAGNI principle).
