Claude Code / Codex 广告操作包

一个页面看懂：该叫哪个 Skill，怎么安全执行。

这是给使用者看的快速手册：从竞品研究、策略生产、创意生产，到本方账户分析、Meta/XHS 执行、release 安装和 CI 校验。重点不是“功能很多”，而是每个 skill 有清楚边界，真实广告账户写操作不会误触。

从安装开始 直接看路由表
01 quickstart

第一次使用：先装包，再配置 token，再让 agent 选 skill。

Release zip 解压后同时安装用户级 skill 和完整 CLI 项目。平时对话时先说业务目标，agent 根据下方路由规则决定调用哪个 skill。

step 1

下载并解压 release

从 GitHub Release 下载 `media-ads-skill-latest.zip`，不要下载 GitHub 自动生成的 source code zip。

unzip media-ads-skill-latest.zip -d ~
cd ~/media-ads-skill
step 2

安装 Python 依赖

核心 CLI 用 `uv` 管理。需要 scraper/dev 额外依赖时再跑 all-extras。

uv sync
# 可选：uv sync --all-extras
step 3

配置真实账户凭证

不知道 token 怎么拿，就触发 `token-setup`。不要把 `.env` 提交到 Git。

cp .env.example .env
# META_ACCESS_TOKEN=...
# META_ACCOUNT_ID=act_...
# XHS_ACCESS_TOKEN=...
smoke check

确认 CLI 可用

uv run media-buyer --help
uv run data-analysis --help
uv run content-creator --help
python scripts/validate-skills.py
02 routing

怎么判断该用哪个 skill？先看数据源，再看最终动作。

这套隔离规则解决过去的重叠问题：比如“FB广告分析”可能是竞品库研究，也可能是本方账户复盘；现在按 source-of-truth 拆开。

用户真实意图唯一 owner边界 / 禁止越界
外部竞品广告库、IG、市场资料、竞品视频content-creator不读本方账户 spend/CPL/CTR；不输出 live 执行命令。
本方 Meta/XHS 账户或导出广告表现数据data-analysis只读拉数、诊断、报告和行动建议；预算/status/publish 转执行 skill。
没有账户数据，只问 Meta 策略、政策、设置、排障consult调用知识库给建议；不拉账户数据，不执行写操作。
既有 Meta 对象 cut/scale/pause/budget/clone/relaunch/repairmeta-ads-ops必须先读当前状态，再 dry-run；不负责新 CT 发布。
从 ready creative + copy 创建新的 Meta CT campaign/ad set/admeta-ct-publish只接受已备好素材和文案；不写文案，不 relaunch 旧广告。
XHS 聚光计划/单元预算、出价、时段、复制、托管xhs-ads-ops不套用 Meta 单位；XHS 预算用元，出价用分。
平台不明的 cut/scale/暂停/改预算/执行media-buyer只做 legacy router；不能直接执行写操作。
example

“帮我分析广告为什么 CTR 低”

如果要看 Taipan/Segambut 真实账户数据 → `data-analysis`。如果只是问通用策略“CTR 低通常怎么优化” → `consult`。

example

“FB 广告分析”

如果是竞品广告库、竞品素材、外部品牌 → `content-creator`。如果是自己的广告后台表现 → `data-analysis`。

03 workflow

两条最常用链路：新广告上线和每周优化。

上游研究和真实账户执行不要混在同一个 skill。先让正确的 skill 产出结构化结果，再交给下一个 owner。

new launch

新产品 / 新客上线

content-creator→ codex→ creator→ meta-ct-publish

先研究外部市场，再生成策略和创意，最后用 ready creative/copy 创建 CT 测试对象。新建对象默认 `PAUSED`。

weekly ops

日常账户优化

data-analysis→ meta-ads-ops/ xhs-ads-ops

先只读拉数和诊断，再把明确行动转成 dry-run。用户确认后才 live。

04 skills

12 个 skill 的职责、输入、输出。

下面是用户最需要知道的使用边界。目录名用于安装，frontmatter `name` 用于 agent 识别；二者通常一致，`ads-budget-planning` 是历史目录别名。

external research

content-creator

外部竞品、IG、市场、竞品视频研究。

  • 输入：行业、关键词、竞品账号、视频素材。
  • 输出：竞品/市场/创意洞察报告。
  • 不做：本方账户表现分析。
account analysis

data-analysis

本方账户或导出数据的只读分析。

  • 输入：账户、日期范围、北极星指标。
  • 输出：结果表、行动清单、报告。
  • 不做：live 写操作。
legacy router

media-buyer

兼容旧入口，只把模糊执行请求分发到具体 skill。

  • Meta 执行 → `meta-ads-ops`。
  • CT 发布 → `meta-ct-publish`。
  • XHS 执行 → `xhs-ads-ops`。
meta existing ops

meta-ads-ops

既有 Meta 对象执行、clone/relaunch、修复、health-check。

  • 先读当前状态和预算。
  • 先 dry-run，显示当前 → 目标。
  • live 后读回确认并留痕。
new ct publish

meta-ct-publish

从 ready creative + copy 创建新的 CT 测试广告。

  • 输入：已备好素材、caption、headline。
  • 默认：新对象 `PAUSED`。
  • 不做：旧广告 relaunch。
