Skill: otman-ai/metaads (version 1.0.0)

# Meta Ads API Skill (Full) ## Overview This skill enables an agent to read, create, and manage Meta (Facebook/Instagram) ad campaigns via the Marketing API. --- ## Base Configuration ### API Base URL ``` https://graph.facebook.com/v19.0/ ``` ### Required Inputs * `access_token` * `ad_account_id` (format: `act_<ID>`) --- ## Authentication ### Method Use access token in query or header: ``` Authorization: Bearer <ACCESS_TOKEN> ``` or ``` ?access_token=<ACCESS_TOKEN> ``` --- ## Permissions Required | Permission | Purpose | | -------------- | ----------------------------- | | ads_read | Read campaigns, ads, insights | | ads_management | Create & update campaigns | --- ## Core Entities * Campaign → Top-level objective * Ad Set → Budget + targeting * Ad → Creative (image/video + copy) --- # READ OPERATIONS (Primary) ## 1. Get Campaigns ### Endpoint ``` GET /act_<AD_ACCOUNT_ID>/campaigns ``` ### Example ``` GET /act_<ID>/campaigns?fields=id,name,status,objective ``` --- ## 2. Get Ad Sets ``` GET /act_<ID>/adsets?fields=id,name,campaign_id,status,daily_budget ``` --- ## 3. Get Ads ``` GET /act_<ID>/ads?fields=id,name,adset_id,status ``` --- ## 4. Campaign Insights ``` GET /<CAMPAIGN_ID>/insights?fields=impressions,clicks,spend,ctr,cpc ``` --- ## 5. Account Insights ``` GET /act_<ID>/insights?fields=impressions,clicks,spend&date_preset=last_7d ``` --- ## 6. Time Range Filtering ``` time_range={'since':'2024-01-01','until':'2024-01-31'} ``` --- ## 7. Status Filtering ``` effective_status=['ACTIVE'] ``` --- ## 8. Levels ``` level=campaign | adset | ad ``` --- ## Pagination Responses include: ``` paging.next ``` ### Agent Rule * Follow `paging.next` until exhausted * Stop at safe limit (e.g., 10 pages) --- # WRITE OPERATIONS ## 9. Create Campaign ``` POST /act_<ID>/campaigns ``` Payload: ``` name=My Campaign objective=CONVERSIONS status=PAUSED special_ad_categories=[] ``` --- ## 10. Create Ad Set ``` POST /act_<ID>/adsets ``` Payload: ``` name=Ad Set 1 daily_budget=1000 billing_event=IMPRESSIONS optimization_goal=REACH campaign_id=<CAMPAIGN_ID> targeting={"geo_locations":{"countries":["MA"]}} status=PAUSED ``` --- ## 11. Create Ad Creative ``` POST /act_<ID>/adcreatives ``` Payload: ``` name=Creative 1 object_story_spec={"page_id":"<PAGE_ID>","link_data":{"message":"Hello","link":"https://example.com"}} ``` --- ## 12. Create Ad ``` POST /act_<ID>/ads ``` Payload: ``` name=Ad 1 adset_id=<ADSET_ID> creative={"creative_id":"<CREATIVE_ID>"} status=PAUSED ``` --- ## 13. Update Campaign Status ``` POST /<CAMPAIGN_ID>?status=PAUSED ``` --- # INSIGHTS METRICS Common fields: * impressions * clicks * spend * ctr * cpc * conversions (if configured) --- # ERROR HANDLING | Code | Meaning | | ---- | --------------------- | | 190 | Invalid/expired token | | 200 | Permission denied | | 100 | Invalid parameter | --- # RATE LIMITS * Respect HTTP 429 * Retry with exponential backoff * Batch requests when possible --- # AGENT RULES (IMPORTANT) ## Safety * Always create campaigns as `PAUSED` * Never expose access tokens * Validate all IDs before use ## Efficiency * Cache campaign lists * Avoid duplicate API calls * Use insights endpoints instead of raw data when possible ## Reliability * Retry failed requests (max 3) * Log all API responses * Detect empty responses --- # ANALYTICS LOGIC (Agent Intelligence) ## Detect Poor Performance * High spend + low CTR → flag * High CPC → recommend pause ## Detect Winners * High CTR + low CPC → scale budget ## Example Rule ``` IF spend > 50 AND ctr < 0.5% THEN mark campaign as underperforming ``` --- # SAMPLE REQUEST FLOW 1. Fetch campaigns 2. Fetch insights 3. Analyze metrics 4. Decide action 5. Update campaign (pause/scale) --- # BEST PRACTICES * Use long-lived tokens * Prefer system users (Business Manager) * Monitor token expiration * Use versioned API (v19.0+) --- # NOTES * Insights are delayed (not real-time) * Conversion tracking requires Pixel or CAPI * Some features require app review ---


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)