@opendirectory.dev/skills 0.1.52 → 0.1.53

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendirectory.dev/skills",
-  "version": "0.1.52",
+  "version": "0.1.53",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {

package/registry.json

@@ -203,7 +203,7 @@
   },
   {
     "name": "meta-ads-skill",
-    "description": "Use when interacting with the Meta Ads MCP server to manage accounts, campaigns, ads, insights, and targeting, or to troubleshoot OAuth token authe...",
+    "description": "Use when interacting with the Meta Ads CLI to manage accounts, campaigns, ads, and insights. Act as an Expert Media Buyer.",
     "tags": [],
     "author": "opendirectory",
     "version": "0.0.1",

package/skills/meta-ads-skill/README.md

@@ -28,9 +28,9 @@ https://github.com/user-attachments/assets/ee98a1b5-ebc4-452f-bbfb-c434f2935067
 
 ## Overview
 
-The **Meta Ads Skill** is a comprehensive, production-ready OpenCode skill designed to give LLMs and AI agents expert-level capabilities to orchestrate the [Varnan-Tech Meta Ads MCP Server](https://github.com/Varnan-Tech/Meta-Ads-MCP). 
+The **Meta Ads Skill** is a comprehensive, production-ready  skill designed to give LLMs and AI agents expert-level capabilities to orchestrate the official **Meta Ads Python CLI**.
 
-By using this skill, an agent transforms into an **Expert Media Buyer**. It will know exactly how to safely authenticate, explore ad structures, troubleshoot campaign performance (like CPA spikes), discover new audiences, and format massive Meta APIs JSON payloads into beautiful, readable markdown reports.
+By using this skill, an agent transforms into an **Expert Media Buyer**. It will know exactly how to explore ad structures, troubleshoot campaign performance (like CPA spikes), discover new audiences, and format massive Meta APIs JSON payloads into beautiful, readable markdown reports.
 
 ---
 
@@ -39,63 +39,36 @@ By using this skill, an agent transforms into an **Expert Media Buyer**. It will
 This skill is designed using a **Progressive Disclosure (Hub-and-Spoke)** architecture to maximize context window efficiency:
 
 1. **The Hub (`SKILL.md`)**: The primary entry point. It provides strict guardrails, safety protocols, and the authentication troubleshooting workflow.
-2. **The Spokes (`references/` & `scripts/`)**: 
+2. **The Spokes (`references/`)**: 
    - When you need to perform a specific task (e.g., investigating a CPA spike), read `references/workflows.md` for the exact step-by-step orchestration strategy.
    - When presenting data to the user, read `references/report_templates.md` to strictly follow the required Markdown layout.
-   - **Data Parsing**: Meta Ads JSON responses are massive. *Always* use the provided `scripts/formatters.py` to condense raw JSON from `get_campaigns`, `get_adsets`, or `get_insights` into clean markdown tables before reasoning over them.
 
 ###  Strict Agent Guardrails
 * **Context Protection**: ALWAYS default to `time_range="last_7d"` for insights. ALWAYS use `limit=10` for listing campaigns/adsets initially.
-* **Safety First**: NEVER execute state-changing tools (`create_campaign`, `update_campaign`, `clear_database`, `reset_database`) without explicitly showing the parameters to the user and waiting for their affirmative confirmation.
+* **Safety First**: NEVER execute state-changing tools (`create_campaign`, `update_campaign`) without explicitly showing the parameters to the user and waiting for their affirmative confirmation.
 
 ---
 
-## Installation & Setup of the Meta Ads MCP
+## Installation & Setup
 
-To use this skill, the host machine must have the Varnan-Tech Meta Ads MCP Server installed and running. 
+To use this skill, you must install the official Meta Ads CLI and configure your credentials.
 
-### 1. Prerequisites
-- **Python 3.10+**
-- A **Meta Developer Account** with a configured App.
-
-### 2. Configure the Meta App
-1. Go to the [Facebook Developers Portal](https://developers.facebook.com/).
-2. Create an App and add the **Marketing API** product.
-3. Under the Facebook Login settings, add `http://localhost:8000/auth/facebook/callback` to the **Valid OAuth Redirect URIs**.
-4. Retrieve your **App ID** and **App Secret**.
-
-### 3. Server Setup
-Clone the MCP repository:
+### 1. Install the CLI
+The skill relies on the `meta-ads` Python package:
 ```bash
-git clone https://github.com/Varnan-Tech/Meta-Ads-MCP.git
-cd Meta-Ads-MCP
-pip install -r requirements.txt
+pip install meta-ads
 ```
 
-Create a `.env` file in the root of the MCP server:
-```env
-FB_APP_ID="your_facebook_app_id"
-FB_APP_SECRET="your_facebook_app_secret"
-FB_OAUTH_ENABLED="true"
-FB_REDIRECT_URI="http://localhost:8000/auth/facebook/callback"
-DATABASE_URL="sqlite:///.meta-ads-mcp/oauth.db"
-```
-
----
-
-## Authentication Workflow
-
-The server uses OAuth backed by a local SQLite database to seamlessly pass tokens to the MCP context.
-
-1. **Start the local Auth Server**:
-   ```bash
-   python src/auth/run_web_server.py
-   ```
-2. **Authenticate**: Open `http://localhost:8000/auth/facebook` in your web browser.
-3. **Grant Permissions**: Click "Connect Facebook" and approve the `ads_management`, `ads_read`, and `read_insights` permissions.
-4. **Completion**: The OAuth token is saved securely to the SQLite DB. The agent can now use the MCP tools automatically without needing the token pasted into the prompt.
+### 2. Authentication (System User Token)
+The CLI uses a **System User Access Token** for authentication. 
+1. Generate a System User Token in your [Meta Business Suite](https://business.facebook.com/settings/system-users).
+2. Ensure the token has `ads_management`, `ads_read`, and `read_insights` permissions.
+3. Set the following environment variables on your machine:
 
-*If an agent encounters an Auth Error during operation, it is instructed by this skill to guide the user back through this exact login flow.*
+```bash
+export ACCESS_TOKEN="your_system_user_access_token"
+export AD_ACCOUNT_ID="act_your_ad_account_id"
+```
 
 ---
 
@@ -109,16 +82,12 @@ meta-ads-skill/
  references/
     report_templates.md           # Standardized markdown report structures
     workflows.md                  # Orchestration strategies (e.g., CPA troubleshooting)
- scripts/
-     auth_check.py                 # Diagnostic script for token status
-     formatters.py                 # JSON -> Markdown table utilities
 ```
 
-## Supported Tools (via MCP)
+## Supported Commands
 
-Through the underlying MCP, this skill orchestrates:
-* **Account Management**: `get_ad_accounts()`, `get_account_info()`
-* **Campaigns & Ads**: `get_campaigns()`, `get_adsets()`, `get_ads()`, `create_campaign()`, `update_campaign()`
-* **Analytics**: `get_insights()`, `analyze_campaigns()`
-* **Targeting**: `search_interests()`, `search_demographics()`, `estimate_audience_size()`
-* **Database**: `token_status()`, `clear_database()`, `reset_database()`
+This skill orchestrates the `meta-ads` CLI using a noun-verb structure:
+* **Campaigns**: `meta ads campaign list`, `meta ads campaign create`
+* **Ad Sets**: `meta ads adset list`
+* **Ads**: `meta ads ad list`
+* **Insights**: `meta ads insights get`

package/skills/meta-ads-skill/meta-ads-skill/SKILL.md

@@ -1,41 +1,58 @@
 ---
 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).

package/skills/meta-ads-skill/meta-ads-skill/references/report_templates.md

@@ -1,6 +1,6 @@
 # Meta Ads Report Templates
 
-Use these markdown templates when generating reports and summaries for users.
+Use these markdown templates when generating reports and summaries for users. These templates are designed to be populated using the structured data from the `meta-ads` CLI's JSON output (`--output json`).
 
 ## 1. Executive Summary Template
 
@@ -10,11 +10,12 @@ Use these markdown templates when generating reports and summaries for users.
 ##  Executive Summary
 [2-3 sentences summarizing the overall performance. E.g., "Account performance remained stable this week with a 5% increase in ROAS, primarily driven by the new Retargeting campaign. However, top-of-funnel CPA has started to rise."]
 
-##  Key Metrics
+##  Key Metrics (Source: `meta ads insights get`)
 - **Spend:** $[Amount] ([+/-]% vs previous period)
 - **Revenue/Conversions:** [Amount] ([+/-]% vs previous period)
 - **CPA:** $[Amount] ([+/-]% vs previous period)
 - **ROAS:** [Amount]x ([+/-]% vs previous period)
+- **CTR:** [Amount]% ([+/-]% vs previous period)
 
 ##  Key Findings
 - **Highlight 1:** [E.g., Campaign X is driving 60% of total conversions at a very efficient CPA.]
@@ -35,7 +36,7 @@ Use these markdown templates when generating reports and summaries for users.
 ##  The Issue
 [Briefly state the problem. E.g., "CPA increased from $20 to $35 starting on [Date]."]
 
-##  Root Cause Analysis
+##  Root Cause Analysis (Source: `meta ads insights get --level [level]`)
 - **Campaign Level:** [Identify which campaign(s) caused the spike.]
 - **Ad Set Level:** [Identify specific ad sets. Did a lookalike audience degrade? Did a specific placement get expensive?]
 - **Ad Level:** [Identify ad fatigue, drop in CTR, increase in CPM, or decrease in conversion rate.]

package/skills/meta-ads-skill/meta-ads-skill/references/workflows.md

@@ -1,36 +1,31 @@
 # Meta Ads Workflows
 
-This document outlines complex orchestrations and workflows for common Meta Ads tasks.
+This document outlines complex orchestrations and workflows for common Meta Ads tasks using the `meta-ads` CLI.
 
 ## 1. CPA Spike Troubleshooting
 
 When a client or user asks to investigate a spike in Cost Per Action (CPA), follow this systematic approach:
 
 1. **Account Level Overview**
-   - **Tool:** `get_ad_accounts` (if account ID not provided)
-   - **Tool:** `get_insights` (Level: account)
+   - **Command:** `meta ads insights get --level account --time-range last_30d --output json`
    - **Action:** Look at overall account performance over the last 7, 14, and 30 days to identify when the spike started.
 
 2. **Campaign Breakdown**
-   - **Tool:** `get_campaigns`
-   - **Tool:** `get_insights` (Level: campaign)
+   - **Command:** `meta ads campaign list --output json`
+   - **Command:** `meta ads insights get --level campaign --time-range last_7d --output json`
    - **Action:** Identify which specific campaigns are driving the CPA increase. Compare spend and CPA across active campaigns.
 
 3. **Ad Set Deep Dive**
-   - **Tool:** `get_adsets`
-   - **Tool:** `get_insights` (Level: adset)
+   - **Command:** `meta ads adset list --campaign-id <ID> --output json`
+   - **Command:** `meta ads insights get --level adset --time-range last_7d --output json`
    - **Action:** For the offending campaigns, break down by Ad Set to see if specific audiences or placements are underperforming.
 
 4. **Ad & Creative Analysis**
-   - **Tool:** `get_ads`
-   - **Tool:** `get_insights` (Level: ad)
+   - **Command:** `meta ads ad list --adset-id <ID> --output json`
+   - **Command:** `meta ads insights get --level ad --time-range last_7d --output json`
    - **Action:** Check if specific ads are experiencing ad fatigue (high frequency, dropping CTR) or if recent changes disrupted the learning phase.
 
-5. **Advanced Insights (Optional)**
-   - **Tool:** `analyze_campaigns`
-   - **Action:** Run automated analysis on the specific campaigns to generate actionable recommendations.
-
-6. **Synthesis and Reporting**
+5. **Synthesis and Reporting**
    - Use the `CPA Spike Investigation Report` template (found in `report_templates.md`) to structure the findings and recommendations.
 
 ## 2. New Audience Discovery
@@ -38,7 +33,7 @@ When a client or user asks to investigate a spike in Cost Per Action (CPA), foll
 When a user wants to find new audiences or test new targeting:
 
 1. **Review Current Top Performers**
-   - **Tool:** `get_insights` (Level: adset)
+   - **Command:** `meta ads insights get --level adset --time-range last_30d --output json`
    - **Action:** Identify the ad sets currently delivering the best ROAS/CPA.
 
 2. **Generate Audience Ideas**
@@ -46,6 +41,7 @@ When a user wants to find new audiences or test new targeting:
 
 3. **Structure the Test**
    - Recommend a campaign structure for testing (e.g., A/B testing with Campaign Budget Optimization (CBO) or Ad Set Budget Optimization (ABO)).
+   - **Command Example:** `meta ads campaign create --name "Test_Audience_X" --status PAUSED --no-input`
 
 4. **Monitoring**
    - Provide the exact metrics to watch (e.g., CTR, CPC, early conversions) over the next 3-7 days.