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:

bash

meta ads <resource> <action> [options]

Examples from the official Ads CLI pattern include:

bash

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:

bash

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:

text

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

bash

# 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:

bash

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

bash

python3 scripts/meta_ads_agent.py doctor

Classify command risk without executing

bash

python3 scripts/meta_ads_agent.py classify -- meta ads campaign update 123 --status ACTIVE

Run a read-only command

bash

python3 scripts/meta_ads_agent.py run -- meta ads campaign list --limit 25

Run a write after approval

bash

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

bash

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

bash

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:

text

- 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:

text

- 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.

meta-ads-cli

NPX Install

Tags

SKILL.md Content

Meta Ads CLI Agent Skill

Highest-priority rules

Recommended agent flow

Install and auth checklist

Using the guard script

Check readiness

Classify command risk without executing

Run a read-only command

Run a write after approval

Run an activation after stronger approval

Lint or run a multi-step plan

Fast task routing

Output expectations

References in this skill