功能描述

Assemble modular ads from Supabase components and deploy to Facebook Ads Manager via the Marketing API. Supports preview, single/batch deploy, and status tra...

使用说明 (SKILL.md)

Ad Engine — Facebook Ads Deployment

Name: Ad Engine
Author: aces1up

Assemble ads from database components and deploy to Facebook. Reads from Supabase ad_components + messages tables, assembles full ad copy, uploads images, and creates Campaign → Ad Set → Ad in Facebook Ads Manager.

First-Time Setup

1. Facebook prerequisites (one-time, manual):

Facebook Business Manager account
Ad Account created
Facebook Page connected
Facebook Developer App with ads_management permission
Long-lived access token (generate at developers.facebook.com)

2. Store credentials:

python3 scripts/fb_deploy.py --setup

Prompts for access token, ad account ID, and page ID. Validates against FB API and saves to ~/.config/ad-engine/fb_config.json.

Usage

Preview assembled ads (no deployment):

# Preview a single ad
python3 scripts/fb_deploy.py --preview --message-id 8555

# Preview all draft ads for a campaign
python3 scripts/fb_deploy.py --preview --campaign-id 43

# Preview as JSON
python3 scripts/fb_deploy.py --preview --campaign-id 43 --json

Deploy a single ad:

python3 scripts/fb_deploy.py --deploy \
  --message-id 8556 \
  --image /path/to/security-audit-ad.png \
  --landing-url "https://calendly.com/your-link" \
  --objective messages

Deploy all draft ads for a campaign:

python3 scripts/fb_deploy.py --deploy \
  --campaign-id 43 \
  --image-dir /path/to/ad-images/ \
  --landing-url "https://calendly.com/your-link" \
  --objective messages

Dry run (preview what would be created):

python3 scripts/fb_deploy.py --deploy \
  --campaign-id 43 \
  --image-dir /path/to/images/ \
  --landing-url "https://calendly.com/link" \
  --dry-run

Check deployed ad status + live metrics:

python3 scripts/fb_deploy.py --status --campaign-id 43

Parameters

Parameter	Required	Description
`--preview`	One of	Preview assembled ads without deploying
`--deploy`	these	Deploy ads to Facebook
`--status`	three	Check status of deployed ads
`--setup`		Configure Facebook credentials
`--message-id`	For single	Specific message ID to preview/deploy
`--campaign-id`	For batch	All draft ads in a campaign
`--image`	Deploy single	Image file path
`--image-dir`	Deploy batch	Directory of images (matched by angle name in filename)
`--landing-url`	Deploy	Booking/landing page URL
`--objective`	No	`leads` (default), `messages`, or `link_clicks`
`--dry-run`	No	Preview deployment without creating anything
`--json`	No	Output as JSON

Image Naming Convention

When using --image-dir for batch deploy, name images by angle:

security-audit-ad.png      → matches angle "security_audit"
setup-is-hell-ad.png       → matches angle "setup_is_hell"
dm-trigger-checklist.png   → matches angle "dm_trigger"
anti-wrapper-graveyard.png → matches angle "anti_wrapper"

How It Works

Reads message from Supabase messages table (content_type = 'fb_ad')
Reads component references from message's extra_data.components
Resolves component keys → actual text from ad_components table
Slots components into framework template using {{merge_tags}}
Uploads image to Facebook → gets image_hash
Creates Campaign (if new) → Ad Set (if new) → Ad Creative → Ad
Updates message status to 'deployed' with FB IDs stored in extra_data

Database Schema

See AD_ENGINE_SPEC.md for full schema documentation.

Dependencies

psycopg2-binary — Supabase Postgres connection
facebook-business — Facebook Marketing API SDK
requests — HTTP client
All auto-installed on first run.

安全使用建议

Do not run this skill unreviewed. Key concerns: (1) fb_deploy.py contains a hard-coded SUPABASE_DSN (full Postgres connection string with credentials) — the skill will connect to that remote DB by default unless you override SUPABASE_DSN, so it may read or modify data on a third-party database. (2) The script auto-installs Python packages at first run (pip), which pulls code from PyPI at runtime — consider running in an isolated environment. (3) The script will prompt for and store a long-lived Facebook access token under ~/.config/ad-engine/fb_config.json; treat that file as sensitive. (4) The script inserts ~/.openclaw/workspace/skills onto sys.path and imports skill_base, which can cause execution of other code from your workspace — ensure you trust that environment. Recommended steps before installing: a) Inspect the full fb_deploy.py (you have it) and search for hard-coded secrets; remove or replace the SUPABASE_DSN default with an explicit placeholder. b) Run with SUPABASE_DSN set to your own test database or set it to an invalid value to ensure it doesn't connect to the embedded DB. c) Run first in an isolated VM or container so pip installs don't affect your system. d) If you plan to provide a Facebook token, understand it grants ad-management privileges — prefer using an app/account you control and rotate tokens after use. e) Ask the publisher for provenance/homepage and justification for embedding that Supabase DSN (is it a shared demo DB?). If you cannot verify the origin and purpose of the embedded DB credentials, treat the skill as untrusted.

