ads

Ads: Free-first Paid Advertising Audit & Optimization

Focused ad account analysis on the 3 base platforms where most ad spend lives: Meta, Google, TikTok. Orchestrates 19 specialized sub-skills and 7 agents (3 audit + 4 creative). First-run users should type /ads start — a guided wizard that captures context, walks them through OAuth setup step-by-step, and persists everything to ~/.claude-ads/profile.json so no future command ever re-asks.

Quick Reference

Command	What it does
`/ads start`	First-run wizard — context capture, per-platform OAuth/MCP walkthroughs with live verification, optional Zernio + Meta Developers signup. Re-run as `/ads start edit/status/reset`.
`/ads next`	Continuous coach — reads recent audit JSON + history, ranks top 3 Quick Wins by impact × ease, optionally walks you through fixing #1. Detects regressions vs your last audit.
`/ads audit`	Full multi-platform audit with parallel subagent delegation (3 agents: Meta, Google, TikTok)
`/ads google`	Google Ads deep analysis (Search, PMax, includes YouTube video campaigns)
`/ads meta`	Meta Ads deep analysis (FB, IG, Advantage+) — MCP-wired to claude.ai Facebook
`/ads tiktok`	TikTok Ads deep analysis (Creative, Shop, Smart+, Symphony, GMV Max)
`/ads creative`	Cross-platform creative quality audit
`/ads landing`	Landing page quality assessment for ad campaigns
`/ads budget`	Budget allocation and bidding strategy review
`/ads plan <business-type>`	Strategic ad plan with industry templates
`/ads competitor`	Competitor ad intelligence analysis
`/ads math`	PPC financial calculator (CPA, ROAS, break-even, budget forecasting)
`/ads test`	A/B test design (hypothesis, significance, duration, sample size)
`/ads report`	PDF audit report generation for client deliverables
`/ads dna <url>`	Extract brand DNA from website, outputs `brand-profile.json`
`/ads create`	Generate campaign concepts + copy briefs, outputs `campaign-brief.md`
`/ads generate`	Generate AI ad images from brief, outputs to `ad-assets/`
`/ads photoshoot`	Product photography in 5 styles (Studio, Floating, Ingredient, In Use, Lifestyle)
`/ads update <platform\|all>`	Refresh per-platform references with last 30 days of changes (COSTLY: ~50–150k tokens/platform; gates on confirmation)
`/ads publish`	Publish generated creatives to 14+ social networks via Zernio (first 2 accounts free; see `skills/ads-publish/SKILL.md`)

First-run behavior

When the user invokes any /ads command other than /ads start, /ads math, or /ads test, FIRST run:

python3 scripts/profile.py get

Exit code 2 (profile missing) → gently surface a one-line tip:

Tip: run /ads start first — it saves ~30 sec per future command. Proceed inline instead? (Y/N) Honor N (proceed) by falling back to the inline Context Intake below.
Exit code 0 (profile present) → parse the JSON and use the saved context.industry, context.monthly_spend_usd, context.primary_goal, context.active_platforms directly. Do NOT re-ask. Only re-ask if a field is null/empty.

Context Intake (fallback — only when profile is missing AND user declined `/ads start`)

Without context, benchmarks will be generic and recommendations may be wrong for the user's situation.

Ask these questions upfront (combine into one message):

Industry / Business type: Which best describes you? E-commerce · Local Service · Real Estate · Healthcare · Finance · Agency · Other (Note: B2B-enterprise, SaaS, mobile-app, and info-products templates were removed in v2.3.0 since they depended on LinkedIn/Apple/YouTube which are no longer audited; use the generic template plus the platform-specific skills below.)
Monthly ad spend: Total budget and per-platform breakdown (approximate is fine)
Primary goal: Sales / Revenue · Leads / Demos · App Installs · Calls · Brand
Active platforms: Of the 3 supported (Meta, Google, TikTok), which are you advertising on?

If the user provides data upfront (e.g. "audit my Google Ads, I spend $5k/mo on ecommerce"), extract context from that and proceed without re-asking.

After the inline intake, offer: "Want me to save this to your profile so I never re-ask? (runs /ads start quickly with your answers prefilled)."

Use the provided context to:

Select the correct industry benchmarks from references/benchmarks.md
Apply budget-appropriate recommendations (e.g. Smart Bidding requires 15+ conv/month)
Calibrate severity scoring (a $500/mo account has different priorities than $50k/mo)

Orchestration Logic

When the user invokes /ads audit, delegate to subagents in parallel:

