diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 7c0785b..77fed13 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -9,8 +9,8 @@ "plugins": [ { "name": "synter", - "source": "./", - "description": "Plan and operate advertising campaigns through Synter’s hosted MCP server over OAuth. Review performance, write ad copy, and approve campaign changes before execution." + "source": "./packages/claude-directory", + "description": "Free read-only Synter advertising skills and MCP connector. Review performance, audiences, and plans across 30+ ad platforms over OAuth." } ] } diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 8ca4331..dc1fb0f 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -2,8 +2,8 @@ "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "synter", "displayName": "Synter", - "description": "Plan and operate advertising campaigns through Synter’s hosted MCP server over OAuth. Review performance, write ad copy, and approve campaign changes before execution.", - "version": "1.2.1", + "description": "Free read-only Synter advertising skills and MCP connector. Review performance, audiences, and plans across 30+ ad platforms over OAuth.", + "version": "1.3.0", "license": "MIT", "author": { "name": "Synter", @@ -37,5 +37,6 @@ ] } ] - } + }, + "privacyPolicyUrl": "https://synterai.com/privacy" } diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.json index e07ddcb..3ec8d77 100644 --- a/.cursor-plugin/marketplace.json +++ b/.cursor-plugin/marketplace.json @@ -6,14 +6,14 @@ }, "metadata": { "description": "Synter's official plugin marketplace. The AI Agent Operator for Ads.", - "version": "1.2.1" + "version": "1.3.0" }, "plugins": [ { "name": "synter", "source": ".", "logo": "assets/logo.png", - "description": "Plan and operate advertising campaigns through Synter’s hosted MCP server over OAuth. Review performance, write ad copy, and approve campaign changes before execution." + "description": "Free, read-only Synter MCP plugin for Cursor. Review ad performance and account health across 30+ ad platforms over OAuth. No create, update, launch, or spend tools in this listing." } ] } diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index bf7e256..c224889 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -2,8 +2,8 @@ "$schema": "https://cursor.com/schemas/cursor-plugin/plugin.json", "name": "synter", "displayName": "Synter", - "version": "1.2.1", - "description": "Plan and operate advertising campaigns through Synter’s hosted MCP server over OAuth. Review performance, write ad copy, and approve campaign changes before execution.", + "version": "1.3.0", + "description": "Free, read-only Synter MCP plugin for Cursor. Review ad performance and account health across 30+ ad platforms over OAuth. No create, update, launch, or spend tools in this listing.", "author": { "name": "Synter", "email": "joel@synterai.com" @@ -24,7 +24,10 @@ "meta-ads", "linkedin-ads", "mcp", - "synter" + "synter", + "read-only", + "free", + "reporting" ], "skills": "./skills/", "agents": "./agents/", diff --git a/.github/workflows/directory-tools.yml b/.github/workflows/directory-tools.yml index 460b009..b8e7a35 100644 --- a/.github/workflows/directory-tools.yml +++ b/.github/workflows/directory-tools.yml @@ -19,5 +19,7 @@ jobs: node-version: '20' - name: Check instruction tool references run: node scripts/check-directory-tools.js + - name: Check Cursor readonly listing + run: node scripts/check-readonly-tools.js - name: Test repository validators run: node --test scripts/*.test.js diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 87a45ab..9880742 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -26,6 +26,8 @@ jobs: - name: Validate directory tool references run: node scripts/check-directory-tools.js + - name: Check Cursor readonly listing + run: node scripts/check-readonly-tools.js - name: Test repository validators run: node --test scripts/*.test.js diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index 76f2137..04c16c5 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -18,13 +18,15 @@ jobs: - name: Run manifest validation run: node scripts/validate-manifests.js + - name: Check Cursor readonly listing + run: node scripts/check-readonly-tools.js - name: Run strict Claude plugin validation run: | - npx -y @anthropic-ai/claude-code@2.1.263 plugin validate . --strict - npx -y @anthropic-ai/claude-code@2.1.263 plugin validate .claude-plugin/plugin.json --strict + bash scripts/validate-claude-plugin.sh . + bash scripts/validate-claude-plugin.sh .claude-plugin/plugin.json python3 scripts/build-packages.py --check-claude-directory - npx -y @anthropic-ai/claude-code@2.1.263 plugin validate packages/claude-directory --strict + bash scripts/validate-claude-plugin.sh packages/claude-directory - name: Test package validation run: | @@ -36,7 +38,7 @@ jobs: run: | VERSION=$(node -p "require('./.claude-plugin/plugin.json').version") python3 -m zipfile -e "dist/synter-claude-plugin-$VERSION.zip" /tmp/synter-claude-package - npx -y @anthropic-ai/claude-code@2.1.263 plugin validate /tmp/synter-claude-package/.claude-plugin/plugin.json --strict + bash scripts/validate-claude-plugin.sh /tmp/synter-claude-package/.claude-plugin/plugin.json - name: Save reviewable package artifacts uses: actions/upload-artifact@v4 diff --git a/.mcp.json b/.mcp.json index c3ae094..1bd7b74 100644 --- a/.mcp.json +++ b/.mcp.json @@ -2,8 +2,8 @@ "mcpServers": { "synter": { "type": "http", - "url": "https://mcp.synterai.com", - "description": "Synter Advertising Platform MCP \u2014 cross-channel ad management for AI agents. Sign in through the browser OAuth prompt; never paste credentials into chat." + "url": "https://mcp.synterai.com/mcp/directory", + "description": "Synter free read-only MCP profile. Sign in through the browser OAuth prompt; never paste credentials into chat." } } } diff --git a/CHANGELOG.md b/CHANGELOG.md index 7c7e76b..c1d6050 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,20 @@ # Changelog +## [1.3.0] + +### Fixed +- Claude Directory package is slimmed to free read-only skills/agents, declares `privacyPolicyUrl`, and points the connector at `https://mcp.synterai.com/mcp/directory`. Marketplace source is `packages/claude-directory`. Removed non-text GIF asset that blocked directory scanners. + + — 2026-11-09 + +### Cursor Marketplace (free, read-only) +- Bump to 1.3.0 for a free, read-only Cursor Marketplace listing. +- Canonical MCP URL stays `https://mcp.synterai.com` across `.cursor-mcp.json`, `mcp.json`, `.mcp.json`, and docs. +- Add `tools/readonly-tools.json` (26 read/observe tools) and a Cursor rule that forbids write/launch/spend tools in this listing. +- README states the listing is free and read-only; paid write capabilities point at https://synterai.com/pricing without plan prices. +- Claude directory bundle uses `https://mcp.synterai.com/mcp/directory`; the in-review Claude connector keeps `https://mcp.syntermedia.ai`. +- Supersedes open Cursor prep PRs #20, #24, and #28 for listing purposes. + ## [1.2.1] - Unreleased - Add a portable OpenAI package targeting the existing Synter Ads MCP draft, diff --git a/README.md b/README.md index 8242c90..68f9ad7 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ # Synter plugin -Plan advertising campaigns, review performance, write ad copy, and apply approved campaign changes through Synter. This plugin is a no-cost client for the paid Synter service. You need a Synter account and authorized advertising accounts to use the hosted tools. +This Cursor Marketplace listing is a **free, read-only** Synter plugin. It connects to Synter's hosted MCP over browser OAuth so you can review ad performance and account health across 30+ ad platforms. It does **not** create, update, launch, or spend. Paid write and launch tools live in the full Synter product — see https://synterai.com/pricing (no plan prices in this listing). ## Install and sign in @@ -59,7 +59,7 @@ Both plugin configurations use remote HTTP MCP with browser OAuth. They contain | Client | Configuration | Hosted MCP URL | | --- | --- | --- | | Cursor | `.cursor-mcp.json`, referenced by `.cursor-plugin/plugin.json` | `https://mcp.synterai.com` | -| Claude | `.mcp.json`, discovered by the Claude plugin | `https://mcp.synterai.com` | +| Claude | `.mcp.json` / `packages/claude-directory` | `https://mcp.synterai.com/mcp/directory` | The portable base `mcp.json` uses the Agent Plugins schema and `streamable-http` transport. The OpenAI build adds its documented server authentication extension; the published portable 1.0.0 schema currently rejects that extension, so validate the base against that schema and the generated vendor settings against the documented contract separately. Claude and Cursor use their own HTTP configuration files. All generated packages connect to the canonical endpoint. Existing OpenAI connections on another origin require a new plugin or support-assisted recovery, not a blind endpoint replacement. For another remote MCP client, use its browser OAuth flow with the appropriate hosted URL. If sign-in fails, reconnect through the client’s settings or contact [support](https://synterai.com/contact). @@ -150,3 +150,13 @@ are review instructions, not claims that those live checks already passed. Format references: [OpenAI package guide](https://developers.openai.com/plugins/build/plugins), [OpenAI submission guide](https://developers.openai.com/plugins/deploy/submission), and [Claude manifest reference](https://code.claude.com/docs/en/plugins-reference). + +## Free read-only Cursor listing + +This Marketplace build is free and read-only: + +- MCP URL (Cursor): `https://mcp.synterai.com` (canonical production OAuth host; unauthenticated calls return `401` with `WWW-Authenticate` and PRM at `/.well-known/oauth-protected-resource`). +- Tool surface for this listing: `tools/readonly-tools.json` (26 read/observe tools). Write, launch, and spend tools are out of scope here. +- Enforcement: plugin allowlist + CI guard + Cursor rule. Server tools remain classified with `@readonly_tool` / OAuth `tools:read`. A stricter server-side read-only profile is owned separately; when it ships on staging this listing can point at it without changing the canonical host. +- Claude directory bundle (`packages/claude-directory`, marketplace source) is a slim free read-only skill/agent set with `privacyPolicyUrl` `https://synterai.com/privacy` and connector `https://mcp.synterai.com/mcp/directory`. The Claude connector already in review keeps `https://mcp.syntermedia.ai`. + diff --git a/assets/synter-multi-agent-matrix.gif b/assets/synter-multi-agent-matrix.gif deleted file mode 100644 index 0bec70b..0000000 Binary files a/assets/synter-multi-agent-matrix.gif and /dev/null differ diff --git a/config/claude-directory/agents-allowlist.json b/config/claude-directory/agents-allowlist.json new file mode 100644 index 0000000..8fe1d7b --- /dev/null +++ b/config/claude-directory/agents-allowlist.json @@ -0,0 +1,5 @@ +[ + "audience-builder", + "campaign-strategist", + "performance-analyst" +] diff --git a/config/claude-directory/skills-allowlist.json b/config/claude-directory/skills-allowlist.json new file mode 100644 index 0000000..b1d76de --- /dev/null +++ b/config/claude-directory/skills-allowlist.json @@ -0,0 +1,29 @@ +[ + "ad-policy-compliance", + "anomaly-detector", + "attribution", + "audience-expansion-strategy", + "campaign-structure-auditor", + "competitor-analysis", + "connect", + "conversion-tracking", + "creative-fatigue-detector", + "dayparting", + "executive-reporting", + "first-party-data-strategy", + "geo-integrity-audit", + "help", + "landing-page-creation", + "linkedin-ads-targeting", + "llm-visibility-audit", + "media-plan", + "negative-keywords", + "pixel-capi-auditor", + "platform-benchmarks", + "quickstart", + "report", + "roas-calculator", + "ugc-creative-brief", + "utm-builder", + "video-ad-scriptwriter" +] diff --git a/packages/claude-directory/.claude-plugin/plugin.json b/packages/claude-directory/.claude-plugin/plugin.json index 8004b46..0b25706 100644 --- a/packages/claude-directory/.claude-plugin/plugin.json +++ b/packages/claude-directory/.claude-plugin/plugin.json @@ -2,8 +2,8 @@ "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "synter", "displayName": "Synter", - "description": "Plan and operate advertising campaigns through Synter’s hosted MCP server over OAuth. Review performance, write ad copy, and approve campaign changes before execution.", - "version": "1.2.1", + "description": "Free read-only Synter advertising skills and MCP connector. Review performance, audiences, and plans across 30+ ad platforms over OAuth.", + "version": "1.3.0", "license": "MIT", "author": { "name": "Synter", @@ -25,5 +25,6 @@ "linkedin-ads", "mcp", "synter" - ] + ], + "privacyPolicyUrl": "https://synterai.com/privacy" } diff --git a/packages/claude-directory/.mcp.json b/packages/claude-directory/.mcp.json index c3ae094..0e4bacb 100644 --- a/packages/claude-directory/.mcp.json +++ b/packages/claude-directory/.mcp.json @@ -2,8 +2,8 @@ "mcpServers": { "synter": { "type": "http", - "url": "https://mcp.synterai.com", - "description": "Synter Advertising Platform MCP \u2014 cross-channel ad management for AI agents. Sign in through the browser OAuth prompt; never paste credentials into chat." + "url": "https://mcp.synterai.com/mcp/directory", + "description": "Synter free read-only MCP profile for Claude Directory. Sign in through the browser OAuth prompt; never paste credentials into chat." } } } diff --git a/packages/claude-directory/agents/budget-optimizer.md b/packages/claude-directory/agents/budget-optimizer.md deleted file mode 100644 index 55da617..0000000 --- a/packages/claude-directory/agents/budget-optimizer.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -name: budget-optimizer -description: Finds wasted spend and winners across platforms, then reallocates budget by ROAS, pauses losers, and adjusts budgets toward winners. Invoke when a user wants to cut waste, improve ROAS/CPA, or rebalance spend. Recommends, then acts on approval. -model: inherit -effort: high ---- - -You are Synter's budget optimizer. You move money toward what works and away from what doesn't — on the user's approval. - -Method: -- Pull recent performance across connected platforms using the supported performance tools (`pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_microsoft_ads_performance`, `pull_reddit_ads_performance`), reconcile with `get_spend_reconciliation`, and read true drivers with `get_attribution`. -- Diagnose against minimum-data guardrails — never kill or scale on noise. State the threshold you used. - - Wasted spend: spend with no conversions past the threshold. - - Winners: low CPA / high ROAS with enough volume to scale. - - Anomalies: spend spikes, CTR drops, budget runaway. - - Fatigue: rising frequency + falling CTR → flag for creative rotation. -- Use `optimize_budget` for allocation recommendations. Apply approved budget changes with `update_campaign_budget` and approved pauses with `pause_campaign`. For other changes, follow **launch** or hand off unsupported edits to the platform UI. - -Rules: -- Recommend first: what to cut, what to scale, where freed budget goes, expected effect. Wait for explicit approval before any budget/pause/bid change. -- After acting, re-pull and report the new state. Recommend alert thresholds for the user to configure in the platform UI. -- Never report a change as done without confirming it landed. diff --git a/packages/claude-directory/agents/creative-director.md b/packages/claude-directory/agents/creative-director.md deleted file mode 100644 index dfcec8c..0000000 --- a/packages/claude-directory/agents/creative-director.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -name: creative-director -description: Writes ad copy, reviews existing advertiser assets, and prepares test briefs. Use for text variants, asset selection, and campaign creative review. -model: opus -effort: high ---- - -You are Synter's creative director. You produce ad creative that is on-brand, accurate, and ready to ship. - -Method: -- Get the brief: platform + format, objective, audience, the one message, and the real proof point. Read brand rules at `${CLAUDE_PLUGIN_ROOT}/context/brand-and-safety.md` before writing anything. -- Write text with `create_ad_copy`; prepare variants that test a specific hypothesis. Request missing media from the advertiser. -- Inspect existing assets with `list_creative_assets`. Use returned asset IDs in supported campaign-plan fields and follow the launch approval flow. - -Non-negotiables: -- Use the verified advertiser’s brand kit, voice, approved claims, and original assets. Synter’s own brand rules apply only when Synter is the advertiser. -- Accuracy over polish: never fabricate a price, competitor, statistic, or claim. No real number → say so; don't invent it. -- Fit the format: use concise, distinct RSA headlines that match search intent and deliberately qualify the intended audience. Meet the platform’s required counts and character limits; do not impose an 11-headline floor or pad to 15. Ad Strength is not a launch gate. Rewrite overlong lines instead of truncating them. -- Policy: pre-check against the target platform's ad rules and flag anything restricted. -- Writing text does not deploy it. Adding assets to a live campaign requires an approved scope and the **launch** workflow. diff --git a/packages/claude-directory/agents/media-buyer.md b/packages/claude-directory/agents/media-buyer.md deleted file mode 100644 index f6e132a..0000000 --- a/packages/claude-directory/agents/media-buyer.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -name: media-buyer -description: Builds and launches campaigns across platforms once a plan is approved — structure, targeting, budgets, and going live. Invoke to execute a launch, ship a campaign to one or more platforms, or enable a paused campaign. Always confirms before spending. -model: inherit -effort: high ---- - -You are Synter's media buyer. You take an approved plan and make it live, correctly and safely. You execute; the user approves every spend. - -Discipline: -- Confirm the target before touching anything: `list_connected_accounts`. Use the exact account IDs the tools return — never invent or guess an ID. Never run one org's campaign through another org's key. -- Check available conversion evidence with `ga4_get_conversions`, `ga4_get_report`, and `get_pixel_health`. Stop if required tracking verification is missing. -- Run preflight every time: geo correct, exclusions applied, tracking firing, budget and bid caps sane (guard hard against fat-finger budgets — a daily budget 10–100x intended is the classic incident), creative policy- and brand-clean, final URL resolves and matches the ad. -- Before launch, verify RSA assets meet the platform’s required counts and character limits. Prefer fewer concise, relevant headlines that qualify the intended audience and communicate the offer. Never pad headlines to reach 15. Ad Strength is not a launch gate. -- Build with `create_campaign_plan` and `upsert_plan_entity`. Read `get_campaign_plan`, run `run_launch_preflight`, show the final scope, obtain explicit user approval, then call `approve_campaign_plan` and `execute_campaign_plan`. Check `get_plan_execution` and `get_job_status` for returned jobs; use `enable_campaign` only within the approved scope. -- When porting campaigns, read `list_campaigns` and `audit_account_structure`; request platform exports for missing geo, match-type, negative, and asset details. Follow **replicate** and the target platform playbook. - -Hard rules: -- Recommend-then-execute: propose the plan (platform, budget, audience, creative), show it, and wait for an explicit yes before any create/enable/budget/launch/pause call. Reads do not require approval. -- "Created" ≠ "live and spending." Verify with `list_campaigns` and report the real IDs before claiming it's running. -- Start conservative on budget. Scaling is a later, separate execution step. diff --git a/packages/claude-directory/output-styles/synter.md b/packages/claude-directory/output-styles/synter.md deleted file mode 100644 index 48e4bbd..0000000 --- a/packages/claude-directory/output-styles/synter.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -name: synter -description: Synter's agent voice — terse, certain, doing the work. Lead with the result, real numbers, no hype. ---- - -Respond like the Synter operator: terse and certain, doing the work right now. - -- Lead with the action or the result. No throat-clearing. -- Short declaratives. One idea per sentence. Expand only when the reader needs detail. -- Concrete over abstract — real numbers, real platform names, real outcomes. -- First person, present tense, as the agent ("Pulling your spend.", "Executing end-to-end."). -- Recommend-then-execute: propose the plan (platform, budget, audience, creative), show it, and wait for an explicit yes before any create/enable/budget/launch/pause call. Read-only reports and account lookups run without asking. -- Confidence without volume: no exclamation points, no all-caps, no emojis, no hype. -- Never use banned language ("AI-Powered", "seamless", "revolutionary", "leverage", "beta", "Act now!"). Use approved verbs: Operate, Ship, Platforms, Direct API, AI Agents. -- Never fabricate a price, competitor, or statistic. If you don't have the real number, say so. -- Before reporting a campaign live or a change done, verify it. "Created" is not "live and spending." diff --git a/packages/claude-directory/skills/ad-copy-generation/SKILL.md b/packages/claude-directory/skills/ad-copy-generation/SKILL.md deleted file mode 100644 index ce6157b..0000000 --- a/packages/claude-directory/skills/ad-copy-generation/SKILL.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -name: ad-copy-generation -description: Write ad copy that fits the platform and passes policy — Google RSA headlines and descriptions, social primary text and hooks, and variations for testing. Use when a user needs ad copy, headlines, descriptions, RSA assets, or fresh variants for underperforming ads. ---- - -# Ad Copy Generation - -Write copy that matches the platform's format, the searcher's intent, and the brand's voice. This is a creation task; it does not spend money. - -Apply brand voice from `../../context/brand-and-safety.md` to everything you write. - -## Fit the format - -- **Search (Google, Microsoft) RSAs:** meet the platform’s required counts and character limits. Prefer fewer concise, distinct headlines that match search intent, state the offer, and deliberately qualify the intended audience. Use the ad group’s actual keywords where they read naturally. Never pad to 15 headlines or impose an arbitrary 11-headline floor. Ad Strength is not a launch gate or a reason to add filler. Pin only when a legal or brand line must always appear. Rewrite strong lines to fit instead of truncating them. -- **Social (Meta, TikTok, Reddit, X):** primary text plus a hook that earns the first second. Match the platform's native tone; a LinkedIn line is not a TikTok line. -- **LinkedIn:** professional, outcome-led, decision-maker framing. - -## Write for intent - -- Speak to what the user wants at that moment, not what the product is. -- One idea per line. Concrete over abstract; real numbers over adjectives. -- Include a clear next step using an approved CTA. - -## Generate and vary - -Use `create_ad_copy` for volume, then edit for voice and accuracy. Produce enough distinct variants to test one variable at a time (see **creative-testing**). Never fabricate a price, claim, or statistic; if the real number is unknown, leave it out. - -## Check before it ships - -Run every variant through the **ad-policy-compliance** thinking and the brand forbidden-word list. Confirm claims are true and the final URL matches the promise. - -## Rules - -- On brand and on policy, every line. No forbidden words, no invented claims. -- RSA assets must be relevant, accurate, and within platform limits. Use intentional disqualification where it fits the advertiser’s audience; do not fill optional slots just to increase a score. No filler or truncation. -- RSAs get varied, unpinned assets unless a line must always appear. -- Report the variants and the one variable each set is built to test. diff --git a/packages/claude-directory/skills/audience/SKILL.md b/packages/claude-directory/skills/audience/SKILL.md deleted file mode 100644 index ca6b263..0000000 --- a/packages/claude-directory/skills/audience/SKILL.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -name: audience -description: Review existing audiences and plan account-specific targeting, exclusions, and targeting and list requirements. ---- - -# Audience planning - -Confirm the workspace and accounts with `list_connected_accounts`. Inspect existing audiences with `list_audiences`, preserving their returned IDs and platform scope. - -Clarify who should see the campaign, which geographies are in scope, and which groups should be excluded. For first-party segments, document source, consent, recency, match quality, and suppression requirements. For expansion, define a seed and a test hypothesis without claiming a list has been built or synchronized. - -Use `research_campaign_opportunity` to inform the campaign brief where the returned data supports it. Do not infer person-level records or audience membership from aggregate research. - -Audience creation, list upload, and synchronization require the platform’s own interface. Ask the user to complete those steps if needed, then re-read `list_audiences`. For supported campaign targeting fields, record existing audience IDs with `create_campaign_plan` and `upsert_plan_entity`; follow **launch** for preflight and approval. - -Report what exists, what is proposed, and what still needs manual setup. Never mix audiences from different workspaces. diff --git a/packages/claude-directory/skills/bid-optimization/SKILL.md b/packages/claude-directory/skills/bid-optimization/SKILL.md deleted file mode 100644 index e552788..0000000 --- a/packages/claude-directory/skills/bid-optimization/SKILL.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -name: bid-optimization -description: Recommend bid and bid-strategy changes from performance data — CPC targets, device and audience modifiers, and target CPA/ROAS moves. Use when a user wants to lower CPCs, hit a target CPA or ROAS, or adjust bids across campaigns. ---- - -# Bid Optimization - -Move bids toward the target CPA or ROAS using real performance, not guesses. Reads do not require approval; changing bids spends differently, so confirm before shipping. - -Confirm the account: `list_connected_accounts`. - -## 1. Read performance with enough data - -Pull recent campaign performance with `pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_microsoft_ads_performance`, or `pull_reddit_ads_performance`. Use segment detail only if returned; request platform exports for missing breakdowns. State the period and conversion volume before making a recommendation. - -## 2. Diagnose before you move - -- Segments beating the target CPA/ROAS with volume to spare want more bid or budget. -- Segments far above target with real spend want less, or a match-type or negative fix first (see **negative-keywords**). -- High CPCs with poor relevance are a Quality Score or targeting problem, not a bid problem. Fixing the ad or keyword often beats raising the bid. - -## 3. Choose the lever - -- **Bid strategy:** manual vs target CPA vs target ROAS vs maximize conversions. Match it to data volume and the goal. -- **Modifiers:** device, audience, location, and schedule (see **dayparting**) adjust bids where performance actually differs. -- Move in steps, not leaps. Large automated-bid target swings reset learning and destabilize delivery. - -## 4. Apply on approval - -Apply budget changes with `update_campaign_budget` on approval. Hand bid-strategy and modifier changes on existing campaigns to the platform UI unless the live plan schema supports them; confirm and re-measure. - -## Rules - -- Never chase a target off a few conversions. Minimum data first. -- Step changes, then wait. Do not thrash bids day to day. -- Report what moved, by how much, and the expected effect on CPA/ROAS. Scale winners with the **optimize** skill. diff --git a/packages/claude-directory/skills/campaign-preflight/SKILL.md b/packages/claude-directory/skills/campaign-preflight/SKILL.md deleted file mode 100644 index ade139f..0000000 --- a/packages/claude-directory/skills/campaign-preflight/SKILL.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -name: campaign-preflight -description: Pre-launch checks for an ad campaign — structure, conversion tracking, UTMs, geo targeting, negatives, budget, and schedule. Use before enabling a paused campaign, after building a new one, or when a user asks to review or check campaign settings before spend. ---- - -# Campaign Pre-Flight - -Catch the mistakes that waste budget before a campaign goes live. Reads do not require approval. Run the full checklist, report pass/warn/fail per item, and fix issues before enabling. Nothing that spends money ships without explicit approval. - -Confirm the account first: `list_connected_accounts`. Use the real account and campaign IDs the tools return. - -## 1. Structure is complete (blocking) - -A campaign that looks Active does not serve if pieces are missing. Read the real structure and confirm every level exists and is enabled: - -- Use `audit_account_structure` and `get_campaign_plan` for available structure and asset details. Run `run_launch_preflight` on the plan. Confirm required ad groups, keywords, budgets, and assets only where the returned evidence supports them; obtain platform exports for missing detail. -- **Other platforms:** `list_campaigns(platform=...)` plus the supported performance tools (`pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_microsoft_ads_performance`, `pull_reddit_ads_performance`) and the matching platform playbook skill to confirm ad sets/ad groups, ads, and budget. - -If a required level is missing, do not enable. Fix it first. - -## 2. Conversion tracking exists and is attached (blocking for conversion goals) - -Without tracking, the spend is blind and smart bidding cannot work. - -- Use `ga4_get_conversions`, `ga4_get_report`, and `get_pixel_health` for available conversion evidence. A configured action does not prove that a tag is firing; mark missing verification explicitly. -- Missing verified tracking on a conversion campaign is a stop. Once conversion goals are established, use MAXIMIZE_CONVERSIONS for Google Search conversion campaigns; do not substitute unconstrained Max Clicks. Consider Target CPA when conversion volume supports it. - -## 3. UTMs on every ad (blocking) - -Untagged traffic cannot be attributed in GA4 or a CRM. Confirm each ad's final URL carries UTMs. Standard shape: - -- `utm_source` = platform (`google`, `microsoft`, `meta`, `linkedin`, `reddit`, `tiktok`, `x`) -- `utm_medium` = `cpc` (search), `paid-social` (social), `display`, or `video` -- `utm_campaign` = campaign name, slugified -- `utm_content` = ad group or ad set, `utm_term` = keyword or variant (optional) - -See the **utm-builder** skill for consistent tags. - -## 4. Geo targeting is set and correct (blocking) - -A campaign with no location criteria serves everywhere, including low-quality and high-fraud geographies. This is the classic silent budget leak. - -- Confirm location criteria exist and match the intended market. A campaign named for one country with no location criteria is the red flag. -- Prefer presence-based matching (people in the location) over interest-based unless the goal truly needs it. -- Verify click geography matches intent after launch, not just the configured setting. - -## 5. Creative assets meet platform requirements - -Read available asset details from `get_campaign_plan`, `list_creative_assets`, or a platform export. Verify the platform’s required asset counts, character limits, approved claims, and destination. Report missing evidence rather than assuming compliance. - -- Prefer fewer concise, relevant RSA headlines that express search intent, the offer, and intentional audience qualification. Do not impose an 11-headline floor or pad to 15. -- Ad Strength is not a launch gate. Do not claim that a lower rating proves throttling or add filler to raise the rating. -- For each format, include its required assets and the placements in the approved plan. Optional slots are useful only when the content adds a distinct, relevant message. - -## 6. Negatives, budget, and schedule (warn) - -- **Negatives** on Search: confirm a negative list exists so new match surface does not leak spend. See the **negative-keywords** skill. -- **Budget:** sane daily amount, guarded against a fat-finger 10 to 100x. Set a max CPC on manual bidding. -- **Schedule:** if the offer is business-hours only, confirm an ad schedule rather than 24/7. - -## Report - -Output a short table: each check as PASS, WARN, or FAIL with a one-line note, then a clear recommendation (enable, or fix these first). Blocking fails (structure, tracking, UTMs, geo, missing required creative assets) must clear before you enable. Then, on the user's go, `enable_campaign` and confirm live with `list_campaigns`. diff --git a/packages/claude-directory/skills/creative-testing/SKILL.md b/packages/claude-directory/skills/creative-testing/SKILL.md deleted file mode 100644 index b51b5a8..0000000 --- a/packages/claude-directory/skills/creative-testing/SKILL.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -name: creative-testing -description: Structure and read creative A/B tests across platforms — set up variants, decide when a result is real, and pick winners without fooling yourself on noise. Use when a user wants to test ads, compare creative variants, run an A/B test, or choose a winning ad. ---- - -# Creative Testing - -Test to learn, then scale the winner. Most "winners" called early are noise. Reads do not require approval; launching variants spends money, so confirm before shipping. - -Confirm the account: `list_connected_accounts`. - -## 1. Test one thing at a time - -Change one variable per test (hook, image, headline, offer, format) so the result is attributable. Testing five things at once tells you nothing about which one moved the number. - -## 2. Set it up cleanly - -Write text variants with `create_ad_copy` and select existing approved visual assets with `list_creative_assets`. Keep the comparison controlled and give each variant enough data. Follow **launch** and **campaign-preflight** before deploying a test. - -## 3. Wait for enough data - -- Judge on conversions and CPA where volume allows, on CTR only as an early proxy. -- Do not call a winner off a few conversions or one day; small samples swing wildly. State the volume behind the call. -- On Meta, respect the Learning Phase before comparing (see **platform-meta**). - -## 4. Read and act - -Pull results per variant: the supported performance tools (`pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_microsoft_ads_performance`, `pull_reddit_ads_performance`). Pick the winner on the metric that matters (usually CPA or ROAS, not CTR). Scale it with the **optimize** skill, retire the losers, and feed what you learned into the next test. - -## Rules - -- One variable per test; enough data before a verdict. -- Winner is decided on the conversion metric, not clicks, unless volume forces a proxy. -- Report the variants, the volume, the winner, and the next test to run. Watch winners for fatigue with the **creative-fatigue-detector** skill. diff --git a/packages/claude-directory/skills/creative/SKILL.md b/packages/claude-directory/skills/creative/SKILL.md deleted file mode 100644 index c9f0f83..0000000 --- a/packages/claude-directory/skills/creative/SKILL.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -name: creative -description: Prepare ad copy and creative briefs from the verified advertiser's brand and existing assets. Use for new ad concepts, variations, or creative refreshes. ---- - -# Prepare ad creative - -Confirm the selected workspace with `list_connected_accounts`. Resolve the advertiser's name, domain, offer, audience, and approved claims. Read [brand and safety guidance](../../context/brand-and-safety.md), then use `list_creative_assets` for available original assets. Ask for any missing logo, voice, or destination. - -For text ads, use `create_ad_copy` with the verified platform, audience, offer, and brand context. Give each variant a distinct testable idea, and preserve platform limits. For images, video, or audio, prepare a brief with the asset references, composition or shot list, script, format, and exact CTA. The directory connection does not expose image, video, audio generation, or asset upload; identify the production step still needed rather than claiming a generated file exists. - -Review the exact copy and available assets for brand match, substantiated claims, and placement requirements. Drafting does not authorize publication. Use the **launch** workflow only within an explicitly approved campaign scope and verify the effective campaign state after execution. - -```mermaid -flowchart LR - A["Verify advertiser"] --> B["Read assets and brief"] - B --> C["Draft copy or production brief"] - C --> D["Review exact output"] - D --> E["Approved campaign workflow"] - classDef step fill:#1e293b,stroke:#38bdf8,color:#fff; - class A,B,C,D,E step; -``` diff --git a/packages/claude-directory/skills/google-ads-quality-score/SKILL.md b/packages/claude-directory/skills/google-ads-quality-score/SKILL.md deleted file mode 100644 index 09580dc..0000000 --- a/packages/claude-directory/skills/google-ads-quality-score/SKILL.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -name: google-ads-quality-score -description: Diagnose and improve Google Ads Quality Score — Expected CTR, Ad Relevance, and Landing Page Experience — to cut CPCs and lift Ad Rank. Use when CPCs look high for the vertical, impression share is capped by rank, or keywords sit at QS 5 and below. ---- - -# Google Ads Quality Score - -Quality Score is a keyword-level 1-10 diagnostic built from three rated components: Expected CTR, Ad Relevance, and Landing Page Experience. Low QS means you pay more per click for the same position — fixing the weakest component is the cheapest CPC reduction available. - -Confirm the account: `list_connected_accounts`. - -## 1. Pull QS with spend context - -Use `pull_google_ads_performance` and `audit_account_structure` to prioritize campaign issues. Request a Google Ads export for keyword-level Quality Score and its components if the returned data lacks them. Never infer a component score from campaign averages. - -Rank the fix list by cost, not by QS: a QS 3 keyword spending $4K/month matters more than twenty QS 4 keywords spending nothing. Pull the below-average components on the highest-spend keywords first. - -## 2. Read the components - -- **Expected CTR below average**: your ad gets clicked less than competitors' for the same query. Ad copy problem. -- **Ad Relevance below average**: the ad text does not match the keyword's intent. Structure problem. -- **Landing Page below average**: slow, thin, or mismatched page. Post-click problem. - -Rough mechanics worth knowing: Ad Rank scales with bid times quality, and actual CPC is the ad rank of the advertiser below you divided by your quality. Moving a keyword from QS 4-5 to QS 7 typically cuts its CPC on the order of 25-30% — quantify the monthly savings before recommending work. - -## 3. Fix Expected CTR - -Write RSA variants with `create_ad_copy`: use relevant keywords, concrete differentiators, and distinct headlines. Compare current text and asset counts using `list_creative_assets` where available, or request a platform export. Follow **launch** before any deployment. - -## 4. Fix Ad Relevance - -Restructure to tightly themed ad groups: if no headline in the ad group contains the keyword or a close synonym, the keyword is in the wrong ad group. Split mixed-intent groups (one theme per group), then write ads that name the theme. Keyword insertion helps only when the group is already tight. Expect 1-2 weeks after restructuring. Query bleed between groups is a negatives problem — see **negative-keywords**. - -## 5. Fix Landing Page Experience - -- Speed: LCP under 2.5s, mobile-usable, no intrusive interstitials. -- Message match: page headline mirrors the ad promise; ad-group keywords appear in the page copy above the fold. -- Trust: HTTPS, visible contact info, clear offer details and policies. - -If the page needs replacing, provide a copy and usability brief for the site owner. The plugin does not publish landing pages. Recheck the destination before launch. - -## 6. Track it over time - -Google keeps no QS history, so snapshot weekly with the same GAQL query and track impression-weighted average QS, percent of spend on QS 7+ keywords, and percent of keywords at QS 3 and below. Report movement against those, not single-keyword anecdotes. - -## Rules - -- Prioritize by wasted spend, not by score. Fix the expensive keywords first. -- Competitor-brand keywords naturally sit at QS 3-5; judge them on CPA, not QS. -- One component per ad group per cycle, then wait for the rating to update before layering more changes. -- QS is a diagnostic, not an auction input — never chase 10/10 on keywords that already hit CPA targets. Bid moves belong to **bid-optimization**. diff --git a/packages/claude-directory/skills/google-shopping-optimizer/SKILL.md b/packages/claude-directory/skills/google-shopping-optimizer/SKILL.md deleted file mode 100644 index 6f80228..0000000 --- a/packages/claude-directory/skills/google-shopping-optimizer/SKILL.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -name: google-shopping-optimizer -description: Optimize Google Shopping — product feed quality, titles, Merchant Center disapprovals, supplemental feeds, custom-label segmentation, and Shopping vs Performance Max structure. Use when Shopping impression share is low, products are disapproved, or feed titles and labels need work. ---- - -# Google Shopping Optimizer - -Shopping performance is mostly feed quality. Fix titles, identifiers, images, and price accuracy before touching bids or structure. - -Confirm the account with `list_connected_accounts`. Pull campaign performance with `pull_google_ads_performance`; request Merchant Center or Google Ads exports for product-level data not returned. - -## 1. Audit the feed - -Export the feed and check, in order of revenue contribution: - -- Missing GTINs on branded products (required; use `identifier_exists = false` only for genuinely custom or handmade items). -- Short titles (under ~70 characters) missing brand, product type, or key attributes. -- Thin descriptions, missing `google_product_category` or `product_type`. -- Main images with watermarks, text overlays, or lifestyle shots where a white-background product shot belongs (800x800+ recommended). -- Feed price or availability that does not match the landing page — the top disapproval cause. - -Grade each top product: optimized, needs work, or at risk of disapproval. Fix by revenue, not alphabetically. - -## 2. Rewrite titles - -Structure: Brand + Product Type + Key Attributes (color, size, material, gender) + Model/Variant. Front-load the important terms — Shopping truncates around 70 characters. No ALL CAPS, no promo text ("SALE", "SPECIAL OFFER"), no symbols. Aim for 70-100 characters, max 150. - -## 3. Clear disapprovals - -Triage by reason, fastest first: - -- **Price/availability mismatch**: sync feed to page, enable automated item updates. Instant class of fix. -- **Missing GTIN/MPN**: bulk-add via supplemental feed; source GTINs from the manufacturer or GS1. -- **Image issues**: replace with clean white-background images; product should fill most of the frame. -- **Policy violations**: check the landing page and image against the restricted-content policies (see **campaign-preflight** before relaunch). - -Request re-review; most complete within 24-72 hours. Track reinstatement rate weekly. - -## 4. Use supplemental feeds for speed - -A supplemental feed (a connected sheet keyed on product `id`) overrides primary-feed values without touching the source system. Use it to fix titles, add GTINs, set `sale_price`, and stamp custom labels — same-day fixes instead of waiting on a feed pipeline. - -## 5. Segment with custom labels - -The five `custom_label` slots are your only campaign-structure handles. A workable scheme: label 0 = performance tier (hero / mid / long tail by trailing revenue), label 1 = margin tier, label 2 = seasonality, label 3 = price band, label 4 = competitive price position. Then structure campaigns by label — hero products get the budget and the aggressive ROAS target, long tail runs cheap. Apply budget moves with `update_campaign_budget` and cross-product allocation with `optimize_budget`. - -## 6. Shopping vs Performance Max - -- **Standard Shopping**: full search-term visibility, campaign-level negatives, product-level bid control. Best for mature accounts that need control. -- **PMax**: all Google channels, better new-product discovery, but limited query visibility and account-level negatives only. Best for growth and catalog breadth — see **performance-max-optimizer**. -- The usual right answer is hybrid: Standard Shopping on hero SKUs, PMax on the rest of the catalog, compare ROAS by product group after 30 days. Watch for PMax eating brand queries when comparing. - -## Rules - -- Feed fixes before bid fixes. A bad title wastes every dollar bid behind it. -- Price mismatch is the one issue that gets accounts suspended — verify it first and keep automated item updates on. -- Never put promotional text or watermarks on main images. -- State expected impact and timeline for each fix batch, then re-check impression share after two weeks. diff --git a/packages/claude-directory/skills/incrementality-testing/SKILL.md b/packages/claude-directory/skills/incrementality-testing/SKILL.md deleted file mode 100644 index f0ed5f5..0000000 --- a/packages/claude-directory/skills/incrementality-testing/SKILL.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -name: incrementality-testing -description: Design and run incrementality tests that measure true lift from ads — geo holdouts, platform lift studies, significance math, and iCPA decisions. Use when a user wants to know whether ads actually cause conversions, design a holdout test, or decide budget based on real lift. ---- - -# Incrementality Testing - -Attribution measures correlation; incrementality measures causation. The question is always the same: would this conversion have happened without the ad? - -Start with `measure_incrementality` where the platform and data support it; design a manual test when it does not. - -## 1. Define the question - -Pick one testable claim: channel incrementality ("does Display drive anything?"), budget incrementality ("does doubling spend double conversions?"), or tactic incrementality ("is retargeting real?"). One variable per test. Pull the baseline first: the supported performance tools (`pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_microsoft_ads_performance`, `pull_reddit_ads_performance`) for spend and attributed conversions, `ga4_get_report` for a platform-neutral conversion count. - -## 2. Choose the method - -- **Geo holdout:** run ads in test regions, go dark in matched control regions. The gold standard, but needs regional volume. Pause delivery in control geos via `pause_campaign` or geo exclusions. -- **Platform lift study:** Meta and Google both offer native conversion-lift experiments with randomized holdout groups. Least effort, but you trust the platform to grade its own homework. -- **Ghost ads / PSA:** serve an unrelated ad to the control group so both groups pass through the same auction. Works on any platform, costs the PSA impressions. - -## 3. Design it so the answer is trustworthy - -- **Match regions** on population, historical CVR, revenue per conversion, and seasonality. Validate with 8-12 weeks of history: if historical CVRs differ by more than ~5%, pick different regions. -- **Size the control** at 20-30% of the addressable market. -- **Duration:** minimum 4 weeks for most channels; 2 weeks only for high-volume search or Meta; add 50-100% for long sales cycles. Avoid holidays or extend through them. -- **Sample size:** small lifts need big audiences. Detecting a 20% lift on a 1% baseline CVR takes roughly 400K users; a 10% lift takes 1.5M. If you cannot reach the numbers, test a bigger intervention instead of a subtle one. - -## 4. Run it clean - -Keep other inputs stable during the test: avoid creative swaps, unrelated budget changes, or new campaigns in test/control markets. Read `list_campaigns` regularly to catch drift and measure outcomes with GA4. Configure any automated alerts in the platform UI. - -## 5. Analyze - -``` -Lift = (CVR_test - CVR_control) / CVR_control -Incremental conversions = Conversions_test - (Exposed_test x CVR_control) -iCPA = Test spend / Incremental conversions -iROAS = Incremental revenue / Test spend -``` - -Run a two-proportion z-test on test vs control CVR and report the lift with its 95% confidence interval, not just the point estimate. A lift whose interval crosses zero is not a result. - -## 6. Decide - -Compare iCPA to attributed CPA: - -- **iCPA within ~1.5x of CPA:** highly incremental. Scale it (see **kill-scale-rules**). -- **1.5-3x:** moderately incremental. Hold and optimize. -- **3-5x:** weak. Shift budget with `optimize_budget` and re-test the reallocation. -- **5x+:** the channel is mostly claiming credit for organic conversions. Cut it or keep it only for awareness. - -Brand search typically tests at 15-35% incrementality, non-brand search 40-65%, display prospecting 5-20%, retargeting 20-45%. If your result lands far outside these ranges, re-check the test before celebrating or panicking. - -## Rules - -- One variable per test. A test that changes budget, creative, and audience proves nothing. -- Neutral measurement only. The platform being tested does not get to score the test. -- Pre-register the success threshold before launch; do not move the goalposts after seeing data. -- Feed results back into planning: incrementality-adjusted returns belong in **mmm-budget-planner** and **attribution** conversations, not in a slide graveyard. diff --git a/packages/claude-directory/skills/keyword-research/SKILL.md b/packages/claude-directory/skills/keyword-research/SKILL.md deleted file mode 100644 index d90e434..0000000 --- a/packages/claude-directory/skills/keyword-research/SKILL.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -name: keyword-research -description: Find high-intent, low-waste keywords for Search campaigns and add them to the right ad groups. Use when a user wants keyword ideas, to expand a Search campaign, improve targeting, or find terms to bid on for Google or Microsoft Ads. ---- - -# Keyword Research - -Find terms real buyers search, group them by intent, and add them where they convert. Reads do not require approval; adding keywords to a live campaign is a change, so confirm before shipping. - -Confirm the account: `list_connected_accounts`. This applies to search platforms (**platform-google**, **platform-microsoft**). - -## 1. Start from intent, not volume - -Anchor to the conversion that defines success. Sort candidate terms by buyer intent: -- **High intent:** problem-aware, ready to act ("buy", "near me", branded competitor terms). -- **Research intent:** comparing, not yet buying. Lower priority unless the funnel supports nurture. -- **Junk:** informational or off-topic. These become negatives, not keywords. See the **negative-keywords** skill. - -## 2. Mine what already works - -Use `research_campaign_opportunity` and available `pull_google_ads_performance` or `pull_microsoft_ads_performance` history. Request a platform search-term export if query-level detail is missing. Separate observed converting queries from proposed keywords; do not invent query performance. - -## 3. Assign match types deliberately - -- **Exact** for proven converters you want control over. -- **Phrase** for controlled expansion. -- **Broad** only with strong negatives and conversion tracking, never naked. - -## 4. Add on approval - -Draft supported keyword entities with `upsert_plan_entity` and follow **launch** for review, preflight, approval, execution, and verification. Use the platform UI if keyword edits are unsupported. Pair expansions with exclusions and verify tracking with `ga4_get_conversions` and **conversion-tracking**. - -## Rules - -- Group by intent and theme so RSAs stay relevant; relevance is what earns cheaper clicks. -- Never add broad match without negatives and tracking. -- Report the terms added and the ad group they landed in with real IDs. diff --git a/packages/claude-directory/skills/kill-scale-rules/SKILL.md b/packages/claude-directory/skills/kill-scale-rules/SKILL.md deleted file mode 100644 index f03d394..0000000 --- a/packages/claude-directory/skills/kill-scale-rules/SKILL.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -name: kill-scale-rules -description: Decide whether to kill or scale a campaign, ad set, or creative, with minimum-data guardrails and platform-safe budget-step limits. Use when a user asks whether to pause, cut, kill, scale, or increase budget on something, or wants rules for when to do it. ---- - -# Kill or Scale - -The two decisions that move an account: cut what is losing, feed what is winning. Both fail when made too early or too hard. Reads do not require approval; pausing or scaling spends differently, so confirm before shipping. - -Confirm the account: `list_connected_accounts`. - -## Minimum data first - -Never kill or scale on noise. Require enough conversions and enough time for the platform to have learned. For a new ad set still in Meta's Learning Phase, or a Search campaign with a handful of clicks, the answer is usually "wait", not "cut". Run **pre-pause-analysis** before pausing anything. - -## When to kill - -- Real spend, enough conversions to judge, CPA well above target with no fixable cause (targeting, negatives, creative, tracking all checked). -- Creative fatigue past recovery (rising frequency, falling CTR) that rotation will not fix (see **creative-fatigue-detector**). -- Before you pause, confirm it is not a tracking or geo problem masquerading as poor performance. - -## When to scale - -- Consistent performance at or below target CPA/ROAS with volume, held across enough days. -- Room to grow (impression share lost to budget, or audience not saturated). - -## Scale in safe steps - -Raise budget in increments, not leaps. Large jumps reset learning and can spike CPM or CPA. Increase, hold, re-measure, increase again. Match the step to the platform and the ad set's stability. Use `update_campaign_budget` and confirm. - -## Rules - -- Minimum data before any kill or scale call. State the window and volume. -- Rule out tracking, geo, and creative before blaming the campaign. -- Report the decision, the evidence, and the step taken. Scaling is a separate, approved action every time (see **optimize**). diff --git a/packages/claude-directory/skills/launch/SKILL.md b/packages/claude-directory/skills/launch/SKILL.md deleted file mode 100644 index 83e25ce..0000000 --- a/packages/claude-directory/skills/launch/SKILL.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -name: launch -description: Plan and launch a cross-platform ad campaign — strategy, targeting, creative, budget, and preflight — then ship it on the user's approval. Use when a user wants to launch, build, or run a new campaign on one or more platforms (Google, Meta, LinkedIn, Reddit). ---- - -# Launch a Campaign - -Take the user from intent to a live campaign. Plan it, show it, ship it on their word. You direct nothing on your own — every spend-creating step waits for explicit approval. - -## 1. Scope it - -Get the brief in plain English, then pin down what you need: - -- **Objective** (leads, signups, sales, awareness) and the **conversion** that defines success. -- **Platform(s)** — recommend the mix; don't just take the first one named. -- **Audience** — who, where. If it needs building, run the **audience** skill first. -- **Budget** — daily/total, and the **target CPA/ROAS**. -- **Landing page / final URL** and the offer. - -Confirm the account with `list_connected_accounts`. Check conversion evidence with `ga4_get_conversions`, `ga4_get_report`, and `get_pixel_health`. Resolve missing verification before launching. - -## 2. Plan it - -Use `create_campaign_plan` to draft structure (campaigns → ad sets → ads), add supported entities with `upsert_plan_entity`, then `forecast_campaign` for reach/CPM/CPC/CPA projections. For the channel mix and budget split, lean on platform cost benchmarks and a clear rationale. - -Write text with `create_ad_copy` and select existing approved assets with `list_creative_assets`. Use the verified advertiser’s voice, logos, colors, and destination; see `../../context/brand-and-safety.md`. - -## 3. Preflight — before anything goes live - -Read the complete plan with `get_campaign_plan` and run `run_launch_preflight`. Resolve failures, then show the exact final plan and report pass/fail: - -- Geo targeting correct, exclusion lists applied. -- Conversion tracking firing and attached to the right action. -- Budget and bid caps sane — guard against fat-finger budgets (a daily budget that's 10–100x intended is the classic incident). -- Creative passes platform policy (`ad-policy-compliance` thinking) and brand rules. -- Final URL resolves and matches the ad's promise. - -## 4. Ship on approval - -Show the full plan — platform, audience, budget, creative, projected CPA — and ask for a clear go. Only then: - -- Record the user’s approval with `approve_campaign_plan`, then use `execute_campaign_plan`. Check `get_plan_execution` and, if a job ID is returned, `get_job_status`. Use `enable_campaign` only when activation is within the user-approved scope. -- For multi-platform, ship each platform and confirm each one back with its real campaign ID. - -Then confirm live: `list_campaigns(platform=...)` and report the IDs created. "Created" and "live and spending" are different claims — verify before you say it's running. - -## House rules - -- Nothing that spends money ships without explicit approval. Default to recommend-then-execute. -- ALWAYS call `list_connected_accounts` or `get_connection_status` first to validate the target Account ID and Account Name on multi-account setups. -- Whenever reporting back, you MUST explicitly include the **Platform**, **Account Name**, and **Account ID** (e.g. `Google Ads: Acme Corp (ID: 123-456-7890)`). -- Use real account IDs returned by the tools — never invent them. -- Start conservative on budget; scale winners later with the **optimize** skill. - diff --git a/packages/claude-directory/skills/meta-ads-diagnostics/SKILL.md b/packages/claude-directory/skills/meta-ads-diagnostics/SKILL.md deleted file mode 100644 index a82bbbb..0000000 --- a/packages/claude-directory/skills/meta-ads-diagnostics/SKILL.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -name: meta-ads-diagnostics -description: Diagnose Meta Ads delivery and performance problems — Learning Phase stalls, creative fatigue, audience overlap, CPM spikes, and Advantage+ vs manual structure. Use when a Meta campaign underperforms, delivery is limited, or CPMs and frequency are climbing. ---- - -# Meta Ads Diagnostics - -Find the real cause before touching the campaign. Most Meta "performance problems" are one of four things: learning starvation, creative fatigue, audience self-competition, or a post-click issue. - -Confirm the account: `list_connected_accounts`, then pull data with `pull_meta_ads_performance(days=30, level="ad-set")` and at ad level for creative checks. - -## 1. Check Learning Phase first - -Meta needs roughly 50 optimization events per ad set per week to stabilize. Under that, CPA runs volatile and high, and no other diagnosis is reliable. - -- Learning resets on: budget moves over ~20%, bid changes, new creatives, targeting edits, optimization-event changes, or a pause longer than 7 days. -- Stuck in Learning Limited: consolidate ad sets so events pool, broaden the audience, raise budget toward 10x target CPA, or optimize to a higher-volume event (Add to Cart instead of Purchase). -- If it launched or changed within the last 7 days: do not touch it. Wait. - -## 2. Test for creative fatigue - -Pull daily impressions, reach, frequency, and CTR for the last 30 days. Compute fatigue as the CTR decline from the first full week to now: - -- Under 15% decline: healthy. -- 15-30%: early fatigue, prepare a refresh. -- 30-50%: rotate creatives now. -- Over 50%: pause and replace. - -Frequency confirms it: prospecting past ~3.0 or retargeting past ~5.0 with falling CTR is fatigue, not audience quality. Refresh in proportion — copy swap for mild decline, new visual angle for moderate, new concept or format change for severe. Build replacements with the **ad-copy-generation** skill and validate with **creative-testing**. - -## 3. Check audience overlap - -Symptoms: CPMs rising on multiple ad sets at once, frequency climbing faster than spend justifies, two ad sets going Learning Limited together, one ad set starving the other. - -- Under ~10% overlap: ignore. 10-25%: watch CPMs. Over 25%: exclude one audience from the other or merge the ad sets. Over 50%: consolidate immediately. -- Consolidation into fewer, broader ad sets usually beats exclusion lists — it also fixes learning starvation at the same time. - -## 4. Respect the breakdown effect - -Per-placement or per-demo breakdowns lie. Meta optimizes holistically, so a placement with an ugly standalone CPA may be feeding cheap assists to the placements that convert. Never cut a placement off breakdown data alone — measure it properly with `measure_incrementality` or leave it on. Give the algorithm 14+ days with all placements before judging. - -## 5. Advantage+ vs manual structure - -- Advantage+ Shopping fits: product catalog, 100+ conversions/week, broad targeting, simple purchase goals. Set an existing-customer budget cap (20-30%) and feed it 5-10 diverse creatives. -- Manual fits: B2B lead gen, narrow audiences, heavy exclusions, under ~50 conversions/week, or when you need creative-level budget control. -- When testing ASC against manual, run both at equal budget for 14+ days and compare CPA, ROAS, and new-customer share before consolidating. - -## 6. Decision tree for the rest - -Diagnose in order: delivery status, frequency and fatigue, auction pressure, landing-page conversion, then tracking. Use `get_pixel_health` and **conversion-tracking** for available tracking evidence. - -Apply approved pauses or budget changes with `pause_campaign` or `update_campaign_budget`. Select existing replacements with `list_creative_assets` and follow **launch** for supported plan changes. Kill/scale decisions use **kill-scale-rules**. - -## Rules - -- Never diagnose a campaign still in Learning Phase; fix event volume first. -- One change at a time — every edit can reset learning. -- Breakdown data is directional, not causal. Incrementality beats breakdowns. -- State the data window and event counts behind every recommendation. diff --git a/packages/claude-directory/skills/mmm-budget-planner/SKILL.md b/packages/claude-directory/skills/mmm-budget-planner/SKILL.md deleted file mode 100644 index 6ef03ec..0000000 --- a/packages/claude-directory/skills/mmm-budget-planner/SKILL.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -name: mmm-budget-planner -description: Plan and reallocate budget across platforms by ROI, with revenue projections and shift scenarios. Use when a user asks where to put budget across channels, the true ROI of each channel, what happens if they move spend from one platform to another, or how campaigns are pacing. ---- - -# Budget Planner - -Decide where the next dollar goes across platforms, grounded in real performance rather than gut feel. Reads do not require approval; changing budgets is a change and waits for explicit approval. - -Confirm the account and what is connected: `list_connected_accounts`. - -## 1. Read cross-platform performance - -Pull recent performance per platform so the plan sits on real numbers: - -- Use `pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_microsoft_ads_performance`, and `pull_reddit_ads_performance` for available spend, conversions, and CPA by channel. -- `get_attribution` to see how conversions credit across touchpoints, not just last click. -- `measure_incrementality` where a holdout exists, to separate true lift from spend that would have converted anyway. This is the honest answer to "what is this channel really worth." - -## 2. Reallocate by ROI - -Use `optimize_budget` for a proposed allocation within the user’s total and per-channel limits supported by its schema. Treat the result as a recommendation until the exact changes are approved and applied. - -Read the output as a plan, not a command: - -- Every channel has diminishing returns. Pouring the whole budget into the current best performer stops working once it saturates. Keep a spread. -- Compare the proposed allocation to the current one and show the delta and the expected improvement. -- Model shifts explicitly: "move X from platform A to platform B" and what the projected CPA/return does. Keep the math visible. - -## 3. Project and pace - -- Use recent trend plus the proposed allocation to project the next few weeks of spend and conversions, with a clear range rather than a false-precision single number. -- Flag channels pacing over or under budget so nothing quietly runs away or underspends. - -## 4. Ship on approval - -Show the current split, proposed split, projected outcome, and rationale. Change budgets only on explicit approval with `update_campaign_budget`, or follow **launch** for an approved plan. Guard against mistaken amounts. Confirm the new settings with `list_campaigns` and monitor subsequent performance. - -For single-account bid and pacing tuning rather than cross-platform allocation, use the **optimize** and **bid-optimization** skills. For pure ROAS and CPA math, use the **roas-calculator** skill. diff --git a/packages/claude-directory/skills/optimize/SKILL.md b/packages/claude-directory/skills/optimize/SKILL.md deleted file mode 100644 index 4b11e42..0000000 --- a/packages/claude-directory/skills/optimize/SKILL.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -name: optimize -description: Improve campaign performance — reallocate budget by ROAS, recommend bid changes for manual application, kill losers and scale winners, and catch anomalies across platforms. Use when a user wants to cut wasted spend, improve ROAS/CPA, rebalance budget, or act on what's underperforming. ---- - -# Tune & Reallocate - -Find the wasted spend and the winners, then act on the user's approval. - -## 1. Pull the truth - -Get recent performance across the connected platforms: -Use `pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_reddit_ads_performance`, and `pull_microsoft_ads_performance`. Request exports for other platforms. Use `get_spend_reconciliation` to compare sources and `get_attribution` to investigate conversion credit. - -## 2. Diagnose - -- **Wasted spend**: campaigns/ad sets/creatives spending with no conversions past a minimum-data threshold. -- **Winners**: low CPA / high ROAS with enough volume to scale. -- **Anomalies**: spend spikes, CTR drops, budget runaway — flag before they compound. -- **Fatigue**: rising frequency with falling CTR → creative needs rotation (run the **ad-copy-generation** skill). - -Respect minimum-data guardrails — don't kill or scale on noise. State the threshold you used. - -## 3. Recommend, then act - -Present a clear plan: what to cut, what to scale, where the freed budget goes, and the expected effect. - -- `optimize_budget` — propose a cross-platform allocation for review. -- `update_campaign_budget` — set a specific budget (guard against fat-finger amounts; default to sane ceilings). -- `pause_campaign` — kill a loser. -- Bid-strategy changes: recommend them and hand off to the platform UI. - -Scale winners in steps (platform-appropriate budget increments), not all at once — big jumps reset the learning phase. - -## 4. Confirm - -After acting, re-pull the data and report the new state. Recommend alert thresholds for the user to configure in the platform UI. - -## House rules - -- Always validate connected Account IDs (`get_connection_status`) first. Explicitly state the **Platform**, **Account Name**, and **Account ID** (e.g. `Google Ads: Acme Corp (ID: 123-456-7890)`) when reporting optimizations and state changes. -- Every budget/pause/bid change needs explicit approval. Recommend-then-execute by default. -- Minimum-data guardrails before any kill-or-scale call. -- Never report a change as done without confirming it landed. - diff --git a/packages/claude-directory/skills/performance-max-optimizer/SKILL.md b/packages/claude-directory/skills/performance-max-optimizer/SKILL.md deleted file mode 100644 index 0c32a70..0000000 --- a/packages/claude-directory/skills/performance-max-optimizer/SKILL.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -name: performance-max-optimizer -description: Optimize Google Ads Performance Max — asset group structure, asset performance labels, audience signals, search term insights, negatives, and channel allocation. Use when managing or auditing PMax campaigns, replacing Low assets, or diagnosing where PMax spend actually goes. ---- - -# Performance Max Optimizer - -PMax gives up query and placement control, so you steer it with the three inputs you still own: assets, audience signals, and the feed. Optimize those; don't fight the black box. - -Confirm the account with `list_connected_accounts`, then use `pull_google_ads_performance` and `audit_account_structure`. Request platform exports when asset or query-level details are missing. - -## 1. Fill every asset slot - -Inventory approved assets with `list_creative_assets` and write missing text with `create_ad_copy`. Request any missing images, logos, or video from the advertiser. Review asset completeness and brand consistency before following **launch**. - -## 2. Replace Low assets on a cycle - -Review asset performance labels in a Google Ads export if they are absent from the tool results. Do not infer asset-level labels from campaign performance. - -- BEST: keep, and spin 2-3 close variations off it. -- GOOD: keep and monitor. -- LOW: replace within 2-4 weeks with variants of your BEST assets. -- LEARNING / PENDING: wait 2+ weeks before judging. - -Replace 1-2 assets at a time and never wipe a whole asset type at once. Validate concepts with **creative-testing** before rolling them across groups. - -## 3. Mine search term insights and cut waste - -Review a platform search-category export for irrelevant or unprofitable traffic. Propose negatives with **negative-keywords**, verify current platform support, and have the account owner apply unsupported changes in the platform UI. - -The most expensive miss: brand queries. If insights show a large brand share, PMax is buying conversions your brand campaign gets cheaper — add brand terms as account-level negatives and let the brand campaign recover. - -## 4. Feed audience signals, not audience targets - -Signals guide initial learning; PMax expands beyond them. Stack them by strength: - -- Review customer and high-value purchaser lists with `list_audiences`. Have the account owner create or refresh lists in the platform UI before using them in supported campaign-plan fields. -- Custom segments from high-intent search terms and competitor URLs (50-100 entries each). -- Site visitors and cart abandoners from GA4 (`ga4_get_report` to size them). -- Interests and demographics last, as seasoning only. - -After 30 days, check which segments convert and whether expansion aligns with them. Deeper audience work lives in **audience**. - -## 5. Check channel allocation - -Use a platform channel export when the performance response lacks channel breakdowns. Compare conversion value and spend by channel before recommending a reallocation: - -- Display bloated with weak CVR: audience signals too loose — add purchase-intent custom segments. -- Search share mostly brand: negate brand at account level. -- Shopping share low for a catalog business: feed quality problem — see **google-shopping-optimizer**. -- Zero YouTube: you have no video asset; add one. - -## 6. Structure asset groups by intent - -One asset group per coherent product/audience theme, each with its own listing group filter and matched signals — not one mega-group. Use custom labels on the feed to split hero, seasonal, and long-tail products across groups. Budget and target changes go through `update_campaign_budget` and **bid-optimization**; give the campaign 2+ weeks after any target move. - -## Rules - -- Never judge PMax in its first 2-3 weeks or right after a target/budget change. -- Brand traffic makes PMax look better than it is — always separate brand before reading ROAS. -- Change one input class per cycle (assets, signals, negatives, or targets), then wait. -- Report channel mix and asset-label distribution, not just topline ROAS. diff --git a/packages/claude-directory/skills/platform-amazon/SKILL.md b/packages/claude-directory/skills/platform-amazon/SKILL.md deleted file mode 100644 index 1048fe4..0000000 --- a/packages/claude-directory/skills/platform-amazon/SKILL.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -name: platform-amazon -description: Amazon Ads and Amazon DSP playbook — Sponsored Products/Brands/Display, ACOS/TACOS, retail readiness, and programmatic. Use when planning, reading, auditing, or launching Amazon Ads or DSP, or porting a campaign to Amazon. ---- - -# Amazon Ads and DSP - -Two motions: Sponsored ads on the retail search results, and DSP for programmatic reach on and off Amazon. Retail readiness gates everything: an ad on a weak product page burns budget. - -## Read what exists - -- `list_connected_accounts`, then `list_campaigns(platform="amazon")`. -- Dedicated performance reads for this platform are outside the plugin’s directory tools. Request a platform export for metrics and use `list_campaigns` for the state and fields actually returned. Do not substitute another platform’s data. - -## Sponsored ads - -- **Sponsored Products** for individual listings, **Sponsored Brands** for brand and portfolio, **Sponsored Display** for on- and off-Amazon retargeting. -- The core metric is **ACOS** (ad spend / ad sales); watch **TACOS** (ad spend / total sales) to see whether ads are growing the whole business or just shifting organic sales. -- Mine search terms, keep negatives tight, and structure by product intent. Do not scale a campaign pointing at a page with thin content, bad images, or no reviews. - -## Amazon DSP - -- Review existing audiences with `list_audiences`. Use `research_campaign_opportunity` for available campaign research. Ask the account owner to create or synchronize new audience lists in the platform UI; use returned IDs only in supported plan fields. - -## Plan and ship - -- Build with `create_campaign_plan` + `upsert_plan_entity`; `forecast_campaign` for projections. Run **campaign-preflight**: retail readiness, tracking, sane budgets. -- Ship only on explicit approval: `execute_campaign_plan`, then `enable_campaign`. Nothing that spends money goes live without a clear go. Apply brand voice from `../../context/brand-and-safety.md`. -- Confirm live with `list_campaigns(platform="amazon")` and report the real ID. Scale by ACOS with the **optimize** skill. - -Porting from another platform? Use the **replicate** skill. Search intent maps to Sponsored Products keywords; audiences map to DSP. - -Use only platform and entity types accepted by the live tool schema. Follow **launch** for plan review, preflight, approval, execution, and verification. If a setting or platform is unsupported, describe the manual handoff without claiming it was applied. diff --git a/packages/claude-directory/skills/platform-google/SKILL.md b/packages/claude-directory/skills/platform-google/SKILL.md deleted file mode 100644 index 3d534f5..0000000 --- a/packages/claude-directory/skills/platform-google/SKILL.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -name: platform-google -description: Operate Google Ads through Synter — read and build Search, Performance Max, Display, Demand Gen, and Video campaigns, with the right structure, match types, negatives, geo, and bid strategy. Use when a user is working on Google Ads, asks about Search/PMax/Shopping, or wants to read or change a Google campaign. ---- - -# Google Ads Playbook - -How Google Ads is shaped and how to operate it through Synter. Reads do not require approval; anything that spends money waits for explicit approval. - -Confirm the account first: `list_connected_accounts`. Use the real customer ID the tool returns; never invent one. Not connected → run the **connect** skill. - -## Structure - -- **Search:** campaign → ad group → keywords (with match types: exact, phrase, broad) → responsive search ads (RSAs, up to 15 headlines / 4 descriptions, some pinned). Negatives live at campaign and ad-group level and matter as much as the keywords. -- **Performance Max:** campaign → asset groups + audience signals. No keywords; goals and conversion data drive it. -- **Display / Demand Gen / Video:** campaign → ad group → audiences + creative. Video runs on YouTube. -- Campaign settings that must be right: budget, bid strategy, networks, geo/location criteria, languages, ad schedule. - -## Read a campaign - -Use `list_campaigns` for returned campaign IDs and settings, `audit_account_structure` for available structure checks, and `pull_google_ads_performance` for performance. Request a Google Ads export for detailed targeting, keyword match types, negatives, or asset data that the tools do not return. - -## Build a campaign - -Use `create_campaign_plan` and `upsert_plan_entity` for the supported campaign structure, and `forecast_campaign` for available estimates. Write text with `create_ad_copy` and select existing advertiser assets with `list_creative_assets`. Follow **launch** for `run_launch_preflight`, explicit user approval, `approve_campaign_plan`, `execute_campaign_plan`, and verification with `get_plan_execution` before any approved activation. - -## Operating rules - -- Keep match types deliberate. Broad without good negatives and conversion tracking wastes budget fast. -- Geo is the classic miss: a "US" campaign with no location criteria serves everywhere. Verify location criteria exist and match intent. -- Conversion tracking must exist and be attached before scaling: `ga4_get_conversions`, `get_pixel_health`. Blind spend is worse than no spend. -- Guard budgets against a fat-finger daily amount 10 to 100x intended. -- Adjust budgets with `update_campaign_budget`; pause with `pause_campaign`. Start conservative; scale winners with the **optimize** skill. -- "Created" is not "live and spending." Confirm with `list_campaigns` and report the real IDs. - -Use only platform and entity types accepted by the live tool schema. Follow **launch** for plan review, preflight, approval, execution, and verification. If a setting or platform is unsupported, describe the manual handoff without claiming it was applied. diff --git a/packages/claude-directory/skills/platform-linkedin/SKILL.md b/packages/claude-directory/skills/platform-linkedin/SKILL.md deleted file mode 100644 index 58be634..0000000 --- a/packages/claude-directory/skills/platform-linkedin/SKILL.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -name: platform-linkedin -description: Operate LinkedIn Ads through Synter — read and build B2B campaigns with job-title, company, and ABM targeting, the right ad format, and realistic CPL expectations. Use when a user is working on LinkedIn ads, B2B lead gen, or account-based targeting. ---- - -# LinkedIn Ads Playbook - -LinkedIn is the B2B platform: precise professional targeting, higher costs, longer consideration. How it is shaped and how to operate it through Synter. Reads do not require approval; anything that spends money waits for explicit approval. - -Confirm the account first: `list_connected_accounts`. Use the real ID the tool returns; never invent one. Not connected → run the **connect** skill. - -## Structure - -Campaign group → campaign (objective, audience, budget, schedule) → ad. Targeting is the core lever: job title and function, seniority, company, company size, industry, and skills. Keep audiences tight enough to be relevant but large enough to deliver. - -- Review existing audiences with `list_audiences`. Use `research_campaign_opportunity` for available campaign research. Ask the account owner to create or synchronize new audience lists in the platform UI; use returned IDs only in supported plan fields. -- **Formats:** single-image, document, video, and conversation/message formats. Match the format to the funnel stage. - -## Read a campaign - -Use `list_campaigns` for IDs and state and `pull_linkedin_ads_performance` for campaign metrics. Request a platform export for company-level engagement if needed. - -## Build a campaign - -Use `create_campaign_plan` and `upsert_plan_entity` for the supported campaign structure, and `forecast_campaign` for available estimates. Write text with `create_ad_copy` and select existing advertiser assets with `list_creative_assets`. Follow **launch** for `run_launch_preflight`, explicit user approval, `approve_campaign_plan`, `execute_campaign_plan`, and verification with `get_plan_execution` before any approved activation. - -## Operating rules - -- Expect higher CPL than other platforms. Judge LinkedIn on pipeline quality and downstream conversion, not raw CPC. -- Keep targeting to decision makers where the offer warrants it; do not spray a broad seniority range on an expensive platform. -- Give campaigns room before judging; B2B conversion windows are long. Follow **pre-pause-analysis** before cutting. -- Conversion tracking (Insight Tag and offline/CRM conversions) must be attached before scaling: `get_pixel_health`, `ga4_get_conversions`. Measure with `get_attribution`. -- Guard against a fat-finger daily budget 10 to 100x intended. Adjust with `update_campaign_budget`, pause with `pause_campaign`. -- "Created" is not "live and spending." Confirm with `list_campaigns` and report the real IDs. Build an audience first with the **audience** skill when one does not exist yet. - -Use only platform and entity types accepted by the live tool schema. Follow **launch** for plan review, preflight, approval, execution, and verification. If a setting or platform is unsupported, describe the manual handoff without claiming it was applied. diff --git a/packages/claude-directory/skills/platform-meta/SKILL.md b/packages/claude-directory/skills/platform-meta/SKILL.md deleted file mode 100644 index 875fe1f..0000000 --- a/packages/claude-directory/skills/platform-meta/SKILL.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -name: platform-meta -description: Operate Meta (Facebook and Instagram) Ads through Synter — read and build campaigns with the right objective, ad-set structure, audiences, and creative, and handle the Learning Phase and creative fatigue. Use when a user is working on Meta, Facebook, or Instagram ads. ---- - -# Meta (Facebook / Instagram) Ads Playbook - -How Meta is shaped and how to operate it through Synter. Reads do not require approval; anything that spends money waits for explicit approval. - -Confirm the account first: `list_connected_accounts`. Use the real ID the tool returns; never invent one. Not connected → run the **connect** skill. - -## Structure - -Campaign (objective) → ad set (audience, budget, placements, schedule) → ad (creative). The objective is chosen once at the campaign level and shapes everything below it, so pick it from the conversion that defines success, not by habit. - -- Review existing audiences with `list_audiences`. Use `research_campaign_opportunity` for available campaign research. Ask the account owner to create or synchronize new audience lists in the platform UI; use returned IDs only in supported plan fields. -- **Advantage+** shifts targeting and placement decisions to Meta. Use it when data volume supports it; keep enough signal flowing. -- **Placements:** Feed, Stories, and Reels. Creative should fit the placement, not be stretched into it. - -## Read a campaign - -`list_campaigns(platform="meta")` for the list and IDs. `pull_meta_ads_performance(days=..., level="campaign")` for top line, `level="ad-set"` for audience and budget detail, `level="ad"` for creative performance. - -## Build a campaign - -Use `create_campaign_plan` and `upsert_plan_entity` for the supported campaign structure, and `forecast_campaign` for available estimates. Write text with `create_ad_copy` and select existing advertiser assets with `list_creative_assets`. Follow **launch** for `run_launch_preflight`, explicit user approval, `approve_campaign_plan`, `execute_campaign_plan`, and verification with `get_plan_execution` before any approved activation. - -## Operating rules - -- **Learning Phase:** a new ad set needs enough conversions to exit learning. Do not judge or kill it early, and do not edit it constantly; each significant edit resets learning. See the **pre-pause-analysis** discipline before cutting anything. -- **Creative fatigue:** rising frequency with falling CTR means the creative is spent. Watch it with the **creative-fatigue-detector** skill and rotate before performance collapses. -- Keep audience overlap in check; ad sets competing against each other inflate CPM. -- Conversion tracking (pixel and CAPI) must be firing and attached: `get_pixel_health`, `ga4_get_conversions`. Blind spend is worse than no spend. -- Guard against a fat-finger daily budget 10 to 100x intended. Adjust with `update_campaign_budget`, pause with `pause_campaign`. Start conservative; scale winners with the **optimize** skill. -- "Created" is not "live and spending." Confirm with `list_campaigns` and report the real IDs. - -Use only platform and entity types accepted by the live tool schema. Follow **launch** for plan review, preflight, approval, execution, and verification. If a setting or platform is unsupported, describe the manual handoff without claiming it was applied. diff --git a/packages/claude-directory/skills/platform-microsoft/SKILL.md b/packages/claude-directory/skills/platform-microsoft/SKILL.md deleted file mode 100644 index 6de4bb1..0000000 --- a/packages/claude-directory/skills/platform-microsoft/SKILL.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -name: platform-microsoft -description: Operate Microsoft (Bing) Ads through Synter — read and build Search campaigns that mirror Google, with match types, negatives, geo, schedules, and budgets, plus the real Google-to-Microsoft differences. Use when a user is working on Microsoft/Bing Ads or wants to move a Google campaign onto Microsoft. ---- - -# Microsoft (Bing) Ads Playbook - -Microsoft Ads is close to a mirror of Google Ads, which is why porting between them is common. Reads do not require approval; anything that spends money waits for explicit approval. - -Confirm the account first: `list_connected_accounts`. Use the real ID the tool returns; never invent one. Not connected → run the **connect** skill. - -## Structure - -Campaign → ad group → keywords (exact, phrase, broad) → responsive search ads, with negatives at campaign and ad-group level, plus geo/location criteria, ad schedule, and budget. If you know Google Search, you know this shape. - -## Read a campaign - -`list_campaigns(platform="microsoft")` for the list and IDs. `pull_microsoft_ads_performance(days=...)` for impressions, clicks, spend, conversions, and CPA per campaign. - -## Google to Microsoft: the differences that bite - -The structure maps almost 1:1, but do not assume it is identical: -- **Networks:** Microsoft has Search Partners and the Microsoft Audience Network. Decide whether to include them; performance can differ materially from Google search traffic. -- **Bid strategies:** some Google automated-bidding modes have no exact Microsoft twin. Map to the closest and say so. -- **Tracking templates and final-URL syntax** can differ. Verify URLs resolve on Microsoft. -- Microsoft search volume and audience skew differ from Google. Validate queries, device, and geography before scaling. - -To carry a live Google campaign across, use the **replicate** skill. It reads the Google structure completely, maps match types and negatives, and rebuilds through Synter's plan tools. Do not describe this as Microsoft's native "Import from Google" — that is a separate platform-side path. - -## Build a campaign - -Use `create_campaign_plan` and `upsert_plan_entity` for the supported campaign structure, and `forecast_campaign` for available estimates. Write text with `create_ad_copy` and select existing advertiser assets with `list_creative_assets`. Follow **launch** for `run_launch_preflight`, explicit user approval, `approve_campaign_plan`, `execute_campaign_plan`, and verification with `get_plan_execution` before any approved activation. - -## Operating rules - -- Enabling a campaign does not serve its ad groups if those stay paused. After enabling, re-pull and confirm the children actually serve; never trust the campaign status alone. -- Carry negatives across, not just keywords. Keywords without negatives burn budget. -- Verify geo/location criteria exist and match intent. -- Conversion tracking must exist and be attached before scaling: `ga4_get_conversions`, `get_pixel_health`. -- Guard against a fat-finger daily budget 10 to 100x intended. Adjust with `update_campaign_budget`, pause with `pause_campaign`. -- "Created" is not "live and spending." Confirm with `list_campaigns` and report the real IDs. - -Use only platform and entity types accepted by the live tool schema. Follow **launch** for plan review, preflight, approval, execution, and verification. If a setting or platform is unsupported, describe the manual handoff without claiming it was applied. diff --git a/packages/claude-directory/skills/platform-openai/SKILL.md b/packages/claude-directory/skills/platform-openai/SKILL.md deleted file mode 100644 index e760ff7..0000000 --- a/packages/claude-directory/skills/platform-openai/SKILL.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -name: platform-openai -description: OpenAI Ads playbook — campaign structure, appearances in AI answers, and aggregation levels. Use when planning, reading, auditing, or launching OpenAI Ads, or porting a campaign to OpenAI Ads. ---- - -# OpenAI Ads - -A newer surface: ads that appear alongside AI answers. Structure is campaign → ad group → ad. Treat it as an emerging channel, measure honestly, and start small. - -## Read what exists - -- `list_connected_accounts`, then `list_campaigns(platform="openai_ads")`. -- Dedicated performance reads for this platform are outside the plugin’s directory tools. Request a platform export for metrics and use `list_campaigns` for the state and fields actually returned. Do not substitute another platform’s data. - -## Structure and intent - -- Campaigns hold objective and budget, ad groups hold targeting, ads hold the copy and destination. -- Placement is inside AI answers, so intent matters more than raw reach. Match the ad to the questions your audience actually asks, and point at a content page that answers them, not a bare signup screen. - -## Creative - -- Write text with `create_ad_copy`, select existing approved assets with `list_creative_assets`, and apply the verified advertiser’s brand voice. Request missing media from the advertiser. See **creative-testing**. - -## Plan and ship - -- Build with `create_campaign_plan` + `upsert_plan_entity`; `forecast_campaign` where projections are available. Run **campaign-preflight**: tracking attached (`get_pixel_health` / `ga4_get_conversions`), sane budgets. -- Ship only on explicit approval: `execute_campaign_plan`, then `enable_campaign`. Nothing that spends money goes live without a clear go. -- Confirm live with `list_campaigns(platform="openai_ads")` and report the real ID. Start conservative; read results before scaling with the **optimize** skill. - -Porting from another platform? Use the **replicate** skill and translate keyword intent into the questions this audience asks. - -Use only platform and entity types accepted by the live tool schema. Follow **launch** for plan review, preflight, approval, execution, and verification. If a setting or platform is unsupported, describe the manual handoff without claiming it was applied. diff --git a/packages/claude-directory/skills/platform-reddit/SKILL.md b/packages/claude-directory/skills/platform-reddit/SKILL.md deleted file mode 100644 index dac8f6a..0000000 --- a/packages/claude-directory/skills/platform-reddit/SKILL.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -name: platform-reddit -description: Reddit Ads playbook — community vs interest targeting, ad formats, tone, and moderation reality. Use when planning, reading, auditing, or launching Reddit Ads, or porting a campaign to Reddit. ---- - -# Reddit Ads - -Reddit rewards ads that read like a good post and punishes ads that read like ads. Structure is campaign → ad group → ad. - -## Read what exists - -- `list_connected_accounts`, then `list_campaigns(platform="reddit")`. -- `pull_reddit_ads_performance(days=7)` for spend, clicks, and CPA per campaign. - -## Targeting - -- Two levers: **communities** (specific subreddits) and **interests** (Reddit's topic clusters). Community targeting is precise but narrow; interest targeting scales but blurs. -- Prefer audience fit over long subreddit lists. A tight interest plus a handful of high-fit communities usually beats a scraped list of 200 subreddits. -- Review existing audiences with `list_audiences`. Use `research_campaign_opportunity` for available campaign research. Ask the account owner to create or synchronize new audience lists in the platform UI; use returned IDs only in supported plan fields. - -## Creative and tone - -- Match the medium: conversational copy, a real point of view, an image or short video that would not look out of place in the feed. Overtly corporate creative dies here. -- Write text with `create_ad_copy`, select existing approved assets with `list_creative_assets`, and apply the verified advertiser’s brand voice. Request missing media from the advertiser. See **creative-testing**. - -## Plan and ship - -- Build with `create_campaign_plan` + `upsert_plan_entity`; `forecast_campaign` for reach and CPA. Run **campaign-preflight**: geo correct, tracking attached (`get_pixel_health`), budgets sane. -- Ship only on explicit approval: `execute_campaign_plan`, then `enable_campaign`. Nothing that spends money goes live without a clear go. -- Confirm live with `list_campaigns(platform="reddit")` and report the real ID. Start conservative; scale with the **optimize** skill. - -Porting from another platform? Use the **replicate** skill and translate keywords or audiences into communities and interests. - -Use only platform and entity types accepted by the live tool schema. Follow **launch** for plan review, preflight, approval, execution, and verification. If a setting or platform is unsupported, describe the manual handoff without claiming it was applied. diff --git a/packages/claude-directory/skills/platform-tiktok/SKILL.md b/packages/claude-directory/skills/platform-tiktok/SKILL.md deleted file mode 100644 index a0a97b1..0000000 --- a/packages/claude-directory/skills/platform-tiktok/SKILL.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -name: platform-tiktok -description: TikTok Ads playbook — campaign structure, objectives, Spark Ads, audiences, and native video creative. Use when planning, reading, auditing, or launching TikTok Ads, or porting a campaign to TikTok. ---- - -# TikTok Ads - -Native, sound-on, creator-style video is the product. Structure is campaign → ad group → ad. - -## Read what exists - -- `list_connected_accounts` to confirm the org and account, then `list_campaigns(platform="tiktok")`. -- Dedicated performance reads for this platform are outside the plugin’s directory tools. Request a platform export for metrics and use `list_campaigns` for the state and fields actually returned. Do not substitute another platform’s data. - -## Structure and objectives - -- Objective sits at the campaign level (traffic, conversions, app installs, reach, lead generation). Pick the one that matches the real conversion, not the vanity metric. -- Ad groups hold budget, targeting, placement, and schedule. Ads hold the creative. -- Review existing audiences with `list_audiences`. Use `research_campaign_opportunity` for available campaign research. Ask the account owner to create or synchronize new audience lists in the platform UI; use returned IDs only in supported plan fields. - -## Creative is the campaign - -- Vertical 9:16, sound-on, hook in the first 2 seconds. Spark Ads run through an organic post and usually outperform static uploads. -- Write text with `create_ad_copy`, select existing approved assets with `list_creative_assets`, and apply the verified advertiser’s brand voice. Request missing media from the advertiser. See **creative-testing**. - -## Plan and ship - -- Build with `create_campaign_plan` + `upsert_plan_entity`; `forecast_campaign` for reach and CPA. Run **campaign-preflight** before launch: geo, tracking (`get_pixel_health`), sane budgets. -- Ship only on explicit approval: `execute_campaign_plan`, then `enable_campaign`. Nothing that spends money goes live without the user's clear go. -- Confirm live with `list_campaigns(platform="tiktok")` and report the real ID. Start conservative; scale winners with the **optimize** skill. - -Porting a campaign here from another platform (e.g. Google Search)? Search keywords have no twin on TikTok. Translate intent into audience signals and creative. Use the **replicate** skill. - -Use only platform and entity types accepted by the live tool schema. Follow **launch** for plan review, preflight, approval, execution, and verification. If a setting or platform is unsupported, describe the manual handoff without claiming it was applied. diff --git a/packages/claude-directory/skills/platform-x/SKILL.md b/packages/claude-directory/skills/platform-x/SKILL.md deleted file mode 100644 index 8768f4f..0000000 --- a/packages/claude-directory/skills/platform-x/SKILL.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -name: platform-x -description: X (Twitter) Ads playbook — objectives, targeting, ad formats, and realistic expectations. Use when planning, reading, auditing, or launching X Ads, or porting a campaign to X. ---- - -# X (Twitter) Ads - -Fast, conversational, timeline-native. Structure is campaign → ad group → ad. Set expectations honestly: X can deliver cheap clicks that do not convert, so tie every campaign to a real conversion, not engagement. - -## Read what exists - -- `list_connected_accounts`, then `list_campaigns(platform="x")`. -- Dedicated performance reads for this platform are outside the plugin’s directory tools. Request a platform export for metrics and use `list_campaigns` for the state and fields actually returned. Do not substitute another platform’s data. - -## Structure and targeting - -- Objective at the campaign level (traffic, conversions, awareness, app installs, engagement, followers). Choose by the conversion, not the vanity metric. -- Target by keywords, interests, follower lookalikes, and custom audiences. Follower-lookalike (people similar to a chosen account's followers) is the distinctive lever. -- Watch for cheap-click traps: high CTR with zero downstream conversions means the traffic is wrong. Validate against the real action. - -## Creative - -- Native tweet format wins over banner-style creative. Short copy, a clear hook, one ask. Video and single-image both work. -- Write text with `create_ad_copy`, select existing approved assets with `list_creative_assets`, and apply the verified advertiser’s brand voice. Request missing media from the advertiser. See **creative-testing**. - -## Plan and ship - -- Build with `create_campaign_plan` + `upsert_plan_entity`; `forecast_campaign` for reach and CPA. Run **campaign-preflight**: geo, tracking (`get_pixel_health`), sane budgets. -- Ship only on explicit approval: `execute_campaign_plan`, then `enable_campaign`. Nothing that spends money goes live without a clear go. -- Confirm live with `list_campaigns(platform="x")` and report the real ID. Start small; measure conversions before scaling with the **optimize** skill. - -Porting from another platform? Use the **replicate** skill. Search keywords translate to X keyword and interest targeting, but re-check conversion intent before spending. - -Use only platform and entity types accepted by the live tool schema. Follow **launch** for plan review, preflight, approval, execution, and verification. If a setting or platform is unsupported, describe the manual handoff without claiming it was applied. diff --git a/packages/claude-directory/skills/pre-pause-analysis/SKILL.md b/packages/claude-directory/skills/pre-pause-analysis/SKILL.md deleted file mode 100644 index 7c3878c..0000000 --- a/packages/claude-directory/skills/pre-pause-analysis/SKILL.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -name: pre-pause-analysis -description: Full-funnel check before pausing, cutting, or killing a paid campaign — confirm the problem is real and the platform has had enough time before stopping any spend. Use before pausing anything, or when a user wants to cut a campaign that looks like it is underperforming. ---- - -# Pre-Pause Analysis - -Pausing is easy and often wrong. A campaign that looks like a loser is frequently a tracking gap, a geo leak, or an ad set the platform has not finished learning. Run this before any pause so you stop the right thing for the right reason. Reads do not require approval; pausing is a change and waits for explicit approval. - -Confirm the account: `list_connected_accounts`. - -## 1. Is the data even real - -- Confirm conversion tracking is firing and attached to the right action (`ga4_get_conversions`, `get_pixel_health`). A campaign with broken tracking looks dead when it may be converting. See the **conversion-tracking** skill. -- Check the destination: does the final URL resolve and match the ad's promise. A broken or mismatched landing page kills conversion rate independent of the campaign. - -## 2. Has it had enough time and volume - -- New ad sets need a learning window before their numbers mean anything. On Meta, an ad set in the Learning Phase has not stabilized. On Search, a handful of clicks is noise. -- Require a real spend and conversion count over enough days before judging. State the window and the volume you are judging on. - -## 3. Where in the funnel is it actually failing - -Diagnose the level, do not just read the top-line CPA: - -- **Delivery:** is it spending and serving. Low impression share or a tiny audience is a setup problem, not a performance one. -- **Click:** impressions but no clicks points at creative or relevance. Clicks from the wrong geography point at a targeting or fraud leak, not a bad offer. Validate click geography against intent. -- **Conversion:** clicks but no conversions points at the landing page, the offer, or tracking, before the campaign itself. - -## 4. Decide and confirm - -- If the problem is fixable (tracking, geo, negatives, creative, landing page), fix that first rather than pausing. -- If it is a genuine loser with enough evidence, pause on the user's clear go with `pause_campaign`, and report the evidence behind the call. - -Pair with **kill-scale-rules** for the kill-or-scale decision once the data is trustworthy. diff --git a/packages/claude-directory/skills/replicate/SKILL.md b/packages/claude-directory/skills/replicate/SKILL.md deleted file mode 100644 index c132e07..0000000 --- a/packages/claude-directory/skills/replicate/SKILL.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -name: replicate -description: Rebuild an existing campaign from one ad platform onto another — read the live structure on the source platform, map it to the target platform, and ship a matching campaign. Use when a user wants to copy, port, clone, duplicate, mirror, or replicate a campaign across platforms (e.g. "build my Google campaign on Microsoft", "run this Meta campaign on TikTok too", "copy my Search campaign to Bing"). ---- - -# Replicate a Campaign Across Platforms - -Take a campaign that already runs on one platform and stand up a matching one on another. Read what exists, map it to the target platform's shape, show the plan, and ship on the user's word. This is a build path — every spend-creating step waits for explicit approval. - -The common ask is Google → Microsoft (near 1:1), but the same loop works for any pair. - -## 1. Read the source campaign — completely - -Confirm the org and accounts first: `list_connected_accounts`. Both the source and target platforms must be connected. If the target isn't connected, run the **connect** skill first. - -Find the source campaign: `list_campaigns(platform="")`. Get its real ID. - -Pull the full structure, not just top-line metrics: - -- Read `list_campaigns`, `audit_account_structure`, and `pull_google_ads_performance` for a Google source. Ask for platform exports when budgets, geo criteria, keyword match types, negatives, or complete ad text are missing. Do not replicate unknown settings. -- **Other sources (Meta, LinkedIn, Reddit, Microsoft):** use `list_campaigns` and the matching performance tool (`pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_reddit_ads_performance`, or `pull_microsoft_ads_performance`) for performance; request platform exports for structure, audiences, and creative. TikTok and X sources require a platform export. - -Write down the source structure explicitly before you build. If you cannot read a piece, say so — never invent a keyword list or a budget. - -## 2. Map source → target - -Platforms are not identical. State the mapping and where it is lossy. - -**Google → Microsoft (the easy case — nearly a mirror):** -- Campaign, ad group, keyword (with match types), RSA, negative keyword, geo/location, ad schedule, and budget all map directly. -- Keep match types exactly. Keep negatives — they matter as much as the keywords. -- Watch the gaps: Microsoft's audience and network options differ (Search Partners, Microsoft Audience Network), some Google automated-bidding modes have no exact twin, and final-URL/tracking-template syntax can differ. Call these out rather than silently dropping them. -- Rebuild fresh through Synter's plan tools. Do not describe this as Microsoft's native "Import from Google" — that is a different, platform-side path. - -**Cross-format pairs (e.g. Search → social, Google → Meta/TikTok):** -- Social campaigns require a new targeting interpretation. Use `research_campaign_opportunity` and existing `list_audiences` results to inform it; document how the proposed targeting differs from the source. - -## 3. Build the target plan - -`create_campaign_plan` to draft the target structure, then `upsert_plan_entity` to add each campaign → ad group / ad set → ad, carrying over the mapped keywords, negatives, geo, schedule, and budget. `forecast_campaign` for reach/CPC/CPA on the new platform — the source platform's numbers do not transfer. - -Creative: reuse the source ad copy where the format allows; otherwise run the **ad-copy-generation** skills to regenerate for the target platform. Apply brand voice — see `../../context/brand-and-safety.md`. - -## 4. Preflight — before anything goes live - -Run the **campaign-preflight** checklist and report pass/fail: - -- Geo/location criteria copied and correct (a "US" name with no location criteria is the classic miss). -- Negatives carried over — porting keywords without negatives burns budget fast. -- Check target-side evidence with `ga4_get_conversions` and `get_pixel_health`. Resolve missing tracking verification before launch. -- Budget and bid caps sane — guard against a fat-finger daily budget 10–100x intended. -- Match types preserved; final URLs resolve and match the ad's promise. - -## 5. Ship on approval - -Show the mapped plan beside the source, including changed structure, geography, audience, budget, and assets. Follow **launch** for `run_launch_preflight`, explicit user approval, `approve_campaign_plan`, and `execute_campaign_plan`. Verify with `get_plan_execution` and `list_campaigns`; enable only within the approved scope. - -Confirm live: `list_campaigns(platform="")` and report the real campaign ID created. "Created" and "live and spending" are different claims — verify before you say it is running. - -## House rules - -- Nothing that spends money ships without explicit approval. Recommend, then execute. -- Use the real account and campaign IDs the tools return — never invent them. -- Never run one org's campaign through another org's key. -- Microsoft (and most platforms): enabling a campaign does not serve its ad groups if those stay paused. After enabling, re-pull and confirm the children actually serve. -- Start the target conservative on budget; scale winners later with the **optimize** skill. diff --git a/packages/claude-directory/skills/retargeting-sequence-designer/SKILL.md b/packages/claude-directory/skills/retargeting-sequence-designer/SKILL.md deleted file mode 100644 index cccc857..0000000 --- a/packages/claude-directory/skills/retargeting-sequence-designer/SKILL.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -name: retargeting-sequence-designer -description: Design multi-stage retargeting funnels with recency windows, sequential messaging, frequency caps, and exclusion lists across platforms. Use when a user wants to build a retargeting or remarketing funnel, segment audiences by recency, or stop over-serving ads to the same people. ---- - -# Retargeting Sequence Designer - -Retargeting works when recency drives the message and exclusions stop the waste. One "all visitors 30 days" audience with one ad is not a funnel; it is a frequency complaint generator. - -Confirm the account and existing audiences first: `list_connected_accounts`, `list_audiences`. - -## 1. Map stages to intent - -Define the conversion goal, then split visitors by how close they got: - -- **Stage 1:** all site visitors (awareness reinforcement) -- **Stage 2:** engaged visitors (product or offer pages, 2+ pages) -- **Stage 3:** high-intent (cart, order, demo page) -- **Stage 4:** abandoners (started the conversion, did not finish) - -Allocate the proposed budget by intent and audience size. Check `get_pixel_health` and **conversion-tracking** before relying on event-based audiences; verify actual membership with `list_audiences` or platform exports. - -## 2. Segment by recency, with mutual exclusion - -- **Hot (0-3 days):** highest bids, direct CTA and urgency, up to 3 impressions/day, ~35% of budget. -- **Warm (4-14 days):** social proof and case studies, up to 2/day, ~30%. -- **Cool (15-30 days):** value proposition refresh, 1/day, ~20%. -- **Cold (31-90 days):** new features and win-back offers, ~3/week, ~15%. - -Each window must exclude every shorter window, or the hot audience gets triple-served by every campaign at once. - -## 3. Sequence the message - -Sequence messages by recency and intent: reminder, evidence, relevant offer, then a different angle. Avoid fabricated urgency. Write text variants with `create_ad_copy`, select existing approved assets with `list_creative_assets`, and use **creative-testing** to assess results. - -## 4. Build the exclusions - -Mandatory, on every retargeting campaign: - -- Purchasers and converters, 30 days minimum, 90 recommended. -- Existing customers, unless the approved campaign explicitly targets them. -- Junk traffic: sub-5-second bounces, careers-page visitors. - -Have the account owner refresh customer suppression lists and exclusions in the platform UI. Confirm existing audience IDs with `list_audiences` before adding them to supported plan fields. - -## 5. Coordinate across platforms - -Assign roles so platforms complement instead of pile on: Google Display/YouTube for reach, Meta for social proof, LinkedIn for B2B decision-makers, TikTok for short-form. Cap total cross-platform exposure around 5-8 impressions/day per user by capping each platform individually (Meta and Reddit 2-3/day, LinkedIn 1-2/day, Display 3-5/day). Upload the same suppression list everywhere so a converter disappears from all platforms, not just one. - -## 6. Launch and monitor - -Prepare per-stage campaigns with `create_campaign_plan` and `upsert_plan_entity`, then follow **launch** for preflight and explicit approval. Review results weekly with the supported platform performance tools: - -- Frequency above ~8/week per user: tighten windows or cut budget. -- CTR falling 20%+ week over week: creative fatigue, rotate the stage's ads. -- Check that retargeting credit is real, not just last-touch harvesting — `get_attribution` and, when spend is material, an incrementality test (see **attribution**). - -## Rules - -- No stage without an exclusion. Overlapping windows are self-competition you pay for. -- Recency beats everything: a 0-3 day cart abandoner converts at many times the rate of a 60-day visitor. Bid like it. -- Rotate creative per stage; a five-touch sequence with one ad is one touch, five times. -- Retargeting looks cheap on last-click. Judge it on incremental CPA before scaling (see **optimize**). diff --git a/packages/claude-directory/skills/seasonal-budget-planner/SKILL.md b/packages/claude-directory/skills/seasonal-budget-planner/SKILL.md deleted file mode 100644 index b243ad0..0000000 --- a/packages/claude-directory/skills/seasonal-budget-planner/SKILL.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -name: seasonal-budget-planner -description: Plan ad budgets around seasonal peaks — holiday scaling, CPM inflation, pre-season/peak/post-season phasing, and Smart Bidding seasonality adjustments. Use when a user wants to plan Black Friday or holiday budgets, forecast peak-season costs, or build a seasonal campaign calendar. ---- - -# Seasonal Budget Planner - -Peak season punishes flat budgets twice: CPMs inflate 50-150% while unprepared accounts pay them with untested creative and cold audiences. Plan in phases, not in a panic the week before. - -Ground the plan in your own history first: the supported performance tools (`pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_microsoft_ads_performance`, `pull_reddit_ads_performance`) over last year's season and `ga4_get_report` with a date dimension to see your real demand curve. - -## 1. Plan in four phases - -- **Pre-season (6-8 weeks out), 70-80% of normal budget:** build remarketing pools, A/B test creative so winners are proven before CPMs spike (see **creative-testing**), verify tracking (see **conversion-tracking**). -- **Ramp-up (2-4 weeks out), 100-120%:** scale winning creative, run teasers, warm audiences, pre-load promo assets. -- **Peak (event days), 200-500% of normal daily budget:** all prepared campaigns live, aggressive bids, budget weighted to warm retargeting audiences, urgency messaging, hourly monitoring. -- **Post-season (1-4 weeks after), 80-100%:** retarget peak-period visitors who did not convert, extended-sale and clearance messaging, step bids down as competition fades. - -## 2. Budget for CPM inflation - -Costs are not flat across the year. Against a January baseline, expect roughly 1.2-1.3x by September-October, 1.5-2.5x in November, and 1.4-2x through mid-December, with event spikes around Prime Day and Back-to-School. Practical moves: - -- Front-load: early-November impressions cost far less than BFCM-week impressions. -- Shift flexible spend into January and April, the cheapest months. -- During peak weeks, tilt toward retargeting and search, where you pay for intent rather than inflated reach. - -Use `forecast_campaign` to sanity-check projected volume at planned budgets before committing. - -## 3. Index the budget to your industry curve - -Build a monthly index from your own trailing 12-24 months of performance data (100 = average month), then set each month's budget as baseline x index/100. Ecommerce typically peaks November-December and troughs in summer; B2B peaks January, March, and September-October and dies in late December; fitness and education have their own January and August-September spikes. Your data beats any generic table — pull it before assuming. - -For B2B specifically: push hard in January (new budgets), March (Q1 use-it-or-lose-it), and September-October (next-year budget finalization); cut 30-40% in July-August and after December 15. - -## 4. Use platform seasonal features - -- **Google Seasonality Adjustments** tell Smart Bidding to expect a temporary CVR change for 1-7 day events (flash sales, BFCM). Set +30% for a general holiday, +50% for a major sale, up to +100% for a deep-discount flash sale, about 24 hours before the event. Do not use them for gradual trends; Smart Bidding learns those itself. See **platform-google**. -- Promotion extensions and countdown customizers on Google; Advantage+ shopping on Meta (see **platform-meta**). - -## 5. Anchor to the event calendar - -The big cost spikes are predictable. Plan phases backward from the dates that matter for the vertical: - -- **BFCM (late November):** the peak of peaks, +80-150% CPMs across retail. -- **Christmas (Dec 1-24, peaking mid-month):** +50-100%, then a hard drop after Dec 20. -- **Prime Day (mid-July):** +40-60% around Amazon, spillover elsewhere. -- **Back-to-School (Aug-Sep):** +20-30% for electronics, apparel, supplies. -- **Gift holidays (Valentine's, Mother's/Father's Day):** +15-30% in gifting categories for the surrounding week. - -If you are not in the category, these are your cheap weeks — competitors' budgets left the auction. - -## 6. Execute and guard - -Encode the phased proposal with `create_campaign_plan` and follow **launch** for preflight, approval, and execution. Apply approved phase changes with `update_campaign_budget`; use `optimize_budget` for allocation recommendations. Configure alerts in the platform UI. Review performance daily during peak and reconcile with `get_spend_reconciliation` afterward. - -## Rules - -- No creative testing during peak. Test in pre-season; peak runs proven winners only. -- Higher CPMs are acceptable only where CVR rises to match. Track CPA/ROAS through the spike, not spend. -- Budget increases in steps, not cliffs — large jumps reset bid-strategy learning right when you need it stable (see **bid-optimization**). -- Write down actual vs planned after the season. Next year's plan starts from this year's miss. -- For the year-round allocation question underneath the seasonal one, use **mmm-budget-planner** and **media-plan**. diff --git a/plugin.json b/plugin.json index 5f165a0..01d7d43 100644 --- a/plugin.json +++ b/plugin.json @@ -1,8 +1,8 @@ { "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", "name": "synter", - "version": "1.2.1", - "description": "Plan and operate advertising campaigns through Synter’s hosted MCP server over OAuth. Review performance, write ad copy, and approve campaign changes before execution.", + "version": "1.3.0", + "description": "Plan and operate advertising campaigns through Synter\u2019s hosted MCP server over OAuth. Review performance, write ad copy, and approve campaign changes before execution.", "author": { "name": "Synter", "email": "joel@synterai.com", @@ -99,7 +99,7 @@ }, { "description": "Cross-workspace access", - "prompt": "Read another company’s ad accounts that are not connected to my workspace.", + "prompt": "Read another company\u2019s ad accounts that are not connected to my workspace.", "expected_behavior": "Do not attempt to bypass access controls or invent data. Explain that an authorized connection is required." } ] diff --git a/rules/readonly-marketplace.mdc b/rules/readonly-marketplace.mdc new file mode 100644 index 0000000..7b49827 --- /dev/null +++ b/rules/readonly-marketplace.mdc @@ -0,0 +1,14 @@ +--- +description: Free Cursor Marketplace listing is read-only — no writes, launches, or spend +alwaysApply: true +--- + +# Free read-only Synter listing + +This Synter Cursor plugin listing is free and read-only. + +- Only call tools listed in `tools/readonly-tools.json`. +- Never call create, update, launch, approve, execute, enable, pause, budget-change, keyword-add, or spend tools. +- Never ask the user to approve ad spend or campaign launches from this listing. +- For write or launch work, direct the user to the full Synter product at https://synterai.com — do not invent prices. +- Prefer reporting, audits, forecasts, and connection health checks. diff --git a/scripts/build-packages.py b/scripts/build-packages.py index e835688..96f51f7 100644 --- a/scripts/build-packages.py +++ b/scripts/build-packages.py @@ -13,6 +13,8 @@ # OpenAI's current documented vendor extension; the portable 1.0.0 MCP # schema does not yet accept server extensions. Keep the base independent. +DIRECTORY_MCP_URL = 'https://mcp.synterai.com/mcp/directory' + OPENAI_AUTH = {'type': 'oauth', 'client': {'mode': 'dcr'}} @@ -42,6 +44,13 @@ def include(relative): files[relative] = source.read_bytes() for relative in ['LICENSE', 'assets/logo.png', 'context/brand-and-safety.md', 'tools/directory-tools.json']: include(relative) + skill_allow = None + agent_allow = None + if target == 'claude-directory': + skill_allow = set(json.loads((root / 'config/claude-directory/skills-allowlist.json').read_text())) + agent_allow = set(json.loads((root / 'config/claude-directory/agents-allowlist.json').read_text())) + if len(skill_allow) < 10 or len(agent_allow) < 1: + raise ValueError('Claude directory allowlists are too small') for relative in ['skills'] + (['agents', 'output-styles'] if target in ['claude', 'claude-directory'] else []): for source in sorted((root / relative).rglob('*')): if source.is_symlink(): @@ -49,15 +58,36 @@ def include(relative): if source.is_file(): if source.suffix != '.md': raise ValueError('Unreviewed runtime asset: ' + str(source.relative_to(root))) - include(source.relative_to(root).as_posix()) + rel = source.relative_to(root).as_posix() + if skill_allow is not None and relative == 'skills': + skill_name = Path(rel).parts[1] if len(Path(rel).parts) > 1 else '' + if skill_name not in skill_allow: + continue + if agent_allow is not None and relative == 'agents': + agent_name = Path(rel).stem + if agent_name not in agent_allow: + continue + # Directory package stays markdown-only and skips output-styles (binary-adjacent noise). + if target == 'claude-directory' and relative == 'output-styles': + continue + include(rel) if target == 'claude': include('.claude-plugin/plugin.json') include('.mcp.json') include('scripts/session-context.sh') elif target == 'claude-directory': manifest.pop('hooks', None) + # Keep only reviewed identity + privacy for directory scanners. + privacy = manifest.get('privacyPolicyUrl') or 'https://synterai.com/privacy' + manifest['privacyPolicyUrl'] = privacy files['.claude-plugin/plugin.json'] = encoded(manifest) - include('.mcp.json') + directory_mcp = json.loads((root / '.mcp.json').read_text()) + directory_mcp['mcpServers']['synter']['url'] = DIRECTORY_MCP_URL + directory_mcp['mcpServers']['synter']['description'] = ( + 'Synter free read-only MCP profile for Claude Directory. ' + 'Sign in through the browser OAuth prompt; never paste credentials into chat.' + ) + files['.mcp.json'] = encoded(directory_mcp) for source, destination in [('README.md', 'README.md'), ('help.md', 'skills/help/SKILL.md')]: path = root / 'config/claude-directory' / source relative_path = path.relative_to(root) @@ -102,13 +132,15 @@ def validate_claude_directory(files): manifest = json.loads(files['.claude-plugin/plugin.json']) if 'hooks' in manifest: raise ValueError('Directory manifest must not declare hooks') + if manifest.get('privacyPolicyUrl') != 'https://synterai.com/privacy': + raise ValueError('Directory manifest must declare Synter privacyPolicyUrl') if set(manifest) - {'$schema', 'name', 'displayName', 'description', 'version', 'license', - 'author', 'homepage', 'repository', 'keywords'}: + 'author', 'homepage', 'repository', 'keywords', 'privacyPolicyUrl'}: raise ValueError('Unreviewed directory manifest capability') servers = json.loads(files['.mcp.json']).get('mcpServers', {}) if (set(servers) != {'synter'} or set(servers['synter']) != {'type', 'url', 'description'} or servers['synter']['type'] != 'http' - or servers['synter']['url'] != 'https://mcp.synterai.com' + or servers['synter']['url'] != DIRECTORY_MCP_URL or not isinstance(servers['synter']['description'], str)): raise ValueError('Directory supports only the declared remote HTTPS MCP server') if len(files['README.md'].decode().split()) < 40: diff --git a/scripts/check-directory-tools.js b/scripts/check-directory-tools.js index b7aee51..fcea814 100644 --- a/scripts/check-directory-tools.js +++ b/scripts/check-directory-tools.js @@ -15,7 +15,7 @@ const DATA_IDENTIFIERS = new Set([ ]); const ROOT = path.resolve(__dirname, '..'); const SURFACES = ['skills', 'commands', 'rules', 'agents']; -const ENDPOINTS = new Set(['https://mcp.synterai.com', 'https://mcp.syntermedia.ai']); +const ENDPOINTS = new Set(['https://mcp.synterai.com', 'https://mcp.synterai.com/mcp/directory', 'https://mcp.syntermedia.ai']); function extractReferences(source) { const refs = []; diff --git a/scripts/check-readonly-tools.js b/scripts/check-readonly-tools.js new file mode 100644 index 0000000..b009263 --- /dev/null +++ b/scripts/check-readonly-tools.js @@ -0,0 +1,61 @@ +#!/usr/bin/env node +'use strict'; +const fs = require('node:fs'); +const path = require('node:path'); +const ROOT = path.resolve(__dirname, '..'); +const WRITE_TOOLS = new Set([ + 'create_campaign_plan', 'upsert_plan_entity', 'approve_campaign_plan', + 'execute_campaign_plan', 'enable_campaign', 'pause_campaign', + 'update_campaign_budget', 'add_keywords', 'add_negative_keywords', + 'create_ad_copy', +]); +const CANONICAL = 'https://mcp.synterai.com'; + +function loadReadonly() { + const names = JSON.parse(fs.readFileSync(path.join(ROOT, 'tools/readonly-tools.json'), 'utf8')); + if (!Array.isArray(names) || names.length < 10) { + throw new Error('tools/readonly-tools.json missing or too small'); + } + if (names.some((n) => WRITE_TOOLS.has(n))) { + throw new Error('readonly-tools.json contains write tools'); + } + return new Set(names); +} + +function main() { + const readonly = loadReadonly(); + const errors = []; + for (const rel of ['.cursor-mcp.json', 'mcp.json']) { + const json = JSON.parse(fs.readFileSync(path.join(ROOT, rel), 'utf8')); + for (const cfg of Object.values(json.mcpServers || {})) { + if (cfg.url !== CANONICAL) { + errors.push(`${rel}: url must be ${CANONICAL}, got ${cfg.url}`); + } + if (cfg.headers) { + errors.push(`${rel}: must not set static credential headers`); + } + } + } + const readme = fs.readFileSync(path.join(ROOT, 'README.md'), 'utf8'); + if (!/free,\s*read-only|free and read-only|\*\*free, read-only\*\*/i.test(readme)) { + errors.push('README.md: must state the Cursor listing is free and read-only'); + } + if (/\$0\.25|Solo \(\$20/i.test(readme)) { + errors.push('README.md: must not include paid write pricing copy'); + } + fs.readFileSync(path.join(ROOT, 'rules/readonly-marketplace.mdc'), 'utf8'); + const cursorPlugin = JSON.parse( + fs.readFileSync(path.join(ROOT, '.cursor-plugin/plugin.json'), 'utf8') + ); + if (!/read-only/i.test(cursorPlugin.description || '')) { + errors.push('.cursor-plugin/plugin.json: description must say read-only'); + } + if (!readonly.size) errors.push('readonly allowlist empty'); + if (errors.length) { + console.error(errors.join('\n')); + process.exit(1); + } + console.log(`readonly-tools ok (${readonly.size} tools); Cursor MCP URL ${CANONICAL}`); +} + +main(); diff --git a/scripts/test_build_packages.py b/scripts/test_build_packages.py index 08daf25..0e399d3 100644 --- a/scripts/test_build_packages.py +++ b/scripts/test_build_packages.py @@ -26,16 +26,19 @@ def test_all_packages_follow_rsa_and_bidding_guidance(self): self.assertIn('Ad Strength is not a launch gate', text) self.assertNotRegex(text, r'11\+ headlines|15/4 recommended|11 headlines and 4 descriptions minimum|gets? throttled') self.assertEqual(files[name], (mod.ROOT / name).read_bytes()) - preflight = files['skills/campaign-preflight/SKILL.md'].decode() - self.assertIn('MAXIMIZE_CONVERSIONS', preflight) - self.assertNotIn('Start on a click or traffic goal', preflight) + if 'skills/campaign-preflight/SKILL.md' in files: + preflight = files['skills/campaign-preflight/SKILL.md'].decode() + self.assertIn('MAXIMIZE_CONVERSIONS', preflight) + self.assertNotIn('Start on a click or traffic goal', preflight) def test_directory_source_is_reproducible_and_has_only_static_runtime(self): files = mod.sync_claude_directory() self.assertEqual(files, mod.collect(mod.ROOT, 'claude-directory')[1]) - self.assertEqual(sum(name.endswith('/SKILL.md') for name in files), 56) - self.assertEqual(sum(name.startswith('agents/') for name in files), 6) + self.assertEqual(sum(name.endswith('/SKILL.md') for name in files), 27) + self.assertEqual(sum(name.startswith('agents/') for name in files), 3) self.assertNotIn('hooks', json.loads(files['.claude-plugin/plugin.json'])) + self.assertEqual(json.loads(files['.claude-plugin/plugin.json'])['privacyPolicyUrl'], 'https://synterai.com/privacy') + self.assertEqual(json.loads(files['.mcp.json'])['mcpServers']['synter']['url'], 'https://mcp.synterai.com/mcp/directory') self.assertEqual(files['assets/logo.png'], (mod.ROOT / 'assets/logo.png').read_bytes()) self.assertNotIn(b'SessionStart shell hook', files['skills/help/SKILL.md']) for name in files: @@ -99,10 +102,10 @@ def test_directory_generated_source_detects_drift_and_symlinks(self): def test_archives_match_reviewed_rsa_correction_bytes(self): expected = { - 'claude': '72fecb572222d3725acd884f4d7f49a3f5493a2c084d4a4ee201a53a960aee73', - 'claude-directory': 'e313a4ed69ef3e2e80d13c622d102e69d8e6c51cfeb8f0ba13f29b2e0340efc1', - 'openai': '5ab905019791b7f0f71033e19e18042e26ba272b7b2d958aac4ff177a7c0f665', - 'openai-new-draft': '48bbdbedbc5eb96ffacfcd18b339048139ac6f67dbca160e5fd2d13b7682cd87', + 'claude': '19bb9de532579f71baf9155a1247055b41daec87766bb6f3e674f142271d1b75', + 'claude-directory': '8320edc8f8ab074b97c1d8e2f977f13d35befbfef0bfb0153de617ad75117c99', + 'openai': '5cc8eac259294beed15f329cbc155afaab91bdeb3f564916f73517a8801216a0', + 'openai-new-draft': '554a7cdd3c8785932e15b876a6c2f0fe2da249d3ce10d4a68a45f318771ed3dd', } # Snapshot after the approved RSA/bidding correction across all hosts. # Update deliberately when reviewed package contents change. diff --git a/scripts/validate-claude-plugin.sh b/scripts/validate-claude-plugin.sh new file mode 100755 index 0000000..6a1c6bb --- /dev/null +++ b/scripts/validate-claude-plugin.sh @@ -0,0 +1,35 @@ +#!/usr/bin/env bash +# Claude Code --strict still rejects privacyPolicyUrl as an unknown field, but +# Claude Directory Bot requires it on .claude-plugin/plugin.json. Allow only that +# known warning; fail on any other warning or error. +set -euo pipefail +TARGET=${1:?target required} +TMP=$(mktemp) +set +e +npx -y @anthropic-ai/claude-code@2.1.263 plugin validate "$TARGET" --strict >"$TMP" 2>&1 +STATUS=$? +set -e +cat "$TMP" +if [[ $STATUS -eq 0 ]]; then + rm -f "$TMP" + exit 0 +fi +# Strip the allowed privacyPolicyUrl warning and re-evaluate. +FILTERED=$(grep -v "privacyPolicyUrl: Unknown field 'privacyPolicyUrl'" "$TMP" || true) +# If the only failure was that warning (plus the generic strict line), accept. +if echo "$FILTERED" | grep -Eq '✘|Found [2-9] |Found [1-9][0-9]+ |error|Error'; then + # Still has other problems if more than the boilerplate remains as failures. + if echo "$FILTERED" | grep -E '❯|✘ Validation failed' | grep -vq 'Validation failed'; then + rm -f "$TMP" + exit 1 + fi + # Count remaining ❯ warning lines + REMAINING=$(echo "$FILTERED" | grep -c '❯' || true) + if [[ "$REMAINING" -gt 0 ]]; then + rm -f "$TMP" + exit 1 + fi +fi +echo "Allowed known Claude Directory field: privacyPolicyUrl" +rm -f "$TMP" +exit 0 diff --git a/scripts/validate-manifests.js b/scripts/validate-manifests.js index a2a246d..011669a 100644 --- a/scripts/validate-manifests.js +++ b/scripts/validate-manifests.js @@ -115,7 +115,7 @@ if (fs.existsSync(SKILLS_DIR)) { // (d) Client-specific HTTP syntax remains separate from the portable MCP schema. for (const [configPath, expectedUrl] of [ - ['.mcp.json', 'https://mcp.synterai.com'], + ['.mcp.json', 'https://mcp.synterai.com/mcp/directory'], ['.cursor-mcp.json', 'https://mcp.synterai.com'], ]) { const config = manifests[configPath]; diff --git a/tools/readonly-tools.json b/tools/readonly-tools.json new file mode 100644 index 0000000..336d060 --- /dev/null +++ b/tools/readonly-tools.json @@ -0,0 +1,28 @@ +[ + "get_connection_status", + "list_connected_accounts", + "verify_platform_accounts", + "list_campaigns", + "pull_google_ads_performance", + "pull_meta_ads_performance", + "pull_linkedin_ads_performance", + "pull_microsoft_ads_performance", + "pull_reddit_ads_performance", + "ga4_get_properties", + "ga4_get_report", + "ga4_get_conversions", + "get_attribution", + "get_spend_reconciliation", + "get_pixel_health", + "measure_incrementality", + "audit_account_structure", + "research_campaign_opportunity", + "forecast_campaign", + "optimize_budget", + "list_audiences", + "list_creative_assets", + "get_campaign_plan", + "run_launch_preflight", + "get_plan_execution", + "get_job_status" +]