Description

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

README (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.

Usage Guidance

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.

Capability Analysis

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.

Capability Assessment

⚠ 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.

Version History

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.

Metadata

Slug ad-engine

Version 1.0.0

License MIT-0

All-time Installs 0

Active Installs 0

Total Versions 1

Frequently Asked Questions

What is 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... It is an AI Agent Skill for Claude Code / OpenClaw, with 95 downloads so far.

How do I install Ad Engine?

Run "/install ad-engine" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.

Is Ad Engine free?

Yes, Ad Engine is completely free, licensed under MIT-0. You can download, install and use it at no cost.

Which platforms does Ad Engine support?

Ad Engine is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).

Who created Ad Engine?

It is built and maintained by aces1up (@aces1up); the current version is v1.0.0.

More Skills

Ad Engine