功能分析

Type: OpenClaw Skill Name: ad-engine Version: 1.0.0 The ad-engine skill bundle contains a hardcoded Supabase database connection string (DSN) including a plaintext password in 'scripts/fb_deploy.py'. While the script appears to be a functional tool for managing Facebook Ads as described, the inclusion of live credentials is a major security vulnerability. Additionally, the script's 'ensure_deps' function uses subprocess to execute pip installs with the '--break-system-packages' flag, which is a risky practice. No evidence of intentional data exfiltration or malicious backdoors was found, but the credential leak and automated package installation make this bundle high-risk.

能力评估

⚠ Purpose & Capability

The skill's stated purpose is to read ad components from Supabase and deploy to Facebook. That's coherent in concept, but the skill declares no required environment variables or credentials while the bundled script contains a hard-coded SUPABASE_DSN (complete Postgres connection string with host and password) pointing to a remote Supabase instance and references a specific campaign (campaign 43). Requiring no DB credential but embedding one is disproportionate and unexpected: legitimate tooling would either require the user to supply their own DB DSN or clearly document use of a shared/read-only remote dataset.

⚠ Instruction Scope

SKILL.md instructs the agent to read messages and ad_components from Supabase and then create/modify Facebook objects and update message rows (including setting status and writing FB IDs). The runtime instructions (and fb_deploy.py) will connect to the database, assemble ads, upload images to Facebook, and update DB records. The instructions do not call out the embedded default DB connection or warn that the script will attempt to connect to a third-party Supabase instance if you don't set SUPABASE_DSN — that is scope creep and a transparency issue. The script also persists Facebook tokens to ~/.config/ad-engine/fb_config.json.

ℹ Install Mechanism

There is no formal install spec; this is an instruction+script skill. The script auto-installs Python dependencies via pip at runtime (psycopg2-binary, facebook-business, requests). Auto-installing packages is common but still increases risk (packages are pulled from PyPI at run time). There is no download-from-arbitrary-URL behavior, but runtime pip installs and executing the bundled Python file are the primary install surface.

⚠ Credentials

The registry metadata claims no required env vars or primary credential, yet the code will use SUPABASE_DSN from environment or fall back to a hard-coded Postgres DSN that includes host and password. It will also read FB_* env vars if present, but otherwise prompts and persists FB credentials. Shipping an embedded DB credential and defaulting to it is disproportionate: it grants the skill network access to a third-party DB without requiring or documenting that credential in the skill metadata. The skill also writes a local config file (~/.config/ad-engine/fb_config.json) to store tokens.

ℹ Persistence & Privilege

always is false (normal). The script persists its own config in the user's home (~/.config/ad-engine). It also manipulates sys.path to import skill_base from ~/.openclaw/workspace/skills — this cross-path import could cause the script to execute platform-provided code or interact with other installed skills; that's expected in many agent environments but worth noting as it increases the runtime trust surface. The skill does not attempt to modify other skills' configs in the provided files.

版本历史

v1.0.0

ad-engine 1.0.0 - Initial release of ad-engine. - Assemble Facebook ads from Supabase components and deploy via Facebook Marketing API. - Supports ad preview, single or batch deployment, and live status tracking. - Enables scalable A/B testing using the ad_components table. - Simple setup process and flexible CLI for managing all ad operations.

元数据

Slug ad-engine

版本 1.0.0

许可证 MIT-0

累计安装 0

当前安装数 0

历史版本数 1

常见问题

Ad Engine 是什么？

Assemble modular ads from Supabase components and deploy to Facebook Ads Manager via the Marketing API. Supports preview, single/batch deploy, and status tra... 它是一个面向 Claude Code / OpenClaw 的 AI Agent Skill 插件，目前累计下载 95 次。

如何安装 Ad Engine？

在 OpenClaw 或 Claude Code 对话框中运行命令「/install ad-engine」即可一键安装，无需额外配置。

Ad Engine 是免费的吗？

是的，Ad Engine 完全免费，采用 MIT-0 许可证，可自由下载、安装和使用。

Ad Engine 支持哪些平台？

Ad Engine 跨平台运行，可在任意部署了 OpenClaw / Claude Code 的环境中使用（cross-platform）。

谁开发了 Ad Engine？

由 aces1up（@aces1up）开发并维护，当前版本 v1.0.0。

Ad Engine