meta-ads

name	meta-ads
description	Use when the user wants to automate Meta Ads (Facebook/Instagram) — creating campaigns, pulling insights, uploading creatives, scaling budgets, or debugging API errors. Enforces production-safe patterns from the Meta Ads API Field Guide — PAUSED-by-default creation, rate-limit header monitoring, learning-phase-aware scaling, and v24/v25 deprecation awareness.

Meta Ads — Production-Safe Automation Skill

This skill loads the operational discipline from the Meta Ads API Field Guide so Claude doesn't hallucinate deprecated fields, blow past rate limits, or accidentally trigger learning-phase resets.

When to use

Trigger this skill for ANY Meta Ads API work:

• Creating campaigns, ad sets, ads, or creatives
• Pulling insights / building reports
• Scaling budgets / managing active campaigns
• Debugging API errors (code 10, 17, 190, 1487225, etc.)
• Cross-account creative transfers
• CAPI / server-side event setup

Do NOT trigger for pure Ads Manager UI questions, CRO strategy, or non-API marketing advice.

Hard rules (never violate)

1. PAUSED by default. Every campaign, ad set, and ad created via API must have status: "PAUSED". User activates manually after review. → Field Guide: Pre-Campaign Checklist

2. Write operations require confirmation. Before any create/update/delete, show the user what will be written and wait for explicit approval. Read-only (get_*, list_*) is free.

3. Attribution from donor, literally. When copying a campaign, copy attribution_spec exactly from the donor. Never "upgrade" 1d_click → 7d_click. → Pitfall 1

4. Rate limit: stop on error, don't retry. On code 17, 613, or subcode 80004, read X-Business-Use-Case-Usage.estimated_time_to_regain_access and sleep. Do NOT retry immediately. → Rate Limits

5. Cross-account = checklist first. Image hashes, page IDs, pixel IDs, audience IDs are all account-scoped. Never reuse across accounts without substitution. → Cross-Account Ops

6. Incremental > rebuild. If > 50% of target objects already exist correctly, add the missing ones. Don't delete and recreate. → Pitfall 14

7. Budget changes: max 4/hour per ad set, ≤ 20% increments. Error subcode 1487225 = budget change limit. > 20% = learning phase reset. → Budgets & Learning Phase

8. v24-compliant fields always. Use instagram_user_id (not instagram_actor_id), excluded_custom_audiences top-level (not exclusions.custom_audiences), ODAE objectives (OUTCOME_* not CONVERSIONS/LINK_CLICKS). → Deprecations 2026

9. BigQuery/warehouse > live API for historical analysis. Deleted creatives don't appear in API listings. Warehouse has full history.

10. Document new errors. Encountered an error code not in Error Codes? Add it to project's lessons.md after the fix is verified.

Workflow for campaign creation (RSIV)

Every new campaign follows four phases. Never skip.

Phase 1: Research

• Which ad account, objective, budget, audience?
• Does a template exist? (check project's campaign templates)
• What creative assets are ready? Are files local?
• Donor campaign — read targeting, attribution_spec, promoted_object literally.

Phase 2: Synthesis (user confirmation gate)

Present to user:

• Campaign name (with numbering)
• Structure: N ad sets × M ads each
• Budget + bid strategy
• Key targeting details
• Attribution spec
• Status: PAUSED

Wait for explicit "yes" before Phase 3.

Phase 3: Implementation

• Upload assets if needed (copy to /tmp/ if paths have parens/spaces)
• Batch API for adset+ads creation where possible
• time.sleep(0.3) between batches
• Monitor X-Business-Use-Case-Usage every 10 calls

Phase 4: Verification

• Count: expected N campaigns, M ad sets, K ads
• Read effective_status (not just status) — IN_PROCESS means not live yet
• Visual preview of at least one ad (the cross-account hash silent-break bug)
• Confirm non-zero estimated audience on each ad set
• Log IDs

Common error quick-fixes

Code	Fix
17 — User request limit	Sleep estimated_time_to_regain_access min, don't retry
10, subcode 1341012 — No permission to profile	page_id or instagram_user_id not in token scope
100, subcode 1815508 — Invalid Instagram position	Remove explicit placements, let Advantage+ pick
100, subcode 1487225 — Budget change limit	4/hour max — wait 60 min
100, subcode 1487534 — Insights row limit	Narrow date range or remove breakdowns
190 — Token expired	Regenerate system user token

Full table: Error Codes

Claude Code integration tips

• Pair with an MCP server for tool access. Recommended: pipeboard-co/meta-ads-mcp (most mature) or mikusnuz/meta-ads-mcp (135 tools, v25-ready).
• Reference docs on demand. Don't load all field guide pages at once. Load only the page matching the current task (e.g., docs/02-insights-api.md when user asks about insights).
• Ask the user before write operations when MCP exposes them — even though the MCP may not enforce this.
• Use subagents for multi-account work. Delegate per-account audits to parallel subagents.

References (progressive disclosure)

Load these as needed based on task:

Task	Load
Any API write	01-rate-limits.md, 07-pitfalls.md
Campaign creation	05-deprecations-2026.md, checklists/pre-campaign-v24.md
Insights / reporting	02-insights-api.md, 11-breakdown-effect.md
Scaling budgets	03-budgets-and-learning-phase.md
Creative upload	04-creatives-and-dco.md
Cross-account copy	08-cross-account-operations.md, checklists/cross-account.md
Server-side tracking	13-conversions-api.md
Error diagnosis	06-error-codes.md
Tool selection	09-ecosystem-and-tools.md, 12-related-resources.md
Any end-to-end workflow	10-cookbook.md

Anti-patterns (never do these)

• ❌ Loop while cursor.has_next(): cursor.load_next_page() — SDK auto-pagination hits rate limits at ~25 pages
• ❌ Create ads with status: "ACTIVE" directly from script
• ❌ Change ad set budget by > 20% to "scale aggressively"
• ❌ Copy a campaign cross-account and reuse image_hash / page_id / pixel_id without substitution
• ❌ Rebuild 70 ads when 50 exist correctly and 20 are missing
• ❌ Retry on rate-limit errors immediately
• ❌ Use CONVERSIONS / LINK_CLICKS / LEAD_GENERATION objectives (deprecated — use OUTCOME_*)
• ❌ Pass instagram_actor_id (use instagram_user_id)
• ❌ Nest exclusions.custom_audiences (use top-level excluded_custom_audiences)