# Meta Ad Builder

> Publica creativos terminados como anuncios en vivo de Meta (Facebook/Instagram) vía la Meta Marketing API, más investigación y apoyo de copy. Sube imagen o video y crea un anuncio en PAUSA en un ad set existente.

Fuente: https://skillsagentes.com/skills/krusemediallc/arcads-claude-code/meta-ad-builder
Markdown: https://skillsagentes.com/skills/krusemediallc/arcads-claude-code/meta-ad-builder.md

Repositorio: https://github.com/krusemediallc/arcads-claude-code
Autor: krusemediallc
Licencia: MIT
Actualizado: hace 2 meses
Coste de contexto: 166 tok instalada, 1.7k tok al activarse, 22.4k tok con todos los archivos del bundle
Bundle: 10 archivos, 87 KB
Permisos que pide: ninguno declarado

## Instalación

Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina.

```bash
# Claude Code
npx -y skills add krusemediallc/arcads-claude-code --skill meta-ad-builder --agent claude-code
# Cursor
npx -y skills add krusemediallc/arcads-claude-code --skill meta-ad-builder --agent cursor
# Codex
npx -y skills add krusemediallc/arcads-claude-code --skill meta-ad-builder --agent codex
# Gemini CLI
npx -y skills add krusemediallc/arcads-claude-code --skill meta-ad-builder --agent gemini
# Windsurf
npx -y skills add krusemediallc/arcads-claude-code --skill meta-ad-builder --agent windsurf
# Cline
npx -y skills add krusemediallc/arcads-claude-code --skill meta-ad-builder --agent cline
```

## Qué hace

- Sube una imagen o video terminado y crea un anuncio PAUSADO en un ad set existente vía la Meta Marketing API; nunca crea campañas ni ad sets nuevos
- Extrae los anuncios de mejor ROAS de la cuenta y anuncios de competidores desde el Ad Library para inspirar el copy antes de escribirlo
- Escribe el copy siguiendo un framework fijo (5 bodies, 5 titles, 3 descriptions) y siempre hace un dry-run que muestra el payload completo antes de desplegar de verdad
- Nunca lanza un anuncio activo por su cuenta: todo anuncio se crea en pausa y el usuario debe reactivarlo manualmente en Ads Manager

## Cuándo usarla

- El usuario pide 'deploy this video to Meta', 'publish this as a Facebook ad', 'pull my top ads' o investigar anuncios de un competidor

## Cuándo no

- No genera el creativo (usa las skills de imagen/video) ni escribe filas de AdTable/Airtable (usa adtable-light)

## Qué la activa

- "Publica este video como anuncio de Meta"
- "Dame mis anuncios con mejor ROAS del último mes"
- "Investiga los anuncios de este competidor en el Ad Library"

## Antes de instalar

- Requiere `META_ACCESS_TOKEN` y `META_AD_ACCOUNT_ID` en `.env`, las dependencias Python del repo, y un ad set ya existente donde publicar.
- Necesita en el PATH: curl, git, python
- Variables de entorno: API_VERSION, ENV_FILE, META_ACCESS_TOKEN, META_AD_ACCOUNT_ID, META_API_VERSION, META_IG_USER_ID, META_PAGE_ID, META_PIXEL_ID, OUTPUT_BASE, SCRIPT_DIR
- makes network requests
- needs API credentials

## Archivos

- SKILL.md — 7 KB
- prompting/copy-guide.md — 4 KB
- reference/deploy-patterns.md — 5 KB
- reference/meta-api-cheatsheet.md — 40 KB
- scripts/check-meta-env.sh — 2 KB
- scripts/deploy-ad.py — 10 KB
- scripts/lib/meta_api.py — 6 KB
- scripts/pull-competitor-ads.py — 7 KB
- scripts/pull-top-ads.py — 7 KB
- scripts/requirements.txt — 146 B

## SKILL.md

Reproducido tal cual desde krusemediallc/arcads-claude-code bajo MIT. Esta sección es el documento original y está en inglés.

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

## 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-style-ad`,
`claymation-ad`, `generate-youtube-thumbnail`, `uni1-image-ad`, etc. Do not use
it to write AdTable/Airtable rows — that's `adtable-light`. This skill is the
*direct Meta Marketing API* deployment step.

## Read order

1. **This file** — workflow, decision tree, safety rules.
2. **[prompting/copy-guide.md](prompting/copy-guide.md)** — the 5-body / 5-title /
   3-description frameworks and the `--copy-file` JSON shape.
3. **[reference/deploy-patterns.md](reference/deploy-patterns.md)** — creative
   spec mechanics, video polling, retry, failure modes.
