内容
# google-marketing-ops
> **为 Claude Code 构建。适用于任何项目 — 克隆，填写 `local/project-context.md`，完成。**
Claude Code 技能，用于协调 Google Ads + Google Analytics 4 + Google Tag Manager，单次对话即可完成。路由用户意图到正确的工具，结合多个工具完成任务，并提供分析手册，而非简单的数据转储。
> **配置模型**：所有项目特定的值（GA 属性 ID、域名、文件路径、每周报告约定）都存放在 `local/project-context.md`（gitignored）。技能本身是通用且可重用的，适用于跨项目 — 克隆，填写 `local/project-context.md`，完成。
## 功能
| 工具 | 读取 | 写入 | 底层集成 |
|---|---|---|---|
| Google Ads | ✅ | ✅ | `google-ads-api` 技能（Python SDK + `~/.google-ads.yaml`） |
| Google Analytics 4 | ✅ | ❌ | [`analytics-mcp`](https://github.com/googleanalytics/google-analytics-mcp)（官方 Google MCP，基于 ADC） |
| Google Tag Manager | ✅ | ✅ | `mcp__gtm__*`（HTTP MCP via OAuth） |
技能本身并未重新实现这些功能 — 它路由、组合并在上面添加分析层。
## 为什么是技能（而不仅仅是 MCP）
每个底层集成都暴露出原子操作。当以下情况时，技能是合适的：
1. **任务跨越多个工具**（例如，广告更改 → GA 验证 → GTM 调试）
2. **原始数据需要解释**（渠道分解是数据；“您的付费搜索跳出率增加了 30%，可能的原因是” 是分析）
3. **有固定的 SOP**（每周广告审查闭环）
直接调用 MCP 适用于一次性查询。当您需要协调时，请使用此技能。
## 架构
```
SKILL.md # 入口路由（~150 行）
playbooks/
├── setup-check.md # 凭证和 MCP 健康检查（在新机器上首先运行此命令）
├── ads-config.md # 广告写入操作（出价、关键词、否定关键词、预算、活动）
├── ads-analysis.md # 广告读取操作（GAQL 查询、搜索词、质量评分）
├── ga-analysis.md # GA4 报告（渠道、着陆页、漏斗、归因）
├── gtm-debug.md # GTM 标签/触发器/变量管理和版本发布
├── cross-tool-flows.md # 跨工具工作流程（广告更改后验证、转换协调）
└── weekly-review.md # 每周广告更改闭环（报告 + 维护计划 + 决策日志）
```
`SKILL.md` 是唯一始终加载的文件。根据用户任务按需读取工作流程。
## 安装
### 1. 安装依赖
```bash
# Python 工具
pipx install analytics-mcp # GA4 MCP
pipx install google-ads # Google Ads SDK（或在项目虚拟环境中安装 pip）
# gcloud（用于 ADC 身份验证）
brew install --cask google-cloud-sdk # macOS
```
### 2. 身份验证
**Google Ads** — 在 `~/.google-ads.yaml` 中放置 OAuth 刷新令牌凭证：
```yaml
developer_token: "..."
client_id: "..."
client_secret: "..."
refresh_token: "..."
login_customer_id: "..."
```
**GA4** — 具有正确范围的应用程序默认凭证：
```bash
gcloud auth application-default login \
--scopes=https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform
```
**GTM** — 通过 Claude Code MCP 进行 OAuth：
```bash
# 配置 GTM MCP（URL 是提供者特定的，请参阅提供者的文档）
claude mcp add --scope user --transport http gtm <gtm-mcp-url>
# 然后在 Claude Code 中运行 /mcp 并完成“gtm”的 OAuth
```
### 3. 将 GA MCP 注册到 Claude Code
```bash
claude mcp add --scope user analytics-mcp -- $(which analytics-mcp)
claude mcp list # 确认“analytics-mcp ... ✓ 已连接”
```
### 4. 安装此技能
克隆到您的技能目录（标准位置是 `~/.claude/skills/`）：
```bash
cd ~/.claude/skills # 或您的 AI_Skills 仓库的符号链接
git clone https://github.com/<user>/google-marketing-ops.git
```
重启 Claude Code 以便选取新的技能元数据。
### 5. 验证
在 Claude Code 中，询问：
> “运行 setup-check”
代理应遍历所有凭证/MCP 检查并报告任何空白。
## 限制
- **GA 写入**（创建受众、自定义维度、事件创建规则）不受支持 — 官方 `analytics-mcp` 是只读的。变通方法：通过 GTM 编辑配置（如果可能），或实施自定义 GA 管理 API 集成。
- **广告活动创建** 建议通过网页界面进行，而不是通过 API — API 需要太多字段才能正确，且失败模式的成本很高。
- **跨工具转换次数不会完全匹配。** 广告与 GA 与 GTM 不同，归因模型、时区、采样和去重。`cross-tool-flows.md` 工作流程解释了标准协调；请勿尝试强制它们相等。
## 配置
所有项目特定的值都存放在 `local/project-context.md`（gitignored）。复制 `local/project-context.md.example` 并填写：
- GA 属性 ID（主要 + 次要）
- 域名（主要 + 次要）
- Google Ads 工具仓库路径（如果您有带有缓存 CSV 数据的仓库）
- GTM 容器 ID
- 每周报告文件路径约定（仅当您采用 `playbooks/weekly-review.md` 中的 W 周 SOP 时）
- 您的 AI 应了解的特定设置的任何其他信息
技能本身不包含硬编码的项目值。要跨多个项目使用，请相应地交换 `local/project-context.md`。
## 许可证
开源前 TBD。建议 MIT 或 Apache-2.0。
## 贡献
开源后欢迎问题和 PR。技能故意保持精简 — 请不要添加捆绑脚本，除非您已在 3+ 工作流程中观察到相同的模式（YAGNI 原则）。
MCP 市场