Meta ad builder
Turn a finished creative — typically the output of a generative-AI skill in this
workspace — into a live Meta ad. The skill covers three phases: research
(optional) → copy → deploy. It talks to the Meta Marketing API directly
via ported, parameterized Python scripts.
Meta credentials required before any deploy work. Run
bash scripts/check-meta-env.sh first — before uploading a creative, before
creating anything in the ad account, before the first Meta call of any phase.
On a non-zero exit, stop and ask the user for what it printed. It has already
uncommented the two required lines in .env and opened the file, so the ask
is "paste these two values", not "go find the docs". Read its Live-app warning
out to them: a development-mode app passes every check and then fails at ad
creation. Until the check passes, nothing is uploaded, no partial ad or
creative exists and nothing is charged — which is exactly why it runs first,
since a deploy that dies halfway orphans uploaded assets in a live ad account.
This key is deliberately lazy: the pack asks for it here, at the moment
someone wants to publish, and never during setup.
When to use this skill
Trigger on phrases like:
- "deploy this video to Meta" / "publish this as a Facebook ad"
- "build/launch a Meta ad" / "push this creative into <ad set>"
- "create a Meta ad with this image and copy"
- "pull my top-performing ads" / "what are my best ads by ROAS"
- "research competitor ads" / "pull <brand>'s ads from the Ad Library"
Do not use this skill to generate creative — that's pixar-ad,
claymation-ad, chatgpt-image-ad, nano-banana-image-ad,
generate-youtube-thumbnail, etc. Do not use it to write ad-table rows. This
skill is the direct Meta Marketing API deployment step.
Read order
- This file — workflow, decision tree, safety rules.
- prompting/copy-guide.md — the 5-body / 5-title /
3-description frameworks and the
--copy-file JSON shape.
- reference/deploy-patterns.md — creative
spec mechanics, video polling, retry, failure modes.
- reference/meta-api-cheatsheet.md — the
full Meta Marketing API reference (campaigns, ad sets, ads, enums, gotchas,
Ad Library). Consult as needed; don't read end-to-end.
Prerequisites
REST key required. A Novoads MCP connector is not a substitute. If
NOVOADS_API_KEY is missing or still the placeholder, stop before any
generation work and tell the user: "Before continuing, create an API key at
https://novoads.ai/dashboard/settings?tab=api and paste it into .env."
That holds even when mcp__novoads__* tools are connected and authenticated in
the session. Never call mcp__novoads__* tools from this repo's workflows: they
are a different surface with different behavior, including the units they quote
costs in. Repo installs verify with ./scripts/check-novoads-env.sh; a solo
install checks NOVOADS_API_KEY in the environment.
Pack version. Every /v1 response carries X-Novoads-Pack-Version; mention a newer pack at https://github.com/novoads/agent-skills only when that header names a version NEWER than this file's metadata.packVersion — equal or older is nothing to say, and it is never a reason to stop.
The Meta app must be published (Live) — check this first
A development-mode app cannot create ad creatives. POST /act_*/ads fails
with code 100 / subcode 1885183 ("Ads creative post was created by an app
that is in development mode"). Every other prerequisite can be perfect and the
deploy still cannot succeed.
Allowlisting the ad account under App settings → Advanced → Authorized ad
account IDs does not work around it — tested live on 2026-08-03 and it
does not help. Publishing the app is the only fix: App Dashboard → toggle the
app from Development to Live.
No Graph endpoint reports app mode for a user token, so check-meta-env.sh
cannot test this for you. Ask the user to confirm the app is Live before the
first deploy against a given app.
Everything else
-
Env (in .env — see your repo's .env.example):
META_ACCESS_TOKEN (required) — long-lived token with ads_management scopeMETA_AD_ACCOUNT_ID (required) — with or without the act_ prefixMETA_PAGE_ID, META_IG_USER_ID, META_PIXEL_ID (optional defaults for deploy)META_API_VERSION (optional, default v23.0)
-
Python deps — install into a virtualenv:
python3 -m venv .venv-meta
.venv-meta/bin/python -m pip install -r scripts/requirements.txt
# then run the scripts with .venv-meta/bin/python, not bare python3
Bare python3 -m pip install fails on a Homebrew python with
error: externally-managed-environment (PEP 668), and macOS is this repo's
first target. Do not suggest --break-system-packages; use the venv.
-
A target ad set that already exists. The skill deploys ads into an existing
ad set — it does not create campaigns or ad sets. If the user needs a new ad
set, create it in Ads Manager or via the cheatsheet §3–§4 first.
-
The finished creative on disk — an image or video file path. Chat-pasted
files are not accessible; ask the user for a real path.
Run bash scripts/check-meta-env.sh to verify credentials before anything else.
It checks the token, the ads_management scope, ad-account reachability and the
Page — a token that passes /me but carries no ads scopes is a real failure mode
it now catches.
When credentials are missing it sets the user up rather than only complaining.
It uncomments the two required lines in .env (they ship commented out, and a
token typed onto a commented line fails the next run identically — the most
likely way this path breaks in practice), opens the file, and prints where each
value comes from plus the Live-app warning. Relay what it printed; it is written
to be read out. It leaves the four optional keys commented, never touches a line
the user has already edited, and exits 1 either way.
Workflow
Phase 1 — Research (optional, when copy should model winners)
# Rank the account's ads and pull the winning copy
python scripts/pull-top-ads.py --date-preset last_30d --min-spend 100 --limit 15
# Pull a competitor's ads from the Ad Library
python scripts/pull-competitor-ads.py --pages "BrandName" --limit 50
Both write JSON under OUTPUT_BASE (or ./outputs/meta-ads/). Read the top-ad
copy fields to identify winning hook/proof/CTA patterns before writing new copy.
Phase 2 — Copy
Write a copy.json following copy-guide.md:
5 bodies (one per framework angle), 5 titles, 3 descriptions. If Phase 1 ran,
mirror the voice and patterns of the winners — new creative + proven copy DNA.
Save copy.json somewhere under outputs/ so it isn't committed.
Phase 3 — Deploy
Always dry-run first — it prints the creative payload in full
(no truncation) plus a dedicated Advantage+ enhancement section, and makes no
API calls:
.venv-meta/bin/python scripts/deploy-ad.py --dry-run \
--adset-id <AD_SET_ID> --copy-file copy.json --link <DESTINATION_URL> \
--image path/to/creative.png
Review the payload with the user, then deploy for real:
.venv-meta/bin/python scripts/deploy-ad.py \
--adset-id <AD_SET_ID> --copy-file copy.json --link <DESTINATION_URL> \
--video clip-a.mp4 --video clip-b.mp4 --cta SIGN_UP --pixel-id <PIXEL_ID>
--image / --video are repeatable — each becomes its own ad in the ad set.- Every ad is created PAUSED. Tell the user to review and un-pause in Meta
Ads Manager. The skill never launches a spending ad automatically.
- Results are written to
deployment_results.json under OUTPUT_BASE:
ads (created), failures (each with the verbatim Meta error), orphans,
and a summary count.
Read the exit code
deploy-ad.py exits 1 if any requested ad failed, and prints each failure
with Meta's own code / subcode / message / fbtrace_id. It no longer prints a
DONE. line on a run that created nothing. If you are wrapping this script,
branch on the exit code — do not parse stdout for success.
Advantage+ enhancements and burned-in captions
The dry run lists every degrees_of_freedom_spec enrollment Meta will apply,
with a one-line note on what each one does to a shipped creative. Read that
section aloud to the user before a first deploy — several enrollments modify
the creative, and the defaults are opt-in.
By default the script sets --burned-in-captions, which forces to OPT_OUT
the enrollments that would deface a creative with text baked into the pixels
(video_uncrop, video_auto_crop, video_filtering, creative_stickers,
reveal_details_over_time, show_summary, show_destination_blurbs, and the
text_extraction customizations) plus text_translation, which rewrites copy
the user approved verbatim. Everything this workspace produces carries burned-in
text — captions on video from caption-video, typography on images from the
image-ad skills — so this is the right default here.
Pass --no-burned-in-captions to send Meta's full enrollment instead. Say so
explicitly when you do; it is the user's creative that gets modified.
Decision tree
| User intent | Phases |
|---|
| "Deploy this creative to Meta" + copy provided | Phase 3 only |
| "Build a Meta ad, write the copy too" | Phase 2 → 3 |
| "Make ads modeled on my winners" | Phase 1 → 2 → 3 |
| "What are my best ads / competitor research" | Phase 1 only |
Safety rules
- Ads deploy PAUSED. Never add an
--active override or un-pause ads without
an explicit user instruction. Confirm the user knows the ads are paused.
- Dry-run before every real deploy. Show the payload; get a go-ahead.
- Confirm the target ad set and destination URL with the user before
deploying — an ad in the wrong ad set spends against the wrong budget.
- Deploying ads is a shared-state, money-adjacent action. Treat the live
deploy-ad.py run as something to confirm, not assume.
- The skill creates ads only — it does not create or edit campaigns, ad sets,
budgets, or audiences. Those stay manual.
Quirks and pitfalls
-
App in development mode → code 100 / subcode 1885183. See Prerequisites.
This is the single most likely reason a first deploy fails.
-
Video processing is async. deploy-ad.py polls the uploaded video until
Meta finishes processing before creating the ad — a video deploy can take a
few minutes. See deploy-patterns.md.
-
Transient OAuthException (code 2). Retried automatically with backoff.
-
act_ prefix is added automatically if missing from META_AD_ACCOUNT_ID.
-
A failed run can leave uploaded assets behind. The video/image upload
succeeds before ad creation is attempted, so a rejected ad orphans the asset.
deploy-ad.py prints every orphan with a ready-to-run curl cleanup line and
records them under orphans in deployment_results.json. It does not
delete anything automatically — deleting objects in a live ad account is the
user's call. Offer the cleanup commands; don't run them unprompted.
-
link_urls is sent for image ads only — this is deliberate, not a bug.
build_image_creative puts link_urls in asset_feed_spec;
build_video_creative does not. A live video deploy (2026-08-03) confirmed the
ad resolves its destination correctly without it, carrying the link through
object_story_spec.video_data.call_to_action instead. Leave the asymmetry
alone; it is verified working.
-
TEXT_LIQUIDITY does not read back on the live creative. The skill sends
text_transformation_types: ["TEXT_LIQUIDITY"] and
degrees_of_freedom_type: "USER_ENROLLED", but reading the created creative
back does not show either field (verified 2026-08-03). The functional part
does persist — the 5/5/3 asset feed was present on the live ad. Verify by
asset feed, not by flag:
curl -s -G "https://graph.facebook.com/v23.0/<AD_ID>" \
--data-urlencode "fields=creative{asset_feed_spec,degrees_of_freedom_spec}" \
--data-urlencode "access_token=$META_ACCESS_TOKEN" | python3 -m json.tool
Confirm asset_feed_spec.bodies/titles/descriptions carry the counts you sent.
Do not claim multi-variant text rotation is enabled on the basis of the flag
you sent — say what read back.
-
Account-specific data stays out of git. All output routes through
outputs/ (gitignored): ad IDs, pulled spend/revenue, competitor data.
-
Special Ad Categories (credit, employment, housing, social issues) change
ad-set targeting rules — flag to the user; see cheatsheet §3.5.
Cost note
The Meta Marketing API itself is free to call. Ad spend is real money — but
because every ad deploys PAUSED, nothing spends until the user un-pauses it in
Ads Manager. There are no per-call credits to estimate.