4. **[reference/meta-api-cheatsheet.md](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

- **Env** (in `.env` — see your repo's `.env.example`):
  - `META_ACCESS_TOKEN` (required) — long-lived token with `ads_management` scope
  - `META_AD_ACCOUNT_ID` (required) — with or without the `act_` prefix
  - `META_PAGE_ID`, `META_IG_USER_ID`, `META_PIXEL_ID` (optional defaults for deploy)
  - `META_API_VERSION` (optional, default `v23.0`)
- **Python deps:** `python3 -m pip install -r scripts/requirements.txt`
- **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.

## Workflow

### Phase 1 — Research (optional, when copy should model winners)

```bash
# 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](prompting/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 full creative payload, makes no API calls:

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

```bash
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 (ad IDs) are written to `deployment_results.json` under `OUTPUT_BASE`.

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

- **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](reference/deploy-patterns.md).
- **Transient `OAuthException` (code 2).** Retried automatically with backoff.
- **`act_` prefix** is added automatically if missing from `META_AD_ACCOUNT_ID`.
- **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.

## Dónde encaja

- Categoría: [Marketing](https://skillsagentes.com/categorias/marketing.md) — Campañas, copy, lanzamientos y ciclos de crecimiento.
- Creador: [krusemediallc](https://skillsagentes.com/creators/krusemediallc.md) — 8 skills en el directorio
- [Todas las skills](https://skillsagentes.com/skills.md)
- [Ranking de instalaciones](https://skillsagentes.com/ranking.md)

## Otras skills del mismo repositorio

- [Arcads External Api](https://skillsagentes.com/skills/krusemediallc/arcads-claude-code/arcads-external-api.md): Crea y consulta assets de video e imagen con IA vía la API externa de Arcads (Seedance 2.0, Sora 2, Veo 3.1, Kling, Grok Video, Nano Banana, b-roll, escenas, guiones/actores), con guía de prompting y espera hasta que cada asset esté listo.
- [Chatgpt Image Ad](https://skillsagentes.com/skills/krusemediallc/arcads-claude-code/chatgpt-image-ad.md): Genera creativos de imagen para anuncios de Meta con ChatGPT Image 2 (gpt-image-2) vía la API de Arcads. Fija el modelo, elimina chrome de plataforma automáticamente y aplica layouts y texto a prueba de bordes.
- [Nano Banana Image Ad](https://skillsagentes.com/skills/krusemediallc/arcads-claude-code/nano-banana-image-ad.md): Genera creativos de imagen para anuncios de Meta con Nano Banana 2 / Nano Banana Pro (familia Gemini Flash Image) vía la API de Arcads. Fija la familia de modelo, elimina chrome de plataforma y aplica layouts a prueba de bordes.
- [Image Ad Clone](https://skillsagentes.com/skills/krusemediallc/arcads-claude-code/image-ad-clone.md): Convierte un anuncio de imagen existente en una plantilla de prompt reutilizable, validándola al regenerarla vía Arcads con ChatGPT Image 2 o Nano Banana. La plantilla se añade a la librería compartida de 37+ plantillas.
- [Generate Youtube Thumbnail](https://skillsagentes.com/skills/krusemediallc/arcads-claude-code/generate-youtube-thumbnail.md): Genera miniaturas de YouTube de alto CTR con Nano Banana 2 vía la API de Arcads: sube imágenes de referencia, cuida la fidelidad de parecido del personaje, usa fórmulas probadas por CTR y genera en lote.

## Skills relacionadas

- [Marketing Council](https://skillsagentes.com/skills/coreyhaines31/marketingskills/marketing-council.md): Consejo simulado de asesores de marketing legendarios (Godin, Ogilvy, Schwartz, Dunford, Sutherland, Hormozi, Sharp y más) que aplican sus frameworks, muestran desacuerdos y sintetizan una recomendación.
- [Ad Creative](https://skillsagentes.com/skills/coreyhaines31/marketingskills/ad-creative.md): Úsalo para generar, iterar o escalar creatividad publicitaria —titulares, descripciones, texto primario o variaciones completas— en cualquier plataforma de pago.
- [Influencer Marketing](https://skillsagentes.com/skills/coreyhaines31/marketingskills/influencer-marketing.md): Para ejecutar partnerships de influencers, creators o embajadores: encontrar y vetar socios, estructurar tratos, redactar briefs, cumplir disclosure y medir el ROI real.
- [Public Relations](https://skillsagentes.com/skills/coreyhaines31/marketingskills/public-relations.md): Para pedir ayuda con relaciones públicas, earned media, cobertura de prensa, pitching a periodistas o estrategia de medios (no pull requests).
- [Revops](https://skillsagentes.com/skills/coreyhaines31/marketingskills/revops.md): Úsalo para revenue operations, gestión del ciclo de vida de leads y procesos de handoff entre marketing y sales, incluyendo scoring, routing, pipeline y CRM automation.

---

Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)