Agent skill

Meta Ad Builder

by krusemediallc in krusemediallc/arcads-claude-code

Publish finished creatives as live Meta (Facebook/Instagram) ads via the Meta Marketing API, plus research and ad-copy support.

MITAuto-check: notesMarketing & SEO

Install Meta Ad Builder

skills CLI
$ npx skills add krusemediallc/arcads-claude-code --skill meta-ad-builder -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install krusemediallc/arcads-claude-code meta-ad-builder --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/krusemediallc/arcads-claude-code.git skills-src && mkdir -p .claude/skills && cp -r skills-src/shared/skills/meta-ad-builder .claude/skills/meta-ad-builder && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
meta-ad-builder
GitHub stars
1.6k
Token cost
~1.7k tokens
SKILL.md length
725 words
Files
10 (incl. scripts)
Skills in repo
8
Repo updated
First seen
Licence
MIT

At a glance

Publish finished creatives as live Meta (Facebook/Instagram) ads via the Meta Marketing API, plus research and ad-copy support.

  • Works in 3 steps: Research (optional, when copy should… → Copy → Deploy
  • The user asks to deploy / publish / launch a creative as a Meta
  • SKILL.md covers When to use this skill, Read order, Prerequisites and Workflow, plus 4 more sections
  • Runs Python and Shell scripts from its folder; calls python, python3 and bash; needs META_ACCESS_TOKEN

What it does

Meta Ad Builder is an agent skill from krusemediallc/arcads-claude-code. Publish finished creatives as live Meta (Facebook/Instagram) ads via the Meta Marketing API, plus research and ad-copy support. Uploads an image or video, builds a multi-variant TEXTLIQUIDITY creative, and creates a PAUSED ad in an existing ad set. Also pulls top-performing ads (ranked by ROAS) and competitor ads from the Ad Library to inform copy. Use when the user asks to deploy / publish / launch a creative as a Meta or Facebook ad, build a Meta ad, push a video or image into an ad set, pull their top ads, or…

Its SKILL.md is about 1.7k tokens, which your agent loads only when the skill is triggered. The skill folder holds 13 other files, including scripts (for example `prompting/copy-guide.md`, `reference/deploy-patterns.md` and `reference/meta-api-cheatsheet.md`).

It sits in Marketing & SEO, covering Paid advertising and Copywriting. It works with Meta Ads, Airtable, Instagram and Python. The repository describes itself as: Arcads external API: agent skills, prompting library, and Cursor/Claude workspace. The licence is MIT.

When your agent uses it

  • The user asks to deploy / publish / launch a creative as a Meta
  • Build a Meta ad
  • Image into an ad set
  • Pull their top ads

Example prompts

  • “/meta-ad-builder”

Requirements

  • Python 3
  • A Bash shell
  • A credential in META_ACCESS_TOKEN

Workflow steps

3 steps, taken from the step headings in SKILL.md.

  1. Research (optional, when copy should model winners)
  2. Copy
  3. Deploy

What it can do on your machine

Read from SKILL.md and the folder at commit 1263501. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 6 files in scripts/ (Python and Shell), which the agent can run.

    Shell commands in SKILL.md call:

    • python
    • python3
    • bash

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names these keys or tokens, usually read from environment variables:

    • META_ACCESS_TOKEN

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Meta Ad Builder loads about 1.7k tokens when it runs. Until then it costs about 170 tokens; SKILL.md has 725 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~170
When it runs · the whole SKILL.md, loaded when a task matches
~1.7k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check: notes

The automated check noted patterns worth knowing about, such as sudo or a known installer.

  • NoteMentions a .env fileSKILL.md:49
    - **Env** (in `.env` — see your repo's `.env.example`):

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from krusemediallc/arcads-claude-code at commit 1263501, republished under its MIT licence (© krusemediallc). 725 words, ~1,667 tokens.

Download SKILL.mdSave it as .claude/skills/meta-ad-builder/SKILL.md (or your agent's skills folder). This skill also uses 9 other files; get the full folder from GitHub.
name
meta-ad-builder
description
Publish finished creatives as live Meta (Facebook/Instagram) ads via the Meta Marketing API, plus research and ad-copy support. Uploads an image or video, builds a multi-variant TEXT_LIQUIDITY creative, and creates a PAUSED ad in an existing ad set. Also pulls top-performing ads (ranked by ROAS) and competitor ads from the Ad Library to inform copy. Use when the user asks to deploy / publish / launch a creative as a Meta or Facebook ad, build a Meta ad, push a video or image into an ad set, pull their top ads, or research competitor ads. Not for generating creative (use the image/video skills) and not for writing AdTable/Airtable rows (use adtable-light).

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 — the 5-body / 5-title / 3-description frameworks and the --copy-file JSON shape.
  3. reference/deploy-patterns.md — creative spec mechanics, video polling, retry, failure modes.
  4. 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: 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.
Show full SKILL.md (269 more words)Show less

Decision tree

User intentPhases
"Deploy this creative to Meta" + copy providedPhase 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.
  • 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.

© krusemediallc, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 9 other files (scripts) in shared/skills/meta-ad-builder of krusemediallc/arcads-claude-code.

  • SKILL.md
  • prompting/copy-guide.md
  • reference/deploy-patterns.md
  • reference/meta-api-cheatsheet.md
  • scripts/check-meta-env.sh
  • scripts/deploy-ad.py
  • scripts/lib/meta_api.py
  • scripts/pull-competitor-ads.py
  • scripts/pull-top-ads.py
  • scripts/requirements.txt

Open the folder on GitHubat commit 1263501

Compare with similar skills

Meta Ad Builder next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Meta Ad Builder compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Meta Ad Builder this skillkrusemediallc/arcads-claude-code1.6k—~1.7kAutomated safety check: NotesMIT
Memstack Marketing Facebook Adcwinvestments/memstack423—~2.6kAutomated safety check: PassProprietary
Meta Adshoodini/ai-agents-skills282—~4.2kAutomated safety check: NotesNone
Facebook Ads Library Searchbrowser-act/skills6.1k—~2.3kAutomated safety check: PassMIT
Hook MethodologyDV0x/creative-ad-agent120—~3.1kAutomated safety check: PassMIT
Ad Copy Writercognyai/claude-code-marketing-skills104—~595Automated safety check: NotesNone

Similar skills

  • Memstack Marketing Facebook Ad

    cwinvestments/memstack

    A skill your agent uses when the user says 'facebook ad', 'FB ad', 'Meta ad', 'Instagram ad', or needs social media ad copy with targeting, creative direction, and A/B test plans for Meta Ads Manager.

    423 GitHub stars~2.6k tokensUpdated 14 days ago
    Marketing & SEOAuto-check passed
  • Meta Ads

    hoodini/ai-agents-skills

    Pull, analyze, manage, and CREATE Meta ads (Facebook, Instagram, Messenger, Threads, Click-to-WhatsApp) via the Marketing API.

    282 GitHub stars~4.2k tokensUpdated 3 mo ago
    Marketing & SEOAuto-check: notes
  • Facebook Ads Library Search

    browser-act/skills

    Searches Meta Ad Library (Facebook/Instagram/WhatsApp ads) by keyword or Facebook page ID and extracts ad details including creatives, copy, CTA, publisher platforms, spend, impressions, reach…

    6.1k GitHub stars~2.3k tokensUpdated 1 mo ago
    Marketing & SEOAuto-check passed
  • Hook Methodology

    DV0x/creative-ad-agent

    Generates conversion-focused ad copy through research-first extraction.

    120 GitHub stars~3.1k tokensUpdated 1 mo ago
    Marketing & SEOAuto-check passed
  • Ad Copy Writer

    cognyai/claude-code-marketing-skills

    Generate ad copy variations for Google, Meta, and LinkedIn Ads

    104 GitHub stars~595 tokensUpdated 3 mo ago
    Marketing & SEOAuto-check: notes
  • Playbook Ad Library

    growthenginenowoslawski/coldoutboundskills

    Produces a line about what a company is currently advertising on Facebook and Instagram, from the Meta Ad Library.

    753 GitHub stars~6.3k tokensUpdated 5 days ago
    Marketing & SEOAuto-check passed

More from krusemediallc/arcads-claude-code

All 8 skills in this repo
  • Analyze Video

    krusemediallc/arcads-claude-code

    Analyze a reference video and reverse-engineer its style into a reusable Seedance 2.0 prompting template.

    1.6k GitHub stars~4.2k tokensUpdated 18 days ago
    Auto-check passed
  • Chatgpt Image Ad

    krusemediallc/arcads-claude-code

    Generate one or more standalone Meta image-ad creatives via ChatGPT Image 2 (gpt-image-2) through the Arcads external API.

    1.6k GitHub stars~2.7k tokensUpdated 18 days ago
    Auto-check: notes
  • Generate Youtube Thumbnail

    krusemediallc/arcads-claude-code

    Generate high-CTR YouTube thumbnails using Nano Banana 2 via the Arcads external API.

    1.6k GitHub stars~2.4k tokensUpdated 18 days ago
    Auto-check: notes
  • Nano Banana Image Ad

    krusemediallc/arcads-claude-code

    Generate one or more standalone Meta image-ad creatives via Nano Banana 2 / Nano Banana Pro (Gemini Flash Image family) through the Arcads external API.

    1.6k GitHub stars~2.5k tokensUpdated 18 days ago
    Auto-check: notes
  • Image Ad Clone

    krusemediallc/arcads-claude-code

    A skill your agent uses when the user wants to reverse-engineer an existing image ad into a reusable prompt template.

    1.6k GitHub stars~2.4k tokensUpdated 18 days ago
    Auto-check: notes
  • Arcads External API

    krusemediallc/arcads-claude-code

    Creates and retrieves AI video and image-related assets via the Arcads external API (Seedance 2.0, Sora 2, Veo 3.1, Kling, Grok Video, Nano Banana, b-roll, scene, script/actor flows).

    1.6k GitHub stars~8.7k tokensUpdated 18 days ago
    Auto-check: notes

Questions about Meta Ad Builder

What does Meta Ad Builder do?

Publish finished creatives as live Meta (Facebook/Instagram) ads via the Meta Marketing API, plus research and ad-copy support. Meta Ad Builder is an agent skill from krusemediallc/arcads-claude-code. Publish finished creatives as live Meta (Facebook/Instagram) ads via the Meta Marketing API, plus research and ad-copy support.

When should I use Meta Ad Builder?

Meta Ad Builder fits situations like: the user asks to deploy / publish / launch a creative as a Meta; build a Meta ad; image into an ad set; pull their top ads.

How do I install Meta Ad Builder in Claude Code?

Run `npx skills add krusemediallc/arcads-claude-code --skill meta-ad-builder -a claude-code`. Or copy the skill folder (shared/skills/meta-ad-builder in krusemediallc/arcads-claude-code) into .claude/skills/meta-ad-builder in your project. Claude Code loads it when a task matches its description.

How do I install Meta Ad Builder in Codex?

Run `npx skills add krusemediallc/arcads-claude-code --skill meta-ad-builder -a codex`. Or copy the skill folder (shared/skills/meta-ad-builder in krusemediallc/arcads-claude-code) into .agents/skills/meta-ad-builder in your project. Codex loads it when a task matches its description.

Can I use Meta Ad Builder in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add krusemediallc/arcads-claude-code --skill meta-ad-builder -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/meta-ad-builder, .gemini/skills/meta-ad-builder, .github/skills/meta-ad-builder and .opencode/skills/meta-ad-builder in your project.

What does Meta Ad Builder need to run?

Going by SKILL.md and its folder, Meta Ad Builder needs Python and a shell for the scripts in its folder, the command-line tools its instructions call (python, python3 and bash) and credentials named META_ACCESS_TOKEN. Our summary lists: Python 3; A Bash shell; A credential in META_ACCESS_TOKEN.

Does Meta Ad Builder access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Meta Ad Builder safe to install?

Our automated static check of SKILL.md found notes only (mentions a .env file), nothing it rates as a warning. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Meta Ad Builder use?

Meta Ad Builder is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Meta Ad Builder use?

About 1.7k tokens (SKILL.md is roughly 6.7k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Meta Ad Builder?

Skills that share tags, products or a category with Meta Ad Builder: Memstack Marketing Facebook Ad (cwinvestments/memstack, 423 stars), Meta Ads (hoodini/ai-agents-skills, 282 stars), Facebook Ads Library Search (browser-act/skills, 6.1k stars) and Hook Methodology (DV0x/creative-ad-agent, 120 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Meta Ad Builder?

krusemediallc (a GitHub user) maintains it in krusemediallc/arcads-claude-code, which has 1,585 GitHub stars. The repository holds 8 skills in this directory. The repository was last updated on September 22, 2026.

Source: krusemediallc/arcads-claude-code on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.