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

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):

1. 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.)
2. Monthly ad spend: Total budget and per-platform breakdown (approximate is fine)
3. Primary goal: Sales / Revenue · Leads / Demos · App Installs · Calls · Brand
4. 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:

1. 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).
2. Collect account data (exports, screenshots, or pasted metrics — for connected platforms use the saved tier in connections.<p>.tier)
3. Detect business type and identify active platforms (from context.active_platforms if available)
4. 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
5. 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.
6. Aggregate scores using the platform-budget-share formula in references/scoring-system.md and generate the unified Ads Health Score (0-100)
7. Create prioritized action plan from the quick_wins and critical_issues arrays of each JSON
8. Persist to history — for each new audit JSON: python3 scripts/profile.py save-audit <platform>-audit-results.json. This feeds /ads next regression detection.
9. 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):

1. /ads dna <url> → brand-profile.json in current directory
2. /ads create → reads profile + optional audit results → campaign-brief.md
3. /ads generate → reads brief + profile → ad-assets/ directory
4. /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 prod