Load context — run python3 scripts/profile.py get. If profile exists, use it. If exit 2, fall back to inline Context Intake (and offer to save via /ads start at the end).
Collect account data (exports, screenshots, or pasted metrics — for connected platforms use the saved tier in connections.<p>.tier)
Detect business type and identify active platforms (from context.active_platforms if available)
Spawn subagents via Task tool with context: fork — only for context.active_platforms (or those with connections.<p>.tier != "skipped"): audit-google, audit-meta, audit-tiktok
Validate: each subagent writes both <platform>-audit-results.json and <platform>-audit-results.md. Parse the JSON and validate against references/audit-output-schema.json before aggregating. If any subagent's JSON is missing or invalid, surface the error and stop — do not silently aggregate partial results.
Aggregate scores using the platform-budget-share formula in references/scoring-system.md and generate the unified Ads Health Score (0-100)
Create prioritized action plan from the quick_wins and critical_issues arrays of each JSON
Persist to history — for each new audit JSON: python3 scripts/profile.py save-audit <platform>-audit-results.json. This feeds /ads next regression detection.
Suggest the next step — point the user at /ads next for ranked Quick Wins.

For individual commands (/ads google, /ads meta, etc.), load the relevant sub-skill directly. Still load profile / collect context first if not already provided.

For /ads update <platform|all>, route to skills/ads-update/SKILL.md. The update skill enforces a mandatory cost-confirmation gate before fetching — do NOT bypass it. See references/update-cost-warning.md for the rationale.

Creative Workflow

Sequential pipeline (each step is independently runnable):

/ads dna <url> → brand-profile.json in current directory
/ads create → reads profile + optional audit results → campaign-brief.md
/ads generate → reads brief + profile → ad-assets/ directory
/ads photoshoot → standalone or reads profile for style injection

Requires GOOGLE_API_KEY (Gemini default) or ADS_IMAGE_PROVIDER + matching key. If API key is missing, /ads generate and /ads photoshoot display setup instructions and exit; they never fail silently.

Industry Detection

Detect business type from ad account signals:

SaaS: trial_start/demo_request events, pricing page targeting, long attribution windows
E-commerce: purchase events, product catalog/feed, Shopping/PMax campaigns
Local Service: call extensions, location targeting, store visits, directions events
B2B Enterprise: LinkedIn Ads active, ABM lists, high CPA tolerance ($50+), long sales cycle
Info Products: webinar/course funnels, lead gen forms, low-ticket offers
Mobile App: app install campaigns, in-app events, deep linking
Real Estate: listing feeds, property-specific landing pages, geo-heavy targeting
Healthcare: HIPAA compliance flags, healthcare-specific ad policies
Finance: Special Ad Categories declared, financial products compliance
Agency: multiple client accounts, white-label reporting needs

Quality Gates

Hard rules (never violate these):

Never recommend Broad Match without Smart Bidding (Google)
3x Kill Rule: flag any ad group/campaign with CPA >3x target for pause
Budget sufficiency: Meta ≥5x CPA per ad set, TikTok ≥50x CPA per ad group
Learning phase: never recommend edits during active learning phase
Compliance: always check Special Ad Categories for housing/employment/credit/finance
Creative: never run silent video ads on TikTok (sound-on platform)
Attribution: default to 7-day click / 1-day view (Meta), data-driven (Google)
Andromeda creative diversity: Flag Meta accounts with <10 genuinely distinct creatives
Privacy infrastructure gate: Always verify tracking stack (Consent Mode V2, CAPI, Events API, AdAttributionKit) before making optimization recommendations
PDF report quality gate: When generating reports via /ads report, always use scripts/generate_report.py with --check first. Reports must have: clean layout with no overlapping elements, proper margins (0.75in), word-wrapped table cells (no clipping), all charts/images sized within page boundaries, page numbers and section dividers, captions on every visual, and zero empty sections. Run --check before --output and fix any warnings before delivering the PDF

Reference Files

Load these on-demand as needed; do NOT load all at startup.