xhs ops

xhs-ads-ops

小红书聚光计划、预算、出价、时段、复制、auto-pilot。

  • 预算单位：元。
  • 出价单位：分。
  • 没有 dry-run 支持的写命令不能 live。
budget plan

iterative-ad-budget-planning

月度预算、pacing、执行看板和计划 artifact。

  • 目录：`ads-budget-planning`。
  • 用于讨论和计划。
  • 不做 live 写操作。
strategy

codex

17 字段客户资料 → NotebookLM → Avatar → Pain-Hunter → Codex 11 字段。

  • 需要 notebook 配置。
  • 阶段输出要给用户确认。
  • 完成后交给 `creator`。
creative production

creator

脚本、caption、headline、日常文案和批量生产。

  • Codex 驱动：3-5 变体。
  • 日常模式：单条文案/脚本。
  • 不发布广告。
consulting

consult

Meta 通用策略、政策、设置、账户受限和知识库问答。

  • 没有本方账户数据时使用。
  • 回答策略和排障。
  • 不执行写操作。
credentials

token-setup

Meta、XHS、NotebookLM、Notion、Gemini、cookie 等配置引导。

  • 先检查 `.env`。
  • 轻量验证 token 是否有效。
  • 不做业务操作。
extension

skill-gen

生成新 skill 的骨架文件。

  • 输出 `SKILL.md` + scripts + lib + tests。
  • 名称冲突拒绝。
  • 新 skill 仍需人工补业务逻辑。
05 examples

可以直接这样问。

自然语言可以模糊，但 agent 必须用上面的 owner 规则拆清楚，不确定平台时先问。

read-only analysis

本方广告表现

帮我分析 Taipan 最近 7 天广告，
北极星 CPL，目标 RM50。
先只读，不要做任何写操作。
external research

竞品研究

帮我找 KL aesthetic clinic 的竞品广告，
重点看 offer、hook、素材形式。
不要看我们自己的账户。
meta ops

既有广告执行

把这 3 个 Meta ad set 改成 PAUSED。
先 dry-run，展示当前状态 -> 目标状态，
我确认后才 live。
new publish

CT 发布

这批 Notion ready creative 做 CT 发布。
先生成 review artifact，再 dry-run。
新对象必须 PAUSED。
06 safety

真实广告账户安全底线。

这些规则是商业护栏，不是建议。即使用户催促，也不能跳过。

dry-run first

所有写操作先 dry-run

Meta/XHS 的创建、暂停、启用、预算、出价、修复、发布，都必须先展示 dry-run。

confirm then live

当前对话明确确认

只有用户看过 dry-run 并明确确认后，才能执行 `--no-dry-run` 或 live 命令。

paused default

新建对象默认 PAUSED

Campaign / ad set / ad 新建后一律 PAUSED。除非用户当前明确说要 ACTIVE。

budget units

预算单位不能混

Meta 预算是 cents，并用账户真实货币 RM 展示；XHS 预算是元，出价是分。

no one-off scripts

不写一次性广告脚本

已有 CLI 能力必须复用；缺能力就扩展 `lib/` + CLI + tests，不绕过业务层直打 API。

reports path

留痕只写月度分行报告

广告分析/操作记录写 `data/reports/YYYY-MM/{taipan|segambut}.md`，不在根目录散落报告。

07 release

Release 会同时安装到 .claude、.codex、.agents。

仓库里不提交本地 `.codex/` 目录；CI 只验证 zip 解压后用户 home 下的安装布局。

zip layout

解压后目录

~/.claude/skills/{project skills}/
~/.agents/skills/{project skills}/
~/.codex/skills/{project skills}/
~/media-ads-skill/
local build

本地打包和校验

scripts/package-skills.sh \
  --output dist/media-ads-skill-latest.zip

python scripts/validate-skills.py \
  --archive dist/media-ads-skill-latest.zip
CI 检查目的失败时代表什么
source manifest检查 `skills/*/SKILL.md` frontmatter name 唯一、description 非空。skill 命名或描述不合格，agent 可能无法稳定识别。
three platform layout检查 `.claude/skills`、`.codex/skills`、`.agents/skills` 与源码 skill 完全一致。某个平台安装缺 skill 或多出旧 skill。
clean archive阻止 `data/`、`output/`、`tests/`、`.env`、项目内 `.codex/` 进入 release。本地报告、token、测试或安装目录污染了分发包。
08 troubleshooting

常见问题怎么判断。

这部分给用户快速排除“我该找谁”和“为什么不能直接 live”。

用户说“分析广告”，但没说是竞品还是自己账户。

先问清楚数据源。竞品/外部 → `content-creator`；自己账户/导出数据 → `data-analysis`。

用户说“帮我 cut/scale”。

如果是问该不该做 → `data-analysis` 或 `consult`；如果已经明确执行对象 → `meta-ads-ops` / `xhs-ads-ops`，先 dry-run。

用户说“投放新广告”。

如果素材和文案没准备好 → `creator`；ready creative/copy 已备好 → `meta-ct-publish`，默认 PAUSED。

release zip 里缺某个 skill。

跑 `python scripts/validate-skills.py --archive dist/media-ads-skill-latest.zip`，看是哪套平台目录和源码 `skills/` 不一致。