Autonomous Meta Ads Agent

An AI-powered pipeline that autonomously generates, deploys, and optimizes Meta (Facebook/Instagram) ads using Claude Code skills. From creative generation to daily optimization — fully automated.

Works for any business. Run /ad-setup and it walks you through everything.

What It Does

• Scrapes your website for ad content (value props, testimonials, pricing)
• Monitors competitor ads via Meta Ad Library and generates counter-positioning
• Generates UGC-style video ads (fal.ai / Kling v3 Pro) and static image ads (Gemini Imagen 4)
• Deploys ads to your Meta Ads account with a proven 3-campaign structure
• Optimizes daily: pauses underperformers, scales winners, detects creative fatigue
• Sends daily performance briefings via Slack

How the Ads Work

This system uses a proven Meta Ads structure that separates testing from scaling:

Your Account
├── Prospecting Campaign (60-70% of budget)
│   Find new customers. Only proven creatives run here.
│   Meta's algorithm optimizes delivery automatically.
│
├── Retargeting Campaign (15-25% of budget)
│   Convert people who already visited your site or watched your videos.
│   Smaller audience, higher conversion rate.
│
└── Testing Campaign (10-15% of budget)
    Test new creatives in isolation (1 creative per ad set).
    Winners get promoted to Prospecting. Losers get paused.

Why this works: Testing in isolation prevents unproven creatives from disrupting your winning campaigns. Budget follows performance — not guesswork.

Quick Start

/ad-setup

That's it. The setup skill walks you through everything interactively:

1. Your business info and pricing
2. API keys (Meta, fal.ai, Gemini)
3. Brand config (colors, voice, personas, competitors)
4. Verification that everything connects

Then it hands you off to the next skill. Each skill recommends what to run next:

/ad-setup → /ad-scrape → /ad-strategy → /ad-monitor → /ad-ideas → /ad-generate → /ad-deploy → /ad-manager

Prerequisites

• Claude Code (CLI, VS Code extension, or Desktop app)
• A Meta Ads account (see "Getting Meta API Access" below)
• fal.ai account for video generation (fal.ai) — free tier available
• Gemini API key for image generation (aistudio.google.com) — free tier available

Installation

# 1. Clone the repo
git clone https://github.com/yourusername/social-ad-generator
cd social-ad-generator

# 2. Install Python dependencies
pip install fal-client mlx-whisper Pillow

# 3. Install ffmpeg (required for video stitching and captions)
# macOS:
brew install ffmpeg
# Ubuntu/Debian:
sudo apt-get install ffmpeg
# Windows: Download from https://ffmpeg.org/download.html

# 4. Copy example config files
cp .env.example .env
cp .mcp.json.example .mcp.json
cp brand/brand.example.json brand/brand.json
cp brand/config.example.json brand/config.json

# 5. Open in Claude Code and run:
/ad-setup

Getting Meta API Access

If you've never used the Meta Ads API, here's how to get started:

1. Create a Meta Developer Account

• Go to developers.facebook.com
• Click "Get Started" and follow the prompts (free)
• You need a personal Facebook account to create a developer account

2. Create an App

• Go to developers.facebook.com/apps
• Click "Create App" → select "Other" → select "Business"
• Give it a name (e.g., "My Ads Automation")

3. Add the Marketing API

• In your app dashboard, click "Add Product"
• Find "Marketing API" and click "Set Up"

4. Get Your Access Token

• Go to developers.facebook.com/tools/explorer
• Select your app from the dropdown
• Click "Generate Access Token"
• Grant these permissions when prompted:
  • ads_management — create and manage ads
  • ads_read — read ad performance data
  • pages_read_engagement — read page data for ad creatives
  • pages_manage_ads — create ads linked to your page

5. Get a Long-Lived Token

• Short-lived tokens expire in 1 hour — you need a long-lived token (60 days)
• In the Access Token Tool, click "Get Long-Lived Token"
• Copy this token — you'll paste it during /ad-setup

6. What You'll Need

After setup, you'll have these (all collected during /ad-setup):

• Access Token — the long-lived token from step 5
• Ad Account ID — /ad-setup will list your accounts and let you pick
• Page ID — /ad-setup will list your pages and let you pick
• Pixel ID — /ad-setup will find your pixel (or tell you how to create one)

Don't worry about finding these manually — /ad-setup automates the discovery.

Skills (11 total)

