agentleFS
Sign inStart free
SyneroSynero/meta-ads-analyzer/SKILL.md

meta-ads-analyzer

Skill9 starsChanged 5 months agoMITView on GitHub

Analyze Facebook/Instagram Ads campaigns via the Meta Marketing API from any AI agent or shell automation.

  • Reads credentials

6 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions6 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 6

    1. athina-ai/goose-skills★ 1.3ksame name
    2. gooseworks-ai/goose-skills★ 1.3ksame name
    3. mathiaschu/meta-ads-analyzer★ 428same name
    4. Eugenevdm01/eugenes-meta-agent★ 4same name
    5. TehseenTech/manus-skills★ 0same name
    6. Tommyvr7/meta-ads-analyzer★ 0same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

The file

We split this skill into the rules it gives an agent

5 rules. 0 are common, 3 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 6 edited versions we read keep these.

  • 3

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use this skill when a user asks an AI agent to inspect Facebook/Instagram Ads campaign performance, active campaigns, spend, CTR, CPC, CPM, …

    line 10
  2. Very specific:

    If Meta deprecates the pinned version, the API returns an error naming it.

    line 40
  3. Distinctive:

    All commands return JSON.

    line 51
  4. Distinctive:

    Do not expose raw access tokens or private account IDs in logs.

    line 70
  5. Very specific:

    If the CLI returns status: error, report the error and suggest the smallest fix.

    line 71

“Common” is measured: kept by at least 6 in 10 of the 6 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Meta Ads Analyzer

Use this skill when a user asks an AI agent to inspect Facebook/Instagram Ads campaign performance, active campaigns, spend, CTR, CPC, CPM, leads, or messaging conversations.

The project is read-only. It does not create, edit, pause, or delete campaigns.

Setup

git clone https://github.com/Synero/meta-ads-analyzer.git
cd meta-ads-analyzer

export META_ACCESS_TOKEN="your_meta_access_token"
export META_ACCOUNT_ID="act_123456789"

bash setup.sh

Required Meta permissions usually include:

  • ads_read
  • ads_management if the user's Meta app/account flow requires it

API version

The default is Graph API v26.0. Pin another version per environment or per call when a workflow needs it:

export META_API_VERSION=v25.0
node meta-ads-cli.js testConnection --apiVersion=v25.0

If Meta deprecates the pinned version, the API returns an error naming it; bump META_API_VERSION or upgrade the CLI instead of retrying.

Commands

./meta-ads.sh test
./meta-ads.sh campaigns
./meta-ads.sh insights
./meta-ads.sh insights --datePreset=last_7d

All commands return JSON.

Intent mapping

User intentCommandAnalysis focus
“How are my campaigns doing?”./meta-ads.sh insightsSpend, CTR, CPC, CPM, conversions
“Which campaigns are active?”./meta-ads.sh campaignsstatus === ACTIVE
“Which campaign is cheapest?”./meta-ads.sh insightsCompare CPC/CPM against objective
“How many leads/conversations?”./meta-ads.sh insightsInspect actions array
“Is my API connected?”./meta-ads.sh testToken and account connectivity

Output handling

When summarizing results:

  1. State the date preset used.
  2. Compare campaigns by objective-relevant metrics.
  3. Mention Meta's reporting delay.
  4. Do not expose raw access tokens or private account IDs in logs.
  5. If the CLI returns status: error, report the error and suggest the smallest fix.

Metrics reference

  • spend: amount spent in the selected period.
  • impressions: total ad impressions.
  • reach: unique accounts reached.
  • clicks: click/interactions count from Meta.
  • ctr: click-through rate.
  • cpc: cost per click.
  • cpm: cost per thousand impressions.
  • actions: conversion events such as leads or messaging conversations.

Basic heuristics:

  • CTR below 1%: review creative, audience, or offer.
  • CTR above 2%: usually healthy, depending on vertical.
  • Frequency above 3: watch for fatigue if available.
  • CPC/CPM must be interpreted relative to objective and market.

Troubleshooting

  • META_ACCESS_TOKEN is required: set the token in the environment.
  • Permission denied: the app/token probably lacks ads permissions or account access.
  • Account not found: check that META_ACCOUNT_ID starts with act_ and belongs to the token's accessible accounts.
  • Empty insights: check date preset, campaign delivery, attribution windows, and Meta reporting delays.

Files

  • meta-ads.sh: shell wrapper for agents.
  • meta-ads-cli.js: zero-dependency Node.js CLI (also importable as a module).
  • setup.sh: local setup and syntax checks.
  • test/: offline suite against a fake Graph API server; run with npm test.
  • .env.example: credential template.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free