metaads

工作流路由（系统提示词）

重要：根据用户意图路由到正确的工作流。

当用户需要设置或配置 Meta Ads API 访问权限时： 示例：“设置 Meta Ads”“连接 Meta Ads”“配置 Facebook 广告”“我的令牌已过期”“Meta Ads 设置”、--check 返回的凭据错误 -> 阅读： ~/.claude/skills/MetaAds/workflows/Setup.md -> 执行： 引导用户完成完整设置（Business Manager、应用、令牌、.env）

当用户想要发布、创建或启动广告系列时： 示例：“发布广告”“创建广告系列”“启动广告系列”“上传广告图片”“发布 Meta Ads”“将此广告系列推送到 Meta”“创建广告组” -> 阅读： ~/.claude/skills/MetaAds/workflows/PublishCampaign.md -> 执行： 广告系列发布工作流 -> 如果凭据验证失败，先路由到 Setup.md

当用户想要检查效果、指标或分析结果时： 示例：“检查 Meta 广告效果”“ROAS”“哪个广告表现最好”“广告支出”“广告系列指标”“我的广告效果如何”“受众细分”“创意效果” -> 阅读： ~/.claude/skills/MetaAds/workflows/AnalyzePerformance.md -> 执行： 效果分析工作流 -> 如果凭据验证失败，先路由到 Setup.md

当用户想要管理广告系列（暂停/恢复/状态）时： 示例：“暂停广告系列”“恢复广告系列”“广告系列状态”“列出广告系列” -> 直接使用 uv run ~/.claude/skills/MetaAds/tools/Publish.py，并添加 --pause、--resume、--status 或 --list

---

何时激活此技能

设置与配置（类别 0）

• “设置 Meta Ads”“连接 Meta Ads API”“配置 Facebook 广告”
• “Meta Ads 设置”“如何连接我的广告账户”
• “我的令牌已过期”“令牌错误”“无法访问 Meta Ads”
• “刷新我的 Meta 令牌”“续期访问令牌”
• --check 返回的任何凭据错误

广告系列发布（类别 1）

• “发布广告”“创建广告系列”“启动广告系列”
• “将此推送到 Meta”“设置广告系列”“上传广告图片”
• “发布 Meta Ads”“创建广告组”“构建广告系列”
• “发布此广告系列配置”“让广告正式上线”

效果分析（类别 2）

• “检查 Meta 广告效果”“我的广告效果如何”
• “ROAS”“广告支出回报率”“广告支出”“广告指标”
• “哪个广告表现最好”“表现最佳的广告”
• “广告系列指标”“广告组效果”“创意效果”
• “受众细分”“年龄/性别细分”
• “CTR”“CPC”“CPM”“CPA”“单次转化费用”

广告系列管理（类别 3）

• “暂停广告系列”“恢复广告系列”“激活广告系列”
• “广告系列状态”“列出广告系列”“显示我的广告系列”

---

核心能力

引导式设置：

• 完整流程引导：Business Manager -> 开发者应用 -> 令牌 -> .env
• 两种令牌路径：系统用户（永不过期）或用户令牌（60 天有效，并自动刷新）
• 自动交换令牌（Agent 运行 curl 命令）
• 转化追踪 Pixel 设置指南
• 针对每种常见故障的错误诊断与具体修复方法

广告系列发布：

• 将本地目录中的图片上传到 Meta
• 创建完整的广告系列层级（广告系列 -> 广告组 -> 创意 -> 广告）
• 支持包含多张图片/多段文案/多个标题的 Advantage+ 灵活创意
• 所有对象均创建为已暂停状态，供人工审核
• 由 JSON 配置驱动，以便重复创建广告系列

效果分析：

• 账户级摘要，包含 DTC 基准指标（CTR、CPM、CPA、ROAS）
• 广告系列、广告组和广告级指标
• 用于深入分析广告系列的每日趋势分析
• 受众细分（年龄、性别、平台、设备）
• 将数据同步到 Analytics/meta-ads/，以便进行跨渠道分析
• 导出 CSV，供电子表格分析使用