Onboarding Flow (run once, in order)

Skill	What it does
/ad-setup	First-time onboarding — collects API keys, business info, creates config files
/ad-scrape	Scrapes your website for value props, testimonials, features, pricing
/ad-strategy	Designs your Meta Ads account structure (campaigns, ad sets, budgets, audiences)
/ad-monitor	Scans competitor ads via Meta Ad Library, generates counter-positioning briefs
/ad-ideas	Generates creative concepts — UGC video scripts, shot lists, messaging angles
/ad-generate	Produces video ads (Kling v3 Pro) and static images (Gemini Imagen 4)
/ad-deploy	Deploys creatives to your Meta account (all created as PAUSED for review)

Daily Operations (automated)

Skill	What it does
/ad-manager	Orchestrator — runs the full pipeline daily via /schedule
/ad-optimize	Pauses losers, scales winners, promotes test winners, detects fatigue
/ad-report	Generates daily/weekly performance briefings, sends to Slack
/caption	Burns social-media-style word-by-word captions onto video ads

How Skills Work

Every skill is interactive — it asks questions one at a time, explains its reasoning, and gets your approval before taking action. No silent changes.

• In interactive mode (you run the skill manually): Skills present recommendations with selectable options, explain WHY, and wait for your approval.
• In automated mode (via /ad-manager on a schedule): Skills execute using your config, log all decisions, and surface findings in the daily report.
• Escape hatches: If you say "just do it", skills use smart defaults and proceed without asking.

Architecture

brand/brand.json          ← Your brand config (personas, competitors, voice)
brand/config.json         ← Runtime config (budgets, thresholds, targeting)
brand/content.json        ← Scraped website content (auto-generated)
brand/competitors.json    ← Competitor intelligence (auto-generated)
brand/ad-ideas.json       ← Creative concepts (auto-generated)
brand/creatives/          ← Generated video + image ads (auto-generated)
state.json                ← Campaign state (IDs, optimization log, flags)
.mcp.json                 ← MCP server config (Meta Ads API, Gemini)

Skills communicate through shared files. /ad-monitor writes creative briefs that /ad-ideas reads. /ad-optimize sets flags that /ad-manager checks. /ad-report reads the optimization log.

Daily Automation

Once set up, schedule the pipeline to run daily:

/schedule create --name "ads-daily" --cron "0 9 * * *" --prompt "/ad-manager"

The manager runs: optimize → generate (if needed) → deploy (if needed) → monitor (weekly) → report.

Troubleshooting

Meta API Issues

"Invalid Access Token"

• Tokens expire after 60 days. Regenerate at developers.facebook.com/tools/explorer
• Get a new long-lived token and update .mcp.json

"No Ad Accounts Found"

• Create an ad account at business.facebook.com
• Link it to your developer app
• Wait a few minutes for propagation, then retry

"Pixel Has Never Fired"

• Install the Meta Pixel on your website first
• Verify at facebook.com/events_manager
• The system starts with a warmup phase (Landing Page Views) that doesn't require pixel events

Video Generation Issues

"ModuleNotFoundError: No module named 'fal_client'"

pip install fal-client

fal.ai rate limit errors

• The system staggers requests with 2-second delays
• If you still hit limits, wait 60 seconds and retry
• Consider upgrading your fal.ai plan for higher limits

ffmpeg not found

# macOS
brew install ffmpeg
# Ubuntu/Debian
sudo apt-get install ffmpeg

General Issues

Skills don't appear in Claude Code

• Make sure you're in the project directory
• The skills folder must be at skills/mikla-ads/ relative to the project root
• Restart Claude Code if you just cloned the repo

Config validation fails during /ad-setup

• Make sure you copied all example files (step 4 of Installation)
• Check that .env and .mcp.json have your real API keys, not the placeholder values

"BLOCKED" status from any skill

• Read the REASON and RECOMMENDATION in the output
• Most blocks are due to expired tokens or missing config
• Run /ad-setup again to re-verify your setup

Contributing

PRs welcome. The skill files are in skills/mikla-ads/*/SKILL.md — each is a self-contained Claude Code skill definition.

To add a new skill:

1. Create a directory under skills/mikla-ads/
2. Add a SKILL.md with frontmatter (name, description, allowed-tools)
3. Follow the Interaction Protocol pattern from existing skills
4. Add a "What's Next" handoff section

License

MIT — see LICENSE