metaads

Workflow Routing (SYSTEM PROMPT)

CRITICAL: Route to the correct workflow based on user intent.

When user needs to set up or configure Meta Ads API access: Examples: "set up meta ads", "connect meta ads", "configure facebook ads", "my token expired", "meta ads setup", credential errors from --check -> READ: ~/.claude/skills/MetaAds/workflows/Setup.md -> EXECUTE: Walk user through complete setup (Business Manager, App, token, .env)

When user wants to publish, create, or launch a campaign: Examples: "publish ads", "create campaign", "launch campaign", "upload ad images", "publish meta ads", "push this campaign to Meta", "create ad set" -> READ: ~/.claude/skills/MetaAds/workflows/PublishCampaign.md -> EXECUTE: Campaign publishing workflow -> If credentials fail, route to Setup.md first

When user wants to check performance, metrics, or analyze results: Examples: "check meta ad performance", "ROAS", "which ad is winning", "ad spend", "campaign metrics", "how are my ads doing", "audience breakdown", "creative performance" -> READ: ~/.claude/skills/MetaAds/workflows/AnalyzePerformance.md -> EXECUTE: Performance analysis workflow -> If credentials fail, route to Setup.md first

When user wants to manage campaigns (pause/resume/status): Examples: "pause campaign", "resume campaign", "campaign status", "list campaigns" -> Use uv run ~/.claude/skills/MetaAds/tools/Publish.py directly with --pause, --resume, --status, or --list

When to Activate This Skill

Setup & Configuration (Category 0)

• "set up meta ads", "connect meta ads API", "configure facebook ads"
• "meta ads setup", "how do I connect my ad account"
• "my token expired", "token error", "can't access meta ads"
• "refresh my meta token", "renew access token"
• Any credential error from --check

Campaign Publishing (Category 1)

• "publish ads", "create campaign", "launch campaign"
• "push this to Meta", "set up the campaign", "upload ad images"
• "publish meta ads", "create ad set", "build the campaign"
• "publish this campaign config", "go live with the ads"

Performance Analysis (Category 2)

• "check meta ad performance", "how are my ads doing"
• "ROAS", "return on ad spend", "ad spend", "ad metrics"
• "which ad is winning", "best performing ad"
• "campaign metrics", "ad set performance", "creative performance"
• "audience breakdown", "age/gender breakdown"
• "CTR", "CPC", "CPM", "CPA", "cost per acquisition"

Campaign Management (Category 3)

• "pause campaign", "resume campaign", "activate campaign"
• "campaign status", "list campaigns", "show my campaigns"

Core Capabilities

Guided Setup:

• Complete walkthrough: Business Manager -> Developer App -> Token -> .env
• Two token paths: System User (never expires) or User Token (60-day, with automated refresh)
• Token exchange automation (agent runs the curl command)
• Pixel setup guidance for conversion tracking
• Error diagnosis with specific fixes for every common failure

Campaign Publishing:

• Upload images from local directories to Meta
• Create full campaign hierarchy (campaign -> ad set -> creative -> ad)
• Advantage+ flexible creative with multiple images/texts/headlines
• All objects created PAUSED for manual review
• JSON config-driven for reproducible campaigns

Performance Analytics:

• Account-level summary with DTC benchmarks (CTR, CPM, CPA, ROAS)
• Campaign, ad set, and ad-level metrics
• Daily trend analysis for campaign deep dives
• Audience breakdowns (age, gender, platform, device)
• Data sync to Analytics/meta-ads/ for cross-channel analysis
• CSV export for spreadsheet analysis

Campaign Management:

• List all campaigns with status
• View campaign hierarchy (campaign -> ad sets -> ads)
• Pause/resume campaigns

Scripts

| Script | Purpose | |--------|---------| | tools/Publish.py | Campaign creation, image upload, pause/resume | | tools/Analytics.py | Performance metrics, breakdowns, sync, export |

Both scripts use PEP 723 inline dependencies — just run with uv run directly from the skill directory. No install or copy step needed.

Usage

Run scripts directly from the skill directory. They load .env from the current working directory (Path.cwd()), so run them from your project root:

