Skill: sebclawops/openclaw-meta-ads (version 1.0.0)

--- name: openclaw-meta-ads description: Shared Meta Ads skill for OpenClaw agents. Analyze Meta (Facebook and Instagram) ad accounts, campaigns, ad sets, ads, insights, and lead-form data with a production-safe read-first workflow. Use when an agent needs Meta Ads reporting, account audits, creative or audience diagnostics, lead-form review, or recommendations before live ad changes. Require explicit approval before any write action. --- # OpenClaw Meta Ads Use this skill for Meta Ads work across agents. This is a shared skill, not a Poseidon-only skill. Keep account-specific tokens, account IDs, and business rules outside the core skill. ## Use this skill for - account and campaign performance reporting - insights analysis - campaign, ad set, and ad diagnostics - lead-form and lead pipeline review - creative and audience review - structured recommendations before live changes ## Default stance Start read-only. Analyze first, recommend second, change last. Do not make live Meta Ads changes without explicit approval. ## Access model Meta account access is agent-specific. The skill is shared, but each agent should use its own token, account ID, and permissions. If credentials or permissions are missing, stop and fix access before pretending the skill can do real work. ## Setup and references Read only what you need: - `references/api-setup.md` for token, permission, and connection basics - `references/account-structure.md` for campaign, ad set, ad, creative, insights, and leads structure - `references/insights-queries.md` for common query patterns - `references/audit-workflows.md` for practical review flows - `references/optimization.md` for optimization heuristics and common mistakes - `references/browser-fallback.md` only when API access is unavailable or UI confirmation is explicitly needed ## Safety rules - never expose tokens or secrets in files or chat - prefer read-only analysis before any operational change - require explicit approval for pausing, enabling, editing, budget changes, or creative changes - treat optimization guidance as heuristic, not universal truth - scrub lead data for PII before broader reasoning when needed ## Output style Lead with findings and recommended actions. Keep reports practical: - what is happening - what looks wrong - what to check next - what to change, if approved

path: README.md
content: # openclaw-meta-ads

Shared Meta Ads skill for OpenClaw agents.

## Goal

Give agents a practical, production-safe way to analyze Meta Ads accounts, inspect campaign structure, review performance, audit lead flow, and recommend improvements without mixing in account-specific business rules.

## What this skill does well

- account and campaign reporting
- insights analysis
- audit workflows
- lead-form review
- creative and audience diagnostics
- optimization guidance grounded in practical heuristics

## What this skill is not

- a Poseidon-only skill
- a replacement for business-specific campaign strategy docs
- a license to make live account changes without approval
- a place to store tokens or account secrets

## Structure

```text
openclaw-meta-ads/
├── SKILL.md
├── README.md
├── references/
│   ├── api-setup.md
│   ├── account-structure.md
│   ├── insights-queries.md
│   ├── audit-workflows.md
│   ├── optimization.md
│   └── browser-fallback.md
└── scripts/
    ├── get_account_info.py
    ├── get_campaigns.py
    ├── get_insights.py
    └── get_leads.py
```

## Practical use order

1. verify token, account ID, and permissions
2. run read-only account or insights queries
3. audit the area in question
4. recommend actions
5. only make live changes with explicit approval

## Notes

- Keep account-specific learnings in the relevant agent or project docs.
- Keep the shared skill general.
- This v1 is intentionally docs-first. Add scripts later only when the API calls are stable and worth standardizing.
- If API access is unavailable, use the browser fallback only when explicitly needed.


path: references/account-structure.md
content: # Account Structure

## Core hierarchy

Meta Ads usually works like this:

1. Ad Account
2. Campaign
3. Ad Set
4. Ad
5. Creative

## What each layer usually controls

### Ad Account
- overall billing and access context
- top-level reporting
- account-wide lists of campaigns, ad sets, ads, creatives, and forms

### Campaign
- objective
- top-level budget in some setups
- broad directional strategy

### Ad Set
- audience
- placements
- optimization goal
- schedule
- budget in many setups

### Ad
- final delivery object
- creative attachment
- copy and call to action

### Creative
- image, video, text, headline, destination, CTA

### Insights
- performance metrics at account, campaign, ad set, or ad level
- common fields: spend, impressions, clicks, ctr, cpc, cpm, reach, frequency, actions, cost_per_action_type

### Lead Forms and Leads
- instant forms can generate leads directly in Meta
- lead data is often sensitive and may also sync downstream into systems like HubSpot

## Common confusion points

- campaign objective does not tell the whole optimization story
- ad set choices often drive audience and delivery more than campaign labels do
- good CTR does not guarantee good lead quality
- lead count does not guarantee pipeline value
- attribution and reporting windows can distort apparent winners and losers


path: references/api-setup.md
content: # API Setup

## Access model

Meta Ads access is account-specific.
Each agent that uses this skill should have its own token, account ID, and permissions.

## Typical credentials

- `META_ADS_API_KEY` or equivalent bearer token
- account ID in `act_<id>` format when calling the Graph API

## Permissions

Common permissions include:
- `ads_read` for reporting and insights
- `ads_management` for live changes
- lead access permissions for form lead retrieval where applicable

## Credential handling

