@opendirectory.dev/skills 0.1.51 → 0.1.53
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/registry.json +12 -1
- package/skills/email-newsletter/README.md +98 -0
- package/skills/email-newsletter/SKILL.md +395 -0
- package/skills/email-newsletter/evals/evals.json +35 -0
- package/skills/email-newsletter/references/design-system.md +390 -0
- package/skills/email-newsletter/references/html-email-guide.md +235 -0
- package/skills/email-newsletter/references/platform-compat.md +154 -0
- package/skills/email-newsletter/references/subject-line-formulas.md +207 -0
- package/skills/email-newsletter/templates/dark-newsletter.html +307 -0
- package/skills/email-newsletter/templates/light-newsletter.html +166 -0
- package/skills/meta-ads-skill/README.md +24 -55
- package/skills/meta-ads-skill/meta-ads-skill/SKILL.md +35 -18
- package/skills/meta-ads-skill/meta-ads-skill/references/report_templates.md +4 -3
- package/skills/meta-ads-skill/meta-ads-skill/references/workflows.md +11 -15
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
<!DOCTYPE html>
|
|
2
|
+
<html lang="en">
|
|
3
|
+
<head>
|
|
4
|
+
<meta charset="UTF-8">
|
|
5
|
+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
6
|
+
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
|
7
|
+
<title>[SUBJECT]</title>
|
|
8
|
+
<link href="https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
|
|
9
|
+
<!--[if mso]>
|
|
10
|
+
<noscript><xml><o:OfficeDocumentSettings><o:PixelsPerInch>96</o:PixelsPerInch></o:OfficeDocumentSettings></xml></noscript>
|
|
11
|
+
<![endif]-->
|
|
12
|
+
<style>
|
|
13
|
+
@media only screen and (max-width: 600px) {
|
|
14
|
+
.container { width: 100% !important; }
|
|
15
|
+
.hero-h1 { font-size: 30px !important; }
|
|
16
|
+
.h2 { font-size: 28px !important; }
|
|
17
|
+
.pad { padding-left: 24px !important; padding-right: 24px !important; }
|
|
18
|
+
}
|
|
19
|
+
</style>
|
|
20
|
+
</head>
|
|
21
|
+
<body style="margin:0;padding:0;background-color:#F0F0EE;-webkit-text-size-adjust:100%;-ms-text-size-adjust:100%;">
|
|
22
|
+
|
|
23
|
+
<!-- Preview text -->
|
|
24
|
+
<span style="display:none;max-height:0;overflow:hidden;opacity:0;font-size:1px;color:#F0F0EE;">[PREVIEW TEXT]</span>
|
|
25
|
+
|
|
26
|
+
<table width="100%" cellpadding="0" cellspacing="0" border="0" style="background-color:#F0F0EE;">
|
|
27
|
+
<tr>
|
|
28
|
+
<td align="center" style="padding:32px 16px;">
|
|
29
|
+
|
|
30
|
+
<table class="container" width="600" cellpadding="0" cellspacing="0" border="0" style="max-width:600px;width:100%;background-color:#FFFFFF;">
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
<!-- ══════════════════════════════════════════════════════
|
|
34
|
+
SECTION: HEADER
|
|
35
|
+
═══════════════════════════════════════════════════════ -->
|
|
36
|
+
<tr>
|
|
37
|
+
<td bgcolor="#1A1A1A" style="background-color:#1A1A1A;padding:20px 40px;">
|
|
38
|
+
<table width="100%" cellpadding="0" cellspacing="0" border="0">
|
|
39
|
+
<tr>
|
|
40
|
+
<td style="font-family:'Instrument Serif',Georgia,'Times New Roman',serif;font-size:20px;font-weight:400;color:#FFFFFF;letter-spacing:-0.01em;">[BRAND NAME]</td>
|
|
41
|
+
<td align="right" style="font-family:Inter,Arial,Helvetica,sans-serif;font-size:11px;font-weight:500;color:#888888;letter-spacing:0.14em;text-transform:uppercase;white-space:nowrap;">Issue #[N] | [DATE]</td>
|
|
42
|
+
</tr>
|
|
43
|
+
</table>
|
|
44
|
+
</td>
|
|
45
|
+
</tr>
|
|
46
|
+
|
|
47
|
+
<!-- Brand strip -->
|
|
48
|
+
<tr>
|
|
49
|
+
<td bgcolor="[BRAND_COLOR]" style="background-color:[BRAND_COLOR];height:3px;font-size:1px;line-height:1px;"> </td>
|
|
50
|
+
</tr>
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
<!-- ══════════════════════════════════════════════════════
|
|
54
|
+
SECTION: HERO (light — white bg)
|
|
55
|
+
═══════════════════════════════════════════════════════ -->
|
|
56
|
+
<tr>
|
|
57
|
+
<td class="pad" bgcolor="#FFFFFF" style="background-color:#FFFFFF;padding:56px 40px 48px;">
|
|
58
|
+
<p style="margin:0 0 16px 0;font-family:Inter,Arial,Helvetica,sans-serif;font-size:11px;font-weight:600;color:[BRAND_COLOR];letter-spacing:0.22em;text-transform:uppercase;">[CATEGORY LABEL]</p>
|
|
59
|
+
<h1 class="hero-h1" style="margin:0 0 20px 0;font-family:'Instrument Serif',Georgia,'Times New Roman',serif;font-size:46px;font-weight:400;line-height:1.05;color:#111111;letter-spacing:-0.02em;">[HERO HEADLINE]</h1>
|
|
60
|
+
<p style="margin:0 0 32px 0;font-family:Inter,Arial,Helvetica,sans-serif;font-size:17px;line-height:1.6;color:#666666;">[HERO HOOK]</p>
|
|
61
|
+
<table cellpadding="0" cellspacing="0" border="0">
|
|
62
|
+
<tr>
|
|
63
|
+
<td align="center" bgcolor="#111111" style="background-color:#111111;border-radius:8px;">
|
|
64
|
+
<a href="[CTA_URL]" target="_blank" style="display:inline-block;padding:14px 32px;font-family:Inter,Arial,Helvetica,sans-serif;font-size:15px;font-weight:600;color:#FFFFFF;text-decoration:none;letter-spacing:0.01em;">[CTA BUTTON TEXT] →</a>
|
|
65
|
+
</td>
|
|
66
|
+
</tr>
|
|
67
|
+
</table>
|
|
68
|
+
</td>
|
|
69
|
+
</tr>
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
<!-- ══════════════════════════════════════════════════════
|
|
73
|
+
SECTION: INTRO
|
|
74
|
+
═══════════════════════════════════════════════════════ -->
|
|
75
|
+
<tr>
|
|
76
|
+
<td class="pad" bgcolor="#FFFFFF" style="background-color:#FFFFFF;padding:32px 40px 0;">
|
|
77
|
+
<p style="margin:0;font-family:Inter,Arial,Helvetica,sans-serif;font-size:16px;line-height:1.7;color:#555555;">[INTRO TEXT]</p>
|
|
78
|
+
</td>
|
|
79
|
+
</tr>
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
<!-- DIVIDER -->
|
|
83
|
+
<tr>
|
|
84
|
+
<td bgcolor="#FFFFFF" style="background-color:#FFFFFF;padding:32px 40px 0;">
|
|
85
|
+
<hr style="border:none;border-top:1px solid #EEEEEE;margin:0;">
|
|
86
|
+
</td>
|
|
87
|
+
</tr>
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
<!-- ══════════════════════════════════════════════════════
|
|
91
|
+
SECTION: MAIN CONTENT
|
|
92
|
+
═══════════════════════════════════════════════════════ -->
|
|
93
|
+
<tr>
|
|
94
|
+
<td class="pad" bgcolor="#FFFFFF" style="background-color:#FFFFFF;padding:32px 40px 8px;">
|
|
95
|
+
<p style="margin:0 0 18px 0;font-family:Inter,Arial,Helvetica,sans-serif;font-size:15px;line-height:1.75;color:#444444;"><strong style="color:#111111;font-weight:700;">[BOLD CALLOUT]</strong> [paragraph]</p>
|
|
96
|
+
<p style="margin:0 0 18px 0;font-family:Inter,Arial,Helvetica,sans-serif;font-size:15px;line-height:1.75;color:#444444;"><strong style="color:#111111;font-weight:700;">[BOLD CALLOUT]</strong> [paragraph]</p>
|
|
97
|
+
<p style="margin:0;font-family:Inter,Arial,Helvetica,sans-serif;font-size:15px;line-height:1.75;color:#444444;"><strong style="color:#111111;font-weight:700;">[BOLD CALLOUT]</strong> [paragraph]</p>
|
|
98
|
+
</td>
|
|
99
|
+
</tr>
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
<!-- ══════════════════════════════════════════════════════
|
|
103
|
+
SECTION: STAT CALLOUT (light version)
|
|
104
|
+
═══════════════════════════════════════════════════════ -->
|
|
105
|
+
<tr>
|
|
106
|
+
<td class="pad" bgcolor="#FFFFFF" style="background-color:#FFFFFF;padding:24px 40px;">
|
|
107
|
+
<table width="100%" cellpadding="0" cellspacing="0" border="0">
|
|
108
|
+
<tr>
|
|
109
|
+
<td bgcolor="#F8F8F6" style="background-color:#F8F8F6;border-left:3px solid [BRAND_COLOR];padding:22px 24px;border-radius:0 6px 6px 0;">
|
|
110
|
+
<p style="margin:0 0 8px 0;font-family:'Instrument Serif',Georgia,'Times New Roman',serif;font-size:22px;font-weight:400;line-height:1.3;color:#111111;">"[STAT OR QUOTE]"</p>
|
|
111
|
+
<p style="margin:0;font-family:Inter,Arial,Helvetica,sans-serif;font-size:12px;color:#999999;">[SOURCE]</p>
|
|
112
|
+
</td>
|
|
113
|
+
</tr>
|
|
114
|
+
</table>
|
|
115
|
+
</td>
|
|
116
|
+
</tr>
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
<!-- ══════════════════════════════════════════════════════
|
|
120
|
+
SECTION: CTA CALLOUT CARD (light — dark card)
|
|
121
|
+
═══════════════════════════════════════════════════════ -->
|
|
122
|
+
<tr>
|
|
123
|
+
<td class="pad" bgcolor="#FFFFFF" style="background-color:#FFFFFF;padding:8px 32px 48px;">
|
|
124
|
+
<table width="100%" cellpadding="0" cellspacing="0" border="0">
|
|
125
|
+
<tr>
|
|
126
|
+
<td bgcolor="#111111" style="background-color:#111111;border-radius:12px;padding:48px 40px;text-align:center;">
|
|
127
|
+
<h2 style="margin:0 0 12px 0;font-family:'Instrument Serif',Georgia,'Times New Roman',serif;font-size:36px;font-weight:400;line-height:1.05;color:#F2F2F2;letter-spacing:-0.02em;">[CTA CALLOUT HEADLINE]</h2>
|
|
128
|
+
<p style="margin:0 0 28px 0;font-family:Inter,Arial,Helvetica,sans-serif;font-size:16px;line-height:1.55;color:#AAAAAA;">[CTA CALLOUT BODY]</p>
|
|
129
|
+
<table cellpadding="0" cellspacing="0" border="0" style="margin:0 auto;">
|
|
130
|
+
<tr>
|
|
131
|
+
<td align="center" bgcolor="[BRAND_COLOR]" style="background-color:[BRAND_COLOR];border-radius:8px;">
|
|
132
|
+
<a href="[CTA_URL]" target="_blank" style="display:inline-block;padding:14px 32px;font-family:Inter,Arial,Helvetica,sans-serif;font-size:15px;font-weight:700;color:#0A0A0A;text-decoration:none;">[CTA BUTTON TEXT]</a>
|
|
133
|
+
</td>
|
|
134
|
+
</tr>
|
|
135
|
+
</table>
|
|
136
|
+
</td>
|
|
137
|
+
</tr>
|
|
138
|
+
</table>
|
|
139
|
+
</td>
|
|
140
|
+
</tr>
|
|
141
|
+
|
|
142
|
+
|
|
143
|
+
<!-- ══════════════════════════════════════════════════════
|
|
144
|
+
SECTION: FOOTER (light)
|
|
145
|
+
═══════════════════════════════════════════════════════ -->
|
|
146
|
+
<tr>
|
|
147
|
+
<td bgcolor="#F8F8F6" style="background-color:#F8F8F6;border-top:1px solid #EEEEEE;padding:36px 40px 44px;">
|
|
148
|
+
<p style="margin:0 0 6px 0;font-family:'Instrument Serif',Georgia,'Times New Roman',serif;font-size:18px;font-weight:400;color:#111111;text-align:center;">[BRAND NAME]</p>
|
|
149
|
+
<p style="margin:0 0 24px 0;font-family:Inter,Arial,Helvetica,sans-serif;font-size:12px;line-height:1.5;color:#AAAAAA;text-align:center;">[COMPANY NAME] · [CITY, COUNTRY]</p>
|
|
150
|
+
<hr style="border:none;border-top:1px solid #E8E8E8;margin:0 auto 24px;width:96px;">
|
|
151
|
+
<p style="margin:0;font-family:Inter,Arial,Helvetica,sans-serif;font-size:12px;line-height:1.5;color:#BBBBBB;text-align:center;">
|
|
152
|
+
<a href="[UNSUBSCRIBE_URL]" style="color:#AAAAAA;text-decoration:underline;">Unsubscribe</a>
|
|
153
|
+
|
|
|
154
|
+
<a href="[PREFERENCES_URL]" style="color:#AAAAAA;text-decoration:underline;">Manage preferences</a>
|
|
155
|
+
</p>
|
|
156
|
+
</td>
|
|
157
|
+
</tr>
|
|
158
|
+
|
|
159
|
+
|
|
160
|
+
</table>
|
|
161
|
+
</td>
|
|
162
|
+
</tr>
|
|
163
|
+
</table>
|
|
164
|
+
|
|
165
|
+
</body>
|
|
166
|
+
</html>
|
|
@@ -28,9 +28,9 @@ https://github.com/user-attachments/assets/ee98a1b5-ebc4-452f-bbfb-c434f2935067
|
|
|
28
28
|
|
|
29
29
|
## Overview
|
|
30
30
|
|
|
31
|
-
The **Meta Ads Skill** is a comprehensive, production-ready
|
|
31
|
+
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**.
|
|
32
32
|
|
|
33
|
-
By using this skill, an agent transforms into an **Expert Media Buyer**. It will know exactly how to
|
|
33
|
+
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.
|
|
34
34
|
|
|
35
35
|
---
|
|
36
36
|
|
|
@@ -39,63 +39,36 @@ By using this skill, an agent transforms into an **Expert Media Buyer**. It will
|
|
|
39
39
|
This skill is designed using a **Progressive Disclosure (Hub-and-Spoke)** architecture to maximize context window efficiency:
|
|
40
40
|
|
|
41
41
|
1. **The Hub (`SKILL.md`)**: The primary entry point. It provides strict guardrails, safety protocols, and the authentication troubleshooting workflow.
|
|
42
|
-
2. **The Spokes (`references/`
|
|
42
|
+
2. **The Spokes (`references/`)**:
|
|
43
43
|
- 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.
|
|
44
44
|
- When presenting data to the user, read `references/report_templates.md` to strictly follow the required Markdown layout.
|
|
45
|
-
- **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.
|
|
46
45
|
|
|
47
46
|
### Strict Agent Guardrails
|
|
48
47
|
* **Context Protection**: ALWAYS default to `time_range="last_7d"` for insights. ALWAYS use `limit=10` for listing campaigns/adsets initially.
|
|
49
|
-
* **Safety First**: NEVER execute state-changing tools (`create_campaign`, `update_campaign
|
|
48
|
+
* **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.
|
|
50
49
|
|
|
51
50
|
---
|
|
52
51
|
|
|
53
|
-
## Installation & Setup
|
|
52
|
+
## Installation & Setup
|
|
54
53
|
|
|
55
|
-
To use this skill,
|
|
54
|
+
To use this skill, you must install the official Meta Ads CLI and configure your credentials.
|
|
56
55
|
|
|
57
|
-
### 1.
|
|
58
|
-
-
|
|
59
|
-
- A **Meta Developer Account** with a configured App.
|
|
60
|
-
|
|
61
|
-
### 2. Configure the Meta App
|
|
62
|
-
1. Go to the [Facebook Developers Portal](https://developers.facebook.com/).
|
|
63
|
-
2. Create an App and add the **Marketing API** product.
|
|
64
|
-
3. Under the Facebook Login settings, add `http://localhost:8000/auth/facebook/callback` to the **Valid OAuth Redirect URIs**.
|
|
65
|
-
4. Retrieve your **App ID** and **App Secret**.
|
|
66
|
-
|
|
67
|
-
### 3. Server Setup
|
|
68
|
-
Clone the MCP repository:
|
|
56
|
+
### 1. Install the CLI
|
|
57
|
+
The skill relies on the `meta-ads` Python package:
|
|
69
58
|
```bash
|
|
70
|
-
|
|
71
|
-
cd Meta-Ads-MCP
|
|
72
|
-
pip install -r requirements.txt
|
|
59
|
+
pip install meta-ads
|
|
73
60
|
```
|
|
74
61
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
FB_REDIRECT_URI="http://localhost:8000/auth/facebook/callback"
|
|
81
|
-
DATABASE_URL="sqlite:///.meta-ads-mcp/oauth.db"
|
|
82
|
-
```
|
|
83
|
-
|
|
84
|
-
---
|
|
85
|
-
|
|
86
|
-
## Authentication Workflow
|
|
87
|
-
|
|
88
|
-
The server uses OAuth backed by a local SQLite database to seamlessly pass tokens to the MCP context.
|
|
89
|
-
|
|
90
|
-
1. **Start the local Auth Server**:
|
|
91
|
-
```bash
|
|
92
|
-
python src/auth/run_web_server.py
|
|
93
|
-
```
|
|
94
|
-
2. **Authenticate**: Open `http://localhost:8000/auth/facebook` in your web browser.
|
|
95
|
-
3. **Grant Permissions**: Click "Connect Facebook" and approve the `ads_management`, `ads_read`, and `read_insights` permissions.
|
|
96
|
-
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.
|
|
62
|
+
### 2. Authentication (System User Token)
|
|
63
|
+
The CLI uses a **System User Access Token** for authentication.
|
|
64
|
+
1. Generate a System User Token in your [Meta Business Suite](https://business.facebook.com/settings/system-users).
|
|
65
|
+
2. Ensure the token has `ads_management`, `ads_read`, and `read_insights` permissions.
|
|
66
|
+
3. Set the following environment variables on your machine:
|
|
97
67
|
|
|
98
|
-
|
|
68
|
+
```bash
|
|
69
|
+
export ACCESS_TOKEN="your_system_user_access_token"
|
|
70
|
+
export AD_ACCOUNT_ID="act_your_ad_account_id"
|
|
71
|
+
```
|
|
99
72
|
|
|
100
73
|
---
|
|
101
74
|
|
|
@@ -109,16 +82,12 @@ meta-ads-skill/
|
|
|
109
82
|
references/
|
|
110
83
|
report_templates.md # Standardized markdown report structures
|
|
111
84
|
workflows.md # Orchestration strategies (e.g., CPA troubleshooting)
|
|
112
|
-
scripts/
|
|
113
|
-
auth_check.py # Diagnostic script for token status
|
|
114
|
-
formatters.py # JSON -> Markdown table utilities
|
|
115
85
|
```
|
|
116
86
|
|
|
117
|
-
## Supported
|
|
87
|
+
## Supported Commands
|
|
118
88
|
|
|
119
|
-
|
|
120
|
-
* **
|
|
121
|
-
* **
|
|
122
|
-
* **
|
|
123
|
-
* **
|
|
124
|
-
* **Database**: `token_status()`, `clear_database()`, `reset_database()`
|
|
89
|
+
This skill orchestrates the `meta-ads` CLI using a noun-verb structure:
|
|
90
|
+
* **Campaigns**: `meta ads campaign list`, `meta ads campaign create`
|
|
91
|
+
* **Ad Sets**: `meta ads adset list`
|
|
92
|
+
* **Ads**: `meta ads ad list`
|
|
93
|
+
* **Insights**: `meta ads insights get`
|
|
@@ -1,41 +1,58 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: meta-ads-expert
|
|
3
|
-
description: Use when interacting with the Meta Ads
|
|
3
|
+
description: Use when interacting with the Meta Ads CLI to manage accounts, campaigns, ads, and insights. Act as an Expert Media Buyer.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Meta Ads Expert Skill
|
|
7
7
|
|
|
8
|
-
**Persona:** You are an Expert Media Buyer. This skill acts as a router, providing high-level instructions and linking to detailed references
|
|
8
|
+
**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.
|
|
9
9
|
|
|
10
10
|
## Authentication & Setup
|
|
11
11
|
|
|
12
|
-
The Meta Ads
|
|
12
|
+
The Meta Ads CLI uses a **System User Access Token** for authentication.
|
|
13
13
|
|
|
14
|
-
###
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
3. **Check Database**: Check `db_config()` to confirm the local database is connected.
|
|
19
|
-
4. **Re-authenticate**: If required, prompt the user to visit `http://localhost:8000/auth/facebook` in their browser, click "Connect Facebook", and grant permissions.
|
|
14
|
+
### Environment Variables
|
|
15
|
+
Ensure the following environment variables are set in the environment where the CLI is executed:
|
|
16
|
+
- `ACCESS_TOKEN`: Your Meta System User Access Token.
|
|
17
|
+
- `AD_ACCOUNT_ID`: Your target Ad Account ID (e.g., `act_123456789`).
|
|
20
18
|
|
|
21
|
-
|
|
19
|
+
**CRITICAL:** NEVER use inline tokens in commands (e.g., `meta ads --token <TOKEN>`). Always rely on environment variables or pre-configured config files.
|
|
22
20
|
|
|
23
|
-
|
|
21
|
+
## CLI Routing
|
|
24
22
|
|
|
25
|
-
|
|
23
|
+
Map your intent to the following `meta-ads` CLI commands:
|
|
24
|
+
|
|
25
|
+
| Intent | CLI Command |
|
|
26
|
+
|---|---|
|
|
27
|
+
| List Ad Accounts | `meta ads account list` |
|
|
28
|
+
| List Campaigns | `meta ads campaign list` |
|
|
29
|
+
| List Ad Sets | `meta ads adset list` |
|
|
30
|
+
| List Ads | `meta ads ad list` |
|
|
31
|
+
| Get Insights | `meta ads insights get` |
|
|
32
|
+
| Create Campaign | `meta ads campaign create` |
|
|
26
33
|
|
|
27
34
|
## Strict Guardrails
|
|
28
35
|
|
|
29
|
-
###
|
|
36
|
+
### Command Execution
|
|
37
|
+
- **JSON Output**: ALWAYS use `--output json` for all read operations to ensure structured data for analysis.
|
|
38
|
+
- **No Input**: ALWAYS use `--no-input` (or equivalent) to prevent the Bash tool from hanging on interactive prompts.
|
|
39
|
+
- **Creation Safety**: ALWAYS use `--status PAUSED` for all creation commands unless the user explicitly requests an active status.
|
|
30
40
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
- **
|
|
41
|
+
### Date Ranges & Pagination
|
|
42
|
+
To prevent context window overflow and API rate limits:
|
|
43
|
+
- **Pagination Limits**: When listing items, cap the limit parameter (e.g., `--limit 10`) initially. Only expand if explicitly required.
|
|
44
|
+
- **Date Ranges**: For insights, ALWAYS default to `--time-range last_7d`. Do NOT request larger ranges unless instructed by the user.
|
|
34
45
|
|
|
35
46
|
## Safety Guardrails (State-Changing Actions)
|
|
36
47
|
|
|
37
|
-
You MUST require explicit user confirmation before executing any state-changing
|
|
48
|
+
You MUST require explicit user confirmation before executing any state-changing commands (e.g., `campaign create`, `campaign update`).
|
|
38
49
|
|
|
39
|
-
1. Present the exact parameters to the user.
|
|
50
|
+
1. Present the exact CLI command and parameters to the user.
|
|
40
51
|
2. Ask for explicit approval.
|
|
41
52
|
3. Only proceed if approved.
|
|
53
|
+
|
|
54
|
+
## Orchestration Workflows
|
|
55
|
+
|
|
56
|
+
For complex orchestrations (e.g., CPA spike analysis), see [references/workflows.md](references/workflows.md).
|
|
57
|
+
|
|
58
|
+
For reporting standards and output templates, see [references/report_templates.md](references/report_templates.md).
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Meta Ads Report Templates
|
|
2
2
|
|
|
3
|
-
Use these markdown templates when generating reports and summaries for users.
|
|
3
|
+
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`).
|
|
4
4
|
|
|
5
5
|
## 1. Executive Summary Template
|
|
6
6
|
|
|
@@ -10,11 +10,12 @@ Use these markdown templates when generating reports and summaries for users.
|
|
|
10
10
|
## Executive Summary
|
|
11
11
|
[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."]
|
|
12
12
|
|
|
13
|
-
## Key Metrics
|
|
13
|
+
## Key Metrics (Source: `meta ads insights get`)
|
|
14
14
|
- **Spend:** $[Amount] ([+/-]% vs previous period)
|
|
15
15
|
- **Revenue/Conversions:** [Amount] ([+/-]% vs previous period)
|
|
16
16
|
- **CPA:** $[Amount] ([+/-]% vs previous period)
|
|
17
17
|
- **ROAS:** [Amount]x ([+/-]% vs previous period)
|
|
18
|
+
- **CTR:** [Amount]% ([+/-]% vs previous period)
|
|
18
19
|
|
|
19
20
|
## Key Findings
|
|
20
21
|
- **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.
|
|
|
35
36
|
## The Issue
|
|
36
37
|
[Briefly state the problem. E.g., "CPA increased from $20 to $35 starting on [Date]."]
|
|
37
38
|
|
|
38
|
-
## Root Cause Analysis
|
|
39
|
+
## Root Cause Analysis (Source: `meta ads insights get --level [level]`)
|
|
39
40
|
- **Campaign Level:** [Identify which campaign(s) caused the spike.]
|
|
40
41
|
- **Ad Set Level:** [Identify specific ad sets. Did a lookalike audience degrade? Did a specific placement get expensive?]
|
|
41
42
|
- **Ad Level:** [Identify ad fatigue, drop in CTR, increase in CPM, or decrease in conversion rate.]
|
|
@@ -1,36 +1,31 @@
|
|
|
1
1
|
# Meta Ads Workflows
|
|
2
2
|
|
|
3
|
-
This document outlines complex orchestrations and workflows for common Meta Ads tasks.
|
|
3
|
+
This document outlines complex orchestrations and workflows for common Meta Ads tasks using the `meta-ads` CLI.
|
|
4
4
|
|
|
5
5
|
## 1. CPA Spike Troubleshooting
|
|
6
6
|
|
|
7
7
|
When a client or user asks to investigate a spike in Cost Per Action (CPA), follow this systematic approach:
|
|
8
8
|
|
|
9
9
|
1. **Account Level Overview**
|
|
10
|
-
- **
|
|
11
|
-
- **Tool:** `get_insights` (Level: account)
|
|
10
|
+
- **Command:** `meta ads insights get --level account --time-range last_30d --output json`
|
|
12
11
|
- **Action:** Look at overall account performance over the last 7, 14, and 30 days to identify when the spike started.
|
|
13
12
|
|
|
14
13
|
2. **Campaign Breakdown**
|
|
15
|
-
- **
|
|
16
|
-
- **
|
|
14
|
+
- **Command:** `meta ads campaign list --output json`
|
|
15
|
+
- **Command:** `meta ads insights get --level campaign --time-range last_7d --output json`
|
|
17
16
|
- **Action:** Identify which specific campaigns are driving the CPA increase. Compare spend and CPA across active campaigns.
|
|
18
17
|
|
|
19
18
|
3. **Ad Set Deep Dive**
|
|
20
|
-
- **
|
|
21
|
-
- **
|
|
19
|
+
- **Command:** `meta ads adset list --campaign-id <ID> --output json`
|
|
20
|
+
- **Command:** `meta ads insights get --level adset --time-range last_7d --output json`
|
|
22
21
|
- **Action:** For the offending campaigns, break down by Ad Set to see if specific audiences or placements are underperforming.
|
|
23
22
|
|
|
24
23
|
4. **Ad & Creative Analysis**
|
|
25
|
-
- **
|
|
26
|
-
- **
|
|
24
|
+
- **Command:** `meta ads ad list --adset-id <ID> --output json`
|
|
25
|
+
- **Command:** `meta ads insights get --level ad --time-range last_7d --output json`
|
|
27
26
|
- **Action:** Check if specific ads are experiencing ad fatigue (high frequency, dropping CTR) or if recent changes disrupted the learning phase.
|
|
28
27
|
|
|
29
|
-
5. **
|
|
30
|
-
- **Tool:** `analyze_campaigns`
|
|
31
|
-
- **Action:** Run automated analysis on the specific campaigns to generate actionable recommendations.
|
|
32
|
-
|
|
33
|
-
6. **Synthesis and Reporting**
|
|
28
|
+
5. **Synthesis and Reporting**
|
|
34
29
|
- Use the `CPA Spike Investigation Report` template (found in `report_templates.md`) to structure the findings and recommendations.
|
|
35
30
|
|
|
36
31
|
## 2. New Audience Discovery
|
|
@@ -38,7 +33,7 @@ When a client or user asks to investigate a spike in Cost Per Action (CPA), foll
|
|
|
38
33
|
When a user wants to find new audiences or test new targeting:
|
|
39
34
|
|
|
40
35
|
1. **Review Current Top Performers**
|
|
41
|
-
- **
|
|
36
|
+
- **Command:** `meta ads insights get --level adset --time-range last_30d --output json`
|
|
42
37
|
- **Action:** Identify the ad sets currently delivering the best ROAS/CPA.
|
|
43
38
|
|
|
44
39
|
2. **Generate Audience Ideas**
|
|
@@ -46,6 +41,7 @@ When a user wants to find new audiences or test new targeting:
|
|
|
46
41
|
|
|
47
42
|
3. **Structure the Test**
|
|
48
43
|
- Recommend a campaign structure for testing (e.g., A/B testing with Campaign Budget Optimization (CBO) or Ad Set Budget Optimization (ABO)).
|
|
44
|
+
- **Command Example:** `meta ads campaign create --name "Test_Audience_X" --status PAUSED --no-input`
|
|
49
45
|
|
|
50
46
|
4. **Monitoring**
|
|
51
47
|
- Provide the exact metrics to watch (e.g., CTR, CPC, early conversions) over the next 3-7 days.
|