广告系列管理：

• 列出所有广告系列及其状态
• 查看广告系列层级（广告系列 -> 广告组 -> 广告）
• 暂停/恢复广告系列

---

脚本

脚本	用途
tools/Publish.py	创建广告系列、上传图片、暂停／恢复
tools/Analytics.py	性能指标、细分、同步、导出

两个脚本都使用 PEP 723 内联依赖项——只需在技能目录中直接使用 uv run 运行。无需安装或复制。

用法

在技能目录中直接运行脚本。脚本会从当前工作目录（Path.cwd()）加载 .env，因此请在项目根目录中运行：

# From your project root (where .env lives):
uv run ~/.claude/skills/MetaAds/tools/Publish.py --check
uv run ~/.claude/skills/MetaAds/tools/Analytics.py --summary

**前提条件：**必须安装 uv。如果尚未安装：curl -LsSf https://astral.sh/uv/install.sh | sh

环境变量（.env）：

变量	必需	说明
META_ADS_ACCESS_TOKEN	是	系统用户令牌或长期有效的用户令牌
META_ADS_ACCOUNT_ID	是	带有 act_ 前缀的广告账户 ID
FACEBOOK_APP_ID	用于刷新	用于令牌交换的应用 ID
FACEBOOK_APP_SECRET	用于刷新	用于令牌交换的应用密钥

---

广告系列目标参考

在广告系列配置中使用以下目标：

目标	适用场景	优化目标
OUTCOME_SALES	DTC 购买、Shopify 转化	OFFSITE_CONVERSIONS
OUTCOME_LEADS	潜在客户开发、电子邮件注册、测验漏斗	LEAD_GENERATION
OUTCOME_TRAFFIC	落地页访问、博客流量	LINK_CLICKS
OUTCOME_AWARENESS	品牌认知、视频观看	REACH 或 IMPRESSIONS
OUTCOME_ENGAGEMENT	帖子互动、主页赞	POST_ENGAGEMENT

---

广告系列配置模板

适用于任何 DTC 品牌的通用模板：

{
  "campaign": {
    "name": "campaign-name-month-year",
    "objective": "OUTCOME_SALES"
  },
  "adsets": [
    {
      "name": "Broad-25-54-US",
      "daily_budget": 5000,
      "targeting": {
        "age_min": 25,
        "age_max": 54,
        "genders": [0],
        "geo_locations": {"countries": ["US"]},
        "publisher_platforms": ["facebook", "instagram"],
        "facebook_positions": ["feed", "video_feeds", "story", "reels"],
        "instagram_positions": ["stream", "story", "reels", "explore"]
      },
      "optimization_goal": "OFFSITE_CONVERSIONS",
      "bid_strategy": "LOWEST_COST_WITHOUT_CAP"
    }
  ],
  "creative": {
    "images_directory": "./path/to/ad-images/",
    "primary_texts": [
      "Primary text variant 1 — lead with the hook or pain point",
      "Primary text variant 2 — lead with the benefit or social proof",
      "Primary text variant 3 — lead with a comparison or price anchor"
    ],
    "headlines": [
      "Short Punchy Headline",
      "Benefit-Driven Headline",
      "Price/Value Headline"
    ],
    "descriptions": [
      "Supporting description with key differentiator"
    ],
    "link_url": "https://yoursite.com/landing-page",
    "url_parameters": "utm_source=meta&utm_medium=paid-social&utm_campaign=campaign-name&utm_content={{ad.name}}",
    "call_to_action_type": "SHOP_NOW"
  }
}

配置说明：

• daily_budget 的单位是美分（5000 = 每天 $50.00）
• genders：0 = 全部，1 = 男性，2 = 女性
• {{ad.name}} 是 Meta 动态参数——会自动填入广告名称
• call_to_action_type 可选项：SHOP_NOW、LEARN_MORE、SIGN_UP、GET_OFFER、ORDER_NOW、SUBSCRIBE、BOOK_NOW

