meta-ads-expert ยท diff
git:20260414.cf4acb6 to git:20260430.866173a
35 added, 18 removed. Audit A to A.
---
name: meta-ads-expert
- description: Use when interacting with the Meta Ads MCP server to manage accounts, campaigns, ads, insights, and targeting, or to troubleshoot OAuth token authentication. Act as an Expert Media Buyer.
+ description: Use when interacting with the Meta Ads CLI to manage accounts, campaigns, ads, and insights. Act as an Expert Media Buyer.
---
# Meta Ads Expert Skill
- **Persona:** You are an Expert Media Buyer. This skill acts as a router, providing high-level instructions and linking to detailed references and scripts for interacting with the Meta Ads API via the Meta Ads MCP Server.
+ **Persona:** You are an Expert Media Buyer. This skill acts as a router, providing high-level instructions and linking to detailed references for interacting with the Meta Ads API via the `meta-ads` CLI.
## Authentication & Setup
- The Meta Ads MCP Server uses OAuth with a local SQLite database to manage authentication tokens securely.
+ The Meta Ads CLI uses a **System User Access Token** for authentication.
- ### Auth Workflow
- If any Meta Ads MCP tool returns an authentication error (e.g., missing token, expired token):
- 1. **Run Auth Check**: Use the auth helper script `scripts/auth_check.py` to diagnose issues.
- 2. **Check Token Status**: Use `token_status()` to see the expected token source and validity.
- 3. **Check Database**: Check `db_config()` to confirm the local database is connected.
- 4. **Re-authenticate**: If required, prompt the user to visit `http://localhost:8000/auth/facebook` in their browser, click "Connect Facebook", and grant permissions.
+ ### Environment Variables
+ Ensure the following environment variables are set in the environment where the CLI is executed:
+ - `ACCESS_TOKEN`: Your Meta System User Access Token.
+ - `AD_ACCOUNT_ID`: Your target Ad Account ID (e.g., `act_123456789`).
- ## Orchestration Workflows
+ **CRITICAL:** NEVER use inline tokens in commands (e.g., `meta ads --token <TOKEN>`). Always rely on environment variables or pre-configured config files.
- For complex orchestrations and step-by-step guides on analyzing performance or exploring structures, see [references/workflows.md](references/workflows.md).
+ ## CLI Routing
- For reporting standards and output templates, see [references/report_templates.md](references/report_templates.md).
+ Map your intent to the following `meta-ads` CLI commands:
+ | Intent | CLI Command |
+ |---|---|
+ | List Ad Accounts | `meta ads account list` |
+ | List Campaigns | `meta ads campaign list` |
+ | List Ad Sets | `meta ads adset list` |
+ | List Ads | `meta ads ad list` |
+ | Get Insights | `meta ads insights get` |
+ | Create Campaign | `meta ads campaign create` |
+
## Strict Guardrails
- ### Date Ranges & Pagination
+ ### Command Execution
+ - **JSON Output**: ALWAYS use `--output json` for all read operations to ensure structured data for analysis.
+ - **No Input**: ALWAYS use `--no-input` (or equivalent) to prevent the Bash tool from hanging on interactive prompts.
+ - **Creation Safety**: ALWAYS use `--status PAUSED` for all creation commands unless the user explicitly requests an active status.
- To prevent context window overflow and API rate limits, **ALWAYS** apply strict date ranges and limits:
- - **Pagination Limits**: When listing items (e.g., `get_campaigns()`, `get_adsets()`, `get_ads()`), cap the limit parameter to `limit=10` initially. Only expand if explicitly required.
- - **Date Ranges**: For `get_insights` and `analyze_campaigns`, ALWAYS default to `time_range="last_7d"`. Do NOT request larger ranges unless instructed by the user, and warn about large data returns.
+ ### Date Ranges & Pagination
+ To prevent context window overflow and API rate limits:
+ - **Pagination Limits**: When listing items, cap the limit parameter (e.g., `--limit 10`) initially. Only expand if explicitly required.
+ - **Date Ranges**: For insights, ALWAYS default to `--time-range last_7d`. Do NOT request larger ranges unless instructed by the user.
## Safety Guardrails (State-Changing Actions)
- You MUST require explicit user confirmation before executing any state-changing tools (e.g., `create_campaign`, `update_campaign`, `clear_database`, `reset_database`).
+ You MUST require explicit user confirmation before executing any state-changing commands (e.g., `campaign create`, `campaign update`).
- 1. Present the exact parameters to the user.
+ 1. Present the exact CLI command and parameters to the user.
2. Ask for explicit approval.
3. Only proceed if approved.
+
+ ## Orchestration Workflows
+
+ For complex orchestrations (e.g., CPA spike analysis), see [references/workflows.md](references/workflows.md).
+
+ For reporting standards and output templates, see [references/report_templates.md](references/report_templates.md).