Do not store tokens in tracked files or workspace notes.
Use the approved secure credential workflow for the environment and expose tokens to the runtime through approved environment injection only.

## Connection basics

Before doing meaningful work, confirm:
- token is present
- token has the right scopes
- correct ad account is selected
- expected endpoints respond without permission errors

## Important notes

- Meta Graph API versions change over time. Keep examples current when updating the skill.
- Read access and write access are not the same thing.
- Some insights or lead endpoints may fail without the right combination of ad account, page, app, or business permissions.


path: references/audit-workflows.md
content: # Audit Workflows

## 1. Account health check

Start with:
- last 30 day account insights
- active campaign list
- major trend changes in spend, clicks, leads, and cost per result

Look for:
- spend rising faster than leads or qualified actions
- campaigns delivering but not producing useful downstream outcomes
- obvious account underdelivery
- active campaigns with stale creatives or weak CTR

## 2. Wasted spend review

Check:
- campaigns with meaningful spend and weak results
- ad sets spending without quality actions
- ads with weak CTR or poor downstream performance
- placements or audiences consuming spend inefficiently

## 3. Lead quality and lead flow review

Check:
- which forms are producing leads
- whether lead volume lines up with downstream CRM results
- whether one campaign is flooding low-quality leads
- whether lead routing and sync are still intact

## 4. Creative fatigue review

Check:
- repeated high spend on the same creative with declining CTR
- weak engagement compared to sister ads in the same ad set
- any quality or ranking indicators that suggest the ad is stale or mismatched

## 5. Before recommending changes

Separate findings into:
- clear problem
- likely cause
- recommended next step
- change that needs explicit approval

Keep reports practical and short.


path: references/browser-fallback.md
content: # Browser Fallback

Use this only when:
- API access is unavailable
- the user explicitly wants UI confirmation
- a specific setting or workflow is easier to verify in Meta Ads Manager

## Default stance

Prefer API-based reporting and repeatable analysis.
Use the browser for confirmation, screenshots, or UI-only checks.

## Basic workflow

1. Open Meta Ads Manager in the approved browser context.
2. Confirm the correct business and ad account are selected.
3. Navigate to the relevant area:
   - campaigns
   - ad sets
   - ads
   - reports
   - instant forms or leads
4. Snapshot the visible data.
5. Report findings clearly.

## Cautions

- Wrong account or date range makes Meta UI analysis unreliable fast.
- Confirm attribution view and date range before drawing conclusions.
- Do not make live UI changes without explicit approval.


path: references/insights-queries.md
content: # Insights and Query Patterns

Use these as practical starting points.
Adapt fields and breakdowns to the actual endpoint and permissions available.

## Account-level reporting

Fetch:
- spend
- impressions
- reach
- clicks
- ctr
- cpc
- cpm
- actions
- cost_per_action_type

Use this for:
- quick performance summary
- last 7, 30, or 90 day review
- headline trend checks

## Campaign-level review

Fetch campaign identity plus insights for:
- objective
- status
- spend
- clicks
- ctr
- cpc
- leads or relevant actions
- cost per result

Use this for:
- top and bottom performer review
- wasted spend review
- scale or pause recommendations

## Ad set review

Fetch:
- audience or targeting summary
- optimization goal
- budget
- delivery status
- spend
- click and result metrics

Use this for:
- audience comparison
- placement or targeting issues
- weak delivery diagnostics

## Ad and creative review

Fetch:
- ad name and status
- creative identifiers
- spend
- impressions
- ctr
- cost per result
- quality or ranking metrics when available

Use this for:
- creative fatigue checks
- winner and loser identification
- ad-level troubleshooting

## Breakdown ideas

Useful breakdowns may include:
- age
- gender
- region or country
- publisher platform
- platform position
- device platform
- daily increments

## Lead retrieval

When lead forms are in play:
- identify the relevant form IDs
- retrieve leads carefully
- treat lead payloads as potentially sensitive
- prefer minimal necessary fields when analyzing quality or flow


path: references/optimization.md
content: # Optimization Heuristics

Use these as practical rules of thumb, not as universal truth.

## Structure

- Keep campaign goals clear. Mixed intent makes diagnosis harder.
- Ad sets usually control the real delivery logic, so weak performance often lives there.
- Separate testing from scaling when possible.

## Creative

- Good Meta performance often depends more on creative freshness than small targeting tweaks.
- High frequency with falling CTR is a fatigue warning.
- Strong click performance can still hide poor lead quality.

## Audience

- Broad audiences can work well, but only if creative and conversion signals are strong.
- Narrow audiences can protect relevance but choke delivery.
- Audience overlap can hide where spend is really being wasted.

## Budget and scaling

- Sudden budget jumps can destabilize delivery.
- Scale winners deliberately, not emotionally.
- A campaign can look efficient at low spend and fall apart when scaled.

## Measurement

- Cost per lead is not the same as cost per qualified lead.
- Attribution windows and view-through behavior can make performance look better or worse than business reality.
- Always compare platform results with downstream CRM outcomes when possible.

## Lead generation

- Cheap leads are not always good leads.
- Form friction that is too low can flood junk.
- Lead quality issues are often funnel issues, not just ad issues.


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