---

DTC 基准参考

指标	良好	尚可	需要改进	含义
CTR	>1.5%	1-1.5%	<1%	点击广告的展示次数占比。数值低 = 创意内容未能引起共鸣
CPM	<$15	$15-25	>$25	每 1000 次展示的费用。数值高 = 竞价竞争激烈或受众范围狭窄
CPC	<$1	$1-2	>$2	每次点击的费用。数值高 = CTR 低导致成本上升
CPA	<$30	$30-50	>$50	每次购买的费用。最终的效率指标
ROAS	>3x	2-3x	<2x	每支出 $1 带来的收入。低于 2x 通常意味着扣除销货成本后会亏损
Frequency	1-3	3-5	>5	每个人看到广告的平均次数。数值高 = 广告疲劳
Hook Rate	>25%	15-25%	<15%	观看视频前 3 秒的人数占比。数值低 = 开场效果弱
Hold Rate	>10%	5-10%	<5%	观看 15 秒以上的人数占比。数值低 = 内容无法持续吸引兴趣

---

优化指南

扩大优胜广告的投放：

• 每 2-3 天将预算增加 20-30%（不要一次性全部增加——这会重置学习阶段）
• 使用新的受众复制表现优异的广告组
• 根据购买者创建类似受众

改进表现不佳的广告：

• CTR < 1%：测试新的开场或图片——创意内容没能让用户停下滑动
• CTR > 2% 但没有购买：问题出在落地页，而不是广告
• CPA 过高：缩小定向范围或测试漏斗下层受众
• Frequency > 4：换上新创意
• 48 小时后仍没有消耗：暂时将优化目标切换为 Link Clicks，然后再切回 Conversions

Meta 学习阶段：

• 每个广告组需要在 7 天内获得约 50 次转化才能退出学习阶段
• 学习阶段内不要编辑（会重置计时）
• 如果预算不足以支持每周 50 次转化，请针对更靠近漏斗上层的事件进行优化（例如选择 ATC 而非 Purchase）

---

示例

示例 1：首次设置

用户：“我想为我的商店设置 Meta 广告”

技能响应：

1. 跳转至 Setup.md 工作流
2. 检查是否存在 .env，以及是否已设置 Business Manager
3. 引导用户创建 Developer App
4. 帮助生成并交换令牌
5. 配置 .env
6. 使用 --check 验证

示例 2：发布广告系列

用户：“为我们的新产品发布创建一个广告系列”

技能响应：

1. 跳转至 PublishCampaign.md 工作流
2. 检查凭据（如果缺失，则跳转至 Setup）
3. 询问图片、文案、定向和预算
4. 构建配置 JSON
5. 发布（全部设为 PAUSED）
6. 报告广告系列 ID 和审核清单

示例 3：查看效果

用户：“我的 Meta 广告效果如何？”

技能响应：

1. 跳转至 AnalyzePerformance.md 工作流
2. 运行 --summary 查看账户概览
3. 与 DTC 基准进行比较
4. 找出表现最好和最差的广告
5. 提供具体的优化建议

示例 4：令牌过期

用户：“我的 Meta 广告令牌无法使用”／Agent 检测到错误代码 190

技能响应：

1. 跳转至 Setup.md 第 6 部分（令牌刷新）
2. 检查 .env 中是否存在 FACEBOOK_APP_ID 和 FACEBOOK_APP_SECRET
3. 告诉用户在 Graph API Explorer 中生成新的短期令牌
4. 运行交换令牌的 curl 命令
5. 使用新的长期令牌更新 .env
6. 使用 --check 验证

示例 5：管理广告系列

用户：“暂停广告系列 12345678”

技能响应：

1. 运行 uv run ~/.claude/skills/MetaAds/tools/Publish.py --pause 12345678
2. 确认广告系列已暂停

---

最后更新： 2026-02-07