# From your project root (where .env lives):
uv run ~/.claude/skills/MetaAds/tools/Publish.py --check
uv run ~/.claude/skills/MetaAds/tools/Analytics.py --summary

Prerequisites: uv must be installed. If not: curl -LsSf https://astral.sh/uv/install.sh | sh

Environment Variables (.env): | Variable | Required | Description | |----------|----------|-------------| | META_ADS_ACCESS_TOKEN | Yes | System User or long-lived User token | | META_ADS_ACCOUNT_ID | Yes | Ad account ID with act_ prefix | | FACEBOOK_APP_ID | For refresh | App ID for token exchange | | FACEBOOK_APP_SECRET | For refresh | App Secret for token exchange |

Campaign Objective Reference

Use these objectives in campaign configs:

| Objective | When to Use | Optimization Goal | |-----------|-------------|-------------------| | OUTCOME_SALES | DTC purchases, Shopify conversions | OFFSITE_CONVERSIONS | | OUTCOME_LEADS | Lead gen, email signups, quiz funnels | LEAD_GENERATION | | OUTCOME_TRAFFIC | Landing page visits, blog traffic | LINK_CLICKS | | OUTCOME_AWARENESS | Brand awareness, video views | REACH or IMPRESSIONS | | OUTCOME_ENGAGEMENT | Post engagement, page likes | POST_ENGAGEMENT |

Campaign Config Template

Generic template for any DTC brand:

{
  "campaign": {
    "name": "campaign-name-month-year",
    "objective": "OUTCOME_SALES"
  },
  "adsets": [
    {
      "name": "Broad-25-54-US",
      "daily_budget": 5000,
      "targeting": {
        "age_min": 25,
        "age_max": 54,
        "genders": [0],
        "geo_locations": {"countries": ["US"]},
        "publisher_platforms": ["facebook", "instagram"],
        "facebook_positions": ["feed", "video_feeds", "story", "reels"],
        "instagram_positions": ["stream", "story", "reels", "explore"]
      },
      "optimization_goal": "OFFSITE_CONVERSIONS",
      "bid_strategy": "LOWEST_COST_WITHOUT_CAP"
    }
  ],
  "creative": {
    "images_directory": "./path/to/ad-images/",
    "primary_texts": [
      "Primary text variant 1 — lead with the hook or pain point",
      "Primary text variant 2 — lead with the benefit or social proof",
      "Primary text variant 3 — lead with a comparison or price anchor"
    ],
    "headlines": [
      "Short Punchy Headline",
      "Benefit-Driven Headline",
      "Price/Value Headline"
    ],
    "descriptions": [
      "Supporting description with key differentiator"
    ],
    "link_url": "https://yoursite.com/landing-page",
    "url_parameters": "utm_source=meta&utm_medium=paid-social&utm_campaign=campaign-name&utm_content={{ad.name}}",
    "call_to_action_type": "SHOP_NOW"
  }
}

Config notes:

• daily_budget is in cents (5000 = $50.00/day)
• genders: 0 = all, 1 = male, 2 = female
• {{ad.name}} is a Meta dynamic parameter — auto-fills with the ad name
• call_to_action_type options: SHOP_NOW, LEARN_MORE, SIGN_UP, GET_OFFER, ORDER_NOW, SUBSCRIBE, BOOK_NOW

DTC Benchmark Reference

| Metric | Good | OK | Needs Work | What It Means | |--------|------|----|------------|---------------| | CTR | >1.5% | 1-1.5% | <1% | % of impressions that click. Low = creative isn't resonating | | CPM | <$15 | $15-25 | >$25 | Cost per 1000 impressions. High = competitive auction or narrow audience | | CPC | <$1 | $1-2 | >$2 | Cost per click. High = low CTR driving up costs | | CPA | <$30 | $30-50 | >$50 | Cost per purchase. The ultimate efficiency metric | | ROAS | >3x | 2-3x | <2x | Revenue per $1 spent. Below 2x usually means losing money after COGS | | Frequency | 1-3 | 3-5 | >5 | Avg times each person saw the ad. High = ad fatigue | | Hook Rate | >25% | 15-25% | <1