Meta Ads CLI Agent Skill
This skill teaches an AI agent to operate Meta ads through Meta's official Ads CLI instead of reimplementing the Marketing API.
The core command shape is:
meta ads <resource> <action> [options]
Examples from the official Ads CLI pattern include:
meta ads campaign list
meta ads campaign create --name "Summer Sale" --objective OUTCOME_SALES --daily-budget 5000
meta ads adset create CAMPAIGN_ID --name "My Ad Set" --optimization-goal LINK_CLICKS --billing-event IMPRESSIONS --targeting-countries US
meta ads creative create --name "Hero Banner" --page-id 111222333 --image ./banner.jpg --body "50% off" --title "Shop Now" --link-url https://example.com/sale --call-to-action SHOP_NOW
meta ads ad create ADSET_ID --name "Hero Banner Ad" --creative-id CREATIVE_ID
meta ads insights get --campaign_id CAMPAIGN_ID --fields impressions,conversions,spend --date-preset last_7d
Use the bundled guard script as the default execution path:
python3 scripts/meta_ads_agent.py doctor
python3 scripts/meta_ads_agent.py classify -- meta ads campaign list
python3 scripts/meta_ads_agent.py run -- meta ads campaign list --limit 25
The guard script does not replace Meta's CLI. It wraps it so agents behave safely and consistently.
Highest-priority rules
- Use Meta's official CLI first. Do not call Graph API directly unless the official CLI cannot do the task and the user explicitly accepts a lower-level workaround.
- Read before write. Inspect the relevant account/object/performance state before changing it.
- No spend-affecting change without explicit user approval. Writes, budget changes, activation, delete/remove, dataset/catalog connections, and creative uploads need approval.
- Never activate by accident. New objects should remain
PAUSED unless the user explicitly asks to activate. ACTIVE, activate, delete, remove, and --force are high-risk.
- Prefer machine-readable output. Use JSON whenever possible:
meta --output json ads .... Use table output only for human presentation.
- One write step at a time. Apply one mutation, verify it, then continue.
- Do not invent IDs. Resolve account, campaign, ad set, creative, page, pixel/dataset, catalog, product set, and targeting IDs from the CLI or user-provided values.
- Keep tokens out of chat and logs. Never print access tokens, app secrets, cookies, or
.env contents.
- Ask for missing material only when blocking. For reads, proceed with defaults. For writes, collect exact account, IDs, budget, date range, page/dataset/catalog, destination URL, and approval.
- Treat regulated/special categories carefully. Housing, employment, credit, politics, social issues, health, financial services, minors, and sensitive audiences require extra review and conservative targeting.
Recommended agent flow
For almost every request, follow this order:
1. Classify request: read-only, ordinary write, budget/write, activation, destructive, regulated.
2. Run doctor/auth check if account access is uncertain.
3. Read current state with compact JSON output.
4. Produce a short plan with exact commands, risks, assumptions, and verification commands.
5. For read-only tasks: run commands and summarise.
6. For writes: wait for explicit approval, then run through scripts/meta_ads_agent.py.
7. Verify state after every write.
8. Report what changed, object IDs, before/after values, and any unresolved issues.
Install and auth checklist
# Meta docs list meta-ads as the package name.
python3.12 -m pip install meta-ads
# Confirm the CLI is available.
meta --help
meta ads --help
# Auth status. Meta docs show ACCESS_TOKEN for token-based auth.
export ACCESS_TOKEN=<ACCESS_TOKEN>
meta auth status
# Prefer an explicit ad account for every command until a default is proven.
meta ads --ad-account-id <AD_ACCOUNT_ID> campaign list
Do not guess config keys if auth fails. Run:
meta auth status
meta ads --help
meta ads <resource> --help
Then follow the official CLI setup/configuration docs for the installed version.
Using the guard script
Check readiness
python3 scripts/meta_ads_agent.py doctor
Classify command risk without executing
python3 scripts/meta_ads_agent.py classify -- meta ads campaign update 123 --status ACTIVE
Run a read-only command
python3 scripts/meta_ads_agent.py run -- meta ads campaign list --limit 25
Run a write after approval
python3 scripts/meta_ads_agent.py run \
--approved "User approved creating the paused campaign named Summer Sale in account act_123" \
-- meta ads campaign create --name "Summer Sale" --objective OUTCOME_SALES --daily-budget 5000
Run an activation after stronger approval
python3 scripts/meta_ads_agent.py run \
--approved "User approved activating campaign 123 after reviewing it" \
--allow-active \
-- meta ads campaign update 123 --status ACTIVE
Lint or run a multi-step plan
python3 scripts/meta_ads_agent.py lint-plan templates/weekly-report-plan.json
python3 scripts/meta_ads_agent.py run-plan templates/weekly-report-plan.json
Write-heavy plans require --approved ...; activation/destructive plans require additional flags.
Fast task routing
| User intent |
First action |
Main workflow |
| “Show performance” |
Read-only |
references/REPORTING.md |
| “What should I pause?” |
Read insights, then propose |
references/WORKFLOWS.md#performance-triage |
| “Pause this ad/campaign” |
Read object + metrics |
references/WORKFLOWS.md#safe-pause |
| “Increase budget” |
Read currency, current budget, delivery |
references/WORKFLOWS.md#budget-change |
| “Launch campaign” |
Build paused launch plan |
references/WORKFLOWS.md#paused-launch |
| “Create catalogue/product set” |
Check account/catalog context |
references/WORKFLOWS.md#catalogs-and-products |
| “Check pixel” |
Dataset and insights audit |
references/WORKFLOWS.md#datasetpixel-audit |
| “Use another endpoint” |
Verify official CLI coverage first |
references/TROUBLESHOOTING.md#when-the-cli-does-not-cover-the-task |
Output expectations
For read-only analysis, return:
- what was queried
- date range and attribution assumptions
- top findings with numbers
- caveats about missing/zero/odd metrics
- recommended next actions separated from actual changes
For writes, return:
- object IDs touched
- before/after values
- command(s) run, redacted where needed
- verification result
- anything still paused/not live
- any follow-up the user must perform in Ads Manager
References in this skill
references/CRITICAL-ANALYSIS-v1.md — what v1 got right/wrong and why v2 changed direction.
references/OFFICIAL-ADS-CLI.md — concise Ads CLI reference for agents.
references/AGENT-OPERATING-MODEL.md — how agents should reason, plan, execute, and recover.
references/SAFETY.md — approval gates, budget/activation/destructive rules.
references/WORKFLOWS.md — account audits, reporting, launch, pause, budget, dataset/catalog workflows.
references/REPORTING.md — Insights fields, date ranges, breakdowns, and interpretation.
references/COMMANDS.md — command patterns and help-discovery strategy.
references/OPTIMISATION-DECISIONING.md — how to turn metrics into cautious recommendations.
resources/command-catalog.json and resources/risk-rules.json — machine-readable aids for agents.
agent-prompts/ and AGENTS.md — ready-made prompts/instructions for general shell agents.
references/TROUBLESHOOTING.md — auth, exit codes, output parsing, rate limits, API errors.
references/PORTABILITY.md — using this skill in non-OpenClaw agents.
templates/ — JSON plan templates and schema.
scripts/meta_ads_agent.py — optional safe command runner.
evals/ — behavioural evals for agent skill quality.
1---
2name: meta-ads-cli
3version: 2.0.0
4description: Use this skill when an AI agent needs to manage, audit, report on, create, pause, update, or troubleshoot Meta/Facebook/Instagram ads through Meta's official Ads CLI (`meta ads ...`). It is designed for any shell-capable agent, not just OpenClaw. It focuses on safe command planning, JSON output, confirmation gates, read-before-write behaviour, paused-by-default launches, reporting workflows, datasets/pixels, catalog/product operations, and failure handling.
5license: MIT. See LICENSE.txt
6compatibility: Requires a shell, Python 3.9+ for the optional guard script, and Meta's official Ads CLI (`pip install meta-ads`, Python 3.12+ per Meta docs). Works with OpenClaw, Claude Code, Codex CLI, Cursor, Aider, Goose, Crew/Autogen agents, and CI runners that can execute terminal commands.
7metadata:
8 source: https://skillmd.com/skills/tristanmanchester/meta-ads-cli
9 author: OpenAI
10 skill_type: agent-agnostic-shell-skill
11 primary_cli: meta ads
12 wrapped_cli: scripts/meta_ads_agent.py
13 risk_model: read-plan-approve-write-verify
14 created: 2026-04-30
15---
16
17# Meta Ads CLI Agent Skill
18
19This skill teaches an AI agent to operate Meta ads through Meta's official **Ads CLI** instead of reimplementing the Marketing API.
20
21The core command shape is:
22
23```bash
24meta ads <resource> <action> [options]
25```
26
27Examples from the official Ads CLI pattern include:
28
29```bash
30meta ads campaign list
31meta ads campaign create --name "Summer Sale" --objective OUTCOME_SALES --daily-budget 5000
32meta ads adset create CAMPAIGN_ID --name "My Ad Set" --optimization-goal LINK_CLICKS --billing-event IMPRESSIONS --targeting-countries US
33meta ads creative create --name "Hero Banner" --page-id 111222333 --image ./banner.jpg --body "50% off" --title "Shop Now" --link-url https://example.com/sale --call-to-action SHOP_NOW
34meta ads ad create ADSET_ID --name "Hero Banner Ad" --creative-id CREATIVE_ID
35meta ads insights get --campaign_id CAMPAIGN_ID --fields impressions,conversions,spend --date-preset last_7d
36```
37
38Use the bundled guard script as the default execution path:
39
40```bash
41python3 scripts/meta_ads_agent.py doctor
42python3 scripts/meta_ads_agent.py classify -- meta ads campaign list
43python3 scripts/meta_ads_agent.py run -- meta ads campaign list --limit 25
44```
45
46The guard script does **not** replace Meta's CLI. It wraps it so agents behave safely and consistently.
47
48## Highest-priority rules
49
501. **Use Meta's official CLI first.** Do not call Graph API directly unless the official CLI cannot do the task and the user explicitly accepts a lower-level workaround.
512. **Read before write.** Inspect the relevant account/object/performance state before changing it.
523. **No spend-affecting change without explicit user approval.** Writes, budget changes, activation, delete/remove, dataset/catalog connections, and creative uploads need approval.
534. **Never activate by accident.** New objects should remain `PAUSED` unless the user explicitly asks to activate. `ACTIVE`, `activate`, `delete`, `remove`, and `--force` are high-risk.
545. **Prefer machine-readable output.** Use JSON whenever possible: `meta --output json ads ...`. Use table output only for human presentation.
556. **One write step at a time.** Apply one mutation, verify it, then continue.
567. **Do not invent IDs.** Resolve account, campaign, ad set, creative, page, pixel/dataset, catalog, product set, and targeting IDs from the CLI or user-provided values.
578. **Keep tokens out of chat and logs.** Never print access tokens, app secrets, cookies, or `.env` contents.
589. **Ask for missing material only when blocking.** For reads, proceed with defaults. For writes, collect exact account, IDs, budget, date range, page/dataset/catalog, destination URL, and approval.
5910. **Treat regulated/special categories carefully.** Housing, employment, credit, politics, social issues, health, financial services, minors, and sensitive audiences require extra review and conservative targeting.
60
61## Recommended agent flow
62
63For almost every request, follow this order:
64
65```text
661. Classify request: read-only, ordinary write, budget/write, activation, destructive, regulated.
672. Run doctor/auth check if account access is uncertain.
683. Read current state with compact JSON output.
694. Produce a short plan with exact commands, risks, assumptions, and verification commands.
705. For read-only tasks: run commands and summarise.
716. For writes: wait for explicit approval, then run through scripts/meta_ads_agent.py.
727. Verify state after every write.
738. Report what changed, object IDs, before/after values, and any unresolved issues.
74```
75
76## Install and auth checklist
77
78```bash
79# Meta docs list meta-ads as the package name.
80python3.12 -m pip install meta-ads
81
82# Confirm the CLI is available.
83meta --help
84meta ads --help
85
86# Auth status. Meta docs show ACCESS_TOKEN for token-based auth.
87export ACCESS_TOKEN=<ACCESS_TOKEN>
88meta auth status
89
90# Prefer an explicit ad account for every command until a default is proven.
91meta ads --ad-account-id <AD_ACCOUNT_ID> campaign list
92```
93
94Do not guess config keys if auth fails. Run:
95
96```bash
97meta auth status
98meta ads --help
99meta ads <resource> --help
100```
101
102Then follow the official CLI setup/configuration docs for the installed version.
103
104## Using the guard script
105
106### Check readiness
107
108```bash
109python3 scripts/meta_ads_agent.py doctor
110```
111
112### Classify command risk without executing
113
114```bash
115python3 scripts/meta_ads_agent.py classify -- meta ads campaign update 123 --status ACTIVE
116```
117
118### Run a read-only command
119
120```bash
121python3 scripts/meta_ads_agent.py run -- meta ads campaign list --limit 25
122```
123
124### Run a write after approval
125
126```bash
127python3 scripts/meta_ads_agent.py run \
128 --approved "User approved creating the paused campaign named Summer Sale in account act_123" \
129 -- meta ads campaign create --name "Summer Sale" --objective OUTCOME_SALES --daily-budget 5000
130```
131
132### Run an activation after stronger approval
133
134```bash
135python3 scripts/meta_ads_agent.py run \
136 --approved "User approved activating campaign 123 after reviewing it" \
137 --allow-active \
138 -- meta ads campaign update 123 --status ACTIVE
139```
140
141### Lint or run a multi-step plan
142
143```bash
144python3 scripts/meta_ads_agent.py lint-plan templates/weekly-report-plan.json
145python3 scripts/meta_ads_agent.py run-plan templates/weekly-report-plan.json
146```
147
148Write-heavy plans require `--approved ...`; activation/destructive plans require additional flags.
149
150## Fast task routing
151
152| User intent | First action | Main workflow |
153|---|---|---|
154| “Show performance” | Read-only | `references/REPORTING.md` |
155| “What should I pause?” | Read insights, then propose | `references/WORKFLOWS.md#performance-triage` |
156| “Pause this ad/campaign” | Read object + metrics | `references/WORKFLOWS.md#safe-pause` |
157| “Increase budget” | Read currency, current budget, delivery | `references/WORKFLOWS.md#budget-change` |
158| “Launch campaign” | Build paused launch plan | `references/WORKFLOWS.md#paused-launch` |
159| “Create catalogue/product set” | Check account/catalog context | `references/WORKFLOWS.md#catalogs-and-products` |
160| “Check pixel” | Dataset and insights audit | `references/WORKFLOWS.md#datasetpixel-audit` |
161| “Use another endpoint” | Verify official CLI coverage first | `references/TROUBLESHOOTING.md#when-the-cli-does-not-cover-the-task` |
162
163## Output expectations
164
165For read-only analysis, return:
166
167```text
168- what was queried
169- date range and attribution assumptions
170- top findings with numbers
171- caveats about missing/zero/odd metrics
172- recommended next actions separated from actual changes
173```
174
175For writes, return:
176
177```text
178- object IDs touched
179- before/after values
180- command(s) run, redacted where needed
181- verification result
182- anything still paused/not live
183- any follow-up the user must perform in Ads Manager
184```
185
186## References in this skill
187
188- `references/CRITICAL-ANALYSIS-v1.md` — what v1 got right/wrong and why v2 changed direction.
189- `references/OFFICIAL-ADS-CLI.md` — concise Ads CLI reference for agents.
190- `references/AGENT-OPERATING-MODEL.md` — how agents should reason, plan, execute, and recover.
191- `references/SAFETY.md` — approval gates, budget/activation/destructive rules.
192- `references/WORKFLOWS.md` — account audits, reporting, launch, pause, budget, dataset/catalog workflows.
193- `references/REPORTING.md` — Insights fields, date ranges, breakdowns, and interpretation.
194- `references/COMMANDS.md` — command patterns and help-discovery strategy.
195- `references/OPTIMISATION-DECISIONING.md` — how to turn metrics into cautious recommendations.
196- `resources/command-catalog.json` and `resources/risk-rules.json` — machine-readable aids for agents.
197- `agent-prompts/` and `AGENTS.md` — ready-made prompts/instructions for general shell agents.
198- `references/TROUBLESHOOTING.md` — auth, exit codes, output parsing, rate limits, API errors.
199- `references/PORTABILITY.md` — using this skill in non-OpenClaw agents.
200- `templates/` — JSON plan templates and schema.
201- `scripts/meta_ads_agent.py` — optional safe command runner.
202- `evals/` — behavioural evals for agent skill quality.