Meta Safe Campaign Builder

Use this skill when building or resuming a Meta Ads campaign programmatically, especially for purchase, lead generation, challenge ticket, webinar, or event campaigns where all new objects must remain PAUSED until QA is complete. This skill is designed for performance-marketing execution, not generic API experimentation.

Safety Rules

Always default to paused-only creation. Never activate campaigns, ad sets, or ads without explicit user confirmation. Treat API tokens, ad account IDs, page IDs, pixel IDs, and Instagram actor IDs as sensitive operational data. Save tokens only in local protected files or environment variables, never in final reports.

Before creating anything, verify the account, page, pixel, event, landing page, budget, naming convention, audience, and CTA. If any critical requirement is missing, ask for clarification instead of guessing. If an API call partially succeeds, resume from the existing object IDs rather than creating duplicates.

Required Inputs

Collect or confirm the following before write calls.

Standard Workflow

1. Load Relevant Skills and Instructions

Read meta-ads-analyzer before analysis or Meta MCP/API work. If the campaign is for a challenge, webinar, ticket, or launch event, also read the relevant challenge/operator skill if available. Check local AGENTS.md files before editing or running project files.

2. Validate Token and Inspect Assets

Validate the token before creating objects. Confirm at minimum that the token can access /me, the ad account, campaigns, pixels, pages, and Instagram actors. Confirm that the user has write access for ads_management. Save a sanitized validation result to a JSON file.

Use this validation to select the correct pixel, page, Instagram identity, and prior campaign setup to mirror. Do not assume asset IDs from memory when inspection is possible.

3. Prepare a Payload Preview

Before write calls, create a payload preview JSON that excludes the token and shows every intended object as PAUSED. Include campaign, ad set, creative, ad, video, thumbnail, promoted object, targeting, attribution, URL, and copy.

Do not proceed if the preview has any active status or missing conversion event. If using ad-set-level budget, put budget and bid strategy at ad set level; avoid conflicting campaign-level bid strategy settings.

4. Create Campaign Infrastructure Paused

Create the campaign with status=PAUSED. Create the ad set with status=PAUSED, the correct daily budget, optimization_goal, billing_event, promoted object, attribution spec, and targeting. Confirm both objects by reading status and effective_status immediately after creation.

If campaign creation succeeds but ad set creation fails, write a resume script that uses the existing campaign ID. Do not rerun full creation in a way that duplicates the campaign.

5. Upload Video Reliably

For large or MOV/MP4 assets, prefer Meta's chunked video upload flow against graph-video.facebook.com using upload_phase=start, repeated transfer, and finish. Save every offset response. After finish, query safe fields such as id,title,status,created_time. Avoid unsupported fields that may trigger false failures.

If a video creative requires a thumbnail, extract a frame with ffmpeg and upload it to /act_{ad_account_id}/adimages. Store the returned image_hash. Use image_hash or image_url in video_data; otherwise Meta may reject the creative.

6. Create Creative and Ad Paused

Create the ad creative with an object_story_spec that contains the correct page_id, instagram_user_id, video_data or link_data, CTA, destination URL, and copy. Then create the ad with status=PAUSED and attach it to the existing ad set.

If Meta returns a blocker, stop and diagnose. Common blockers include app development mode, missing thumbnail, rate limits, invalid page/Instagram actor, policy review limitations, and video not yet processed. Do not keep retrying the same failed request more than three times.

7. QA Before Handover

Verify all created delivery objects through read calls. Minimum QA fields are id, name, status, effective_status, configured_status, daily_budget, promoted_object, targeting, attribution_spec, creative, and video status. If Meta returns rate limits, record that explicitly and avoid further repeated calls.

Confirm whether any ad exists. If no ad exists because creative creation failed, state that clearly. If an ad exists, confirm it is PAUSED before handover.

8. Deliver Handover

Write a concise Markdown handover containing created object IDs, status, campaign configuration, creative copy, QA notes, blockers, and exact next actions. Attach the handover and key JSON QA files. Do not include access tokens.

Blocker Handling

Performance-Marketing Guardrails

Build campaigns for business outcomes, not cheap traffic. For purchase campaigns, keep the conversion event aligned with the funnel offer and ensure ad copy, landing page, checkout, thank-you page, and follow-up sequence match the promise. After launch, monitor cost per purchase, purchase quality, landing-page view rate, checkout completion, and downstream buyer quality.

Reusable Resources

Read references/meta_api_payload_patterns.md when building the payload or script structure. Use templates/handover_template.md when preparing the final delivery report.

Completion Criteria

A task using this skill is complete only when one of these is true: the campaign, ad set, creative, and ad are created and confirmed PAUSED; or the exact blocker is documented with existing object IDs, no accidental activation, and a safe manual or API continuation path.