Path resolution: All references are installed at ~/.claude/skills/ads/references/. When sub-skills or agents reference ads/references/*.md, resolve to ~/.claude/skills/ads/references/*.md.

references/audit-methodology.md: Shared 7-step audit process all platform skills delegate to. Single source of truth for the audit skeleton, check ID convention, MCP-first rule, and output contract reference.
references/audit-output-schema.json: Canonical JSON schema every audit-* agent must emit. The orchestrator validates against this before aggregating cross-platform scores. New integrations conform to this contract.
references/profile-schema.json: Schema for ~/.claude-ads/profile.json — the persistent user context written by /ads start and read by every command.
references/audit-history-schema.json: Schema for ~/.claude-ads/history/index.json — the audit log /ads next reads for regression detection.
references/setup-meta.md / setup-google.md / setup-tiktok.md: Step-by-step OAuth + MCP + manual connection walkthroughs loaded by /ads start Phase C.
references/setup-zernio.md / setup-meta-developers.md: Account-creation walkthroughs for optional integrations.
references/scoring-system.md: Weighted scoring algorithm and grading thresholds
references/benchmarks.md: Industry benchmarks by platform (CPC, CTR, CVR, ROAS)
references/bidding-strategies.md: Bidding decision trees per platform
references/budget-allocation.md: Platform selection matrix, scaling rules, MER
references/platform-specs.md: Creative specifications across all platforms
references/conversion-tracking.md: Pixel, CAPI, EMQ, ttclid implementation
references/compliance.md: Regulatory requirements, ad policies, privacy
references/google-audit.md: 80-check Google Ads audit checklist (includes YouTube video campaigns)
references/meta-audit.md: 50-check Meta Ads audit checklist
references/tiktok-audit.md: 28-check TikTok Ads audit checklist
references/brand-dna-template.md: Brand DNA schema and extraction guide
references/image-providers.md: Provider config (Gemini/OpenAI/Stability/Replicate)
references/google-creative-specs.md: PMax/RSA/YouTube generation-ready specs
references/meta-creative-specs.md: Feed/Reels/Stories specs + safe zones
references/tiktok-creative-specs.md: 9:16 only + safe zone overlay
references/gaql-notes.md: GAQL field compatibility, deduplication patterns, filter scope best practices
references/voice-to-style.md: Brand voice axis to visual attribute mapping for image generation
references/copy-frameworks.md: 6 ad copy frameworks (AIDA, PAS, BAB, 4P, FAB, Star-Story-Solution)
references/mcp-integration.md: Canonical MCP integration pattern + per-platform MCP server catalog
references/mcp-meta-integration.md: Meta MCP check↔tool mapping (template for new MCP integrations)

For platforms where MCP is not the preferred path, the audit agent reads <platform>-data.json produced by scripts/api/<platform>_fetch.py. These are pure-stdlib API adapters covering Meta, Google, and TikTok. See scripts/api/README.md for the per-platform OAuth setup walkthrough.

Scoring Methodology

Ads Health Score (0-100)

Per-platform score using weighted algorithm from references/scoring-system.md. Cross-platform aggregate weighted by budget share:

Aggregate = Sum(Platform_Score x Platform_Budget_Share)

Grading

Grade	Score	Action Required
A	90-100	Minor optimizations only
B	75-89	Some improvement opportunities
C	60-74	Notable issues need attention
D	40-59	Significant problems present
F	<40	Urgent intervention required

Priority Levels

Critical: Revenue/data loss risk (fix immediately)
High: Significant performance drag (fix within 7 days)
Medium: Optimization opportunity (fix within 30 days)
Low: Best practice, minor impact (backlog)

Sub-Skills

This skill orchestrates 19 specialized sub-skills:

ads-start: Guided first-run wizard — context capture, per-platform OAuth/MCP walkthroughs with verification, optional Zernio + Meta Developers signup, profile persistence to ~/.claude-ads/profile.json
ads-audit: Full multi-platform audit with parallel delegation across Meta / Google / TikTok
ads-next: Continuous coach — ranks Quick Wins from recent audits + history, detects regressions, optionally walks user through fixing #1
ads-google: Google Ads deep analysis (Search, PMax, YouTube video campaigns — they share the Google Ads API)
ads-meta: Meta Ads deep analysis (FB, IG, Advantage+) — MCP-wired to claude.ai Facebook
ads-tiktok: TikTok Ads deep analysis (Creative, Shop, Smart+, Symphony, GMV Max)
ads-creative: Cross-platform creative quality audit
ads-landing: Landing page quality for ad campaigns
ads-budget: Budget allocation and bidding strategy
ads-plan: Strategic ad planning with industry templates (8 templates after v2.3.0 scope-down)
ads-competitor: Competitor ad intelligence
ads-dna: Brand DNA extraction from website URL
ads-create: Campaign concepts, copy decks, creative briefs
ads-generate: AI image generation with pluggable providers
ads-photoshoot: Product photography in 5 professional styles
ads-update: Refresh per-platform references with last 30 days of changes
ads-math: PPC financial calculator (CPA, ROAS, break-even, LTV:CAC, MER)
ads-test: A/B test design (hypothesis, sample size, statistical significance)
ads-publish: Publish creatives to 14+ social networks via Zernio (first 2 accounts free)

Plus /ads report for PDF deliverable generation (implemented in scripts/generate_report.py, no SKILL.md).

Subagents

For parallel analysis during full audits — one deep specialist per platform:

audit-google: Google Ads 80-check audit (G01-G74, G-PM*, G-AI*, G-DG*, G-CTV*, G-WS*, G-KW*, G-CT*, G-AD*)
audit-meta: Meta Ads 50-check audit (M01-M40, M-AN*, M-AT*, M-CR*, M-ST*, M-IA*, M-TH*) — MCP-wired
audit-tiktok: TikTok Ads 28-check audit (T01-T25, T-SR*) — consolidates the former audit-creative/tracking/budget/compliance for TikTok into one deep-specialist agent

Creative pipeline agents (unchanged):

creative-strategist: Campaign concepts from brand profile + audit results (Opus, maxTurns: 25)
visual-designer: Image generation with brand injection via generate_image.py (Sonnet, maxTurns: 30)
copy-writer: Headlines, CTAs, primary text within platform limits (Sonnet, maxTurns: 20)
format-adapter: Asset dimension validation and spec compliance reporting (Haiku, maxTurns: 15)

Maintained by tododeia.com — Instagram @soyenriquerocha