| name | ads |
| description | Free-first paid advertising audit and optimization skill, focused on the 3 platforms where 95% of advertiser spend lives: Meta, Google, TikTok. Guided onboarding (/ads start) saves context once and step-by-step OAuth walkthroughs; continuous coach (/ads next) ranks Quick Wins after each audit. ~158 weighted checks with scoring, parallel agents, industry templates, and AI creative generation. |
| argument-hint | start | next | audit | google | meta | tiktok | creative | landing | budget | plan <type> | competitor | dna <url> | create | generate | photoshoot | update <platform|all> | publish |
| license | MIT |
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 thresholdsreferences/benchmarks.md: Industry benchmarks by platform (CPC, CTR, CVR, ROAS)references/bidding-strategies.md: Bidding decision trees per platformreferences/budget-allocation.md: Platform selection matrix, scaling rules, MERreferences/platform-specs.md: Creative specifications across all platformsreferences/conversion-tracking.md: Pixel, CAPI, EMQ, ttclid implementationreferences/compliance.md: Regulatory requirements, ad policies, privacyreferences/google-audit.md: 80-check Google Ads audit checklist (includes YouTube video campaigns)references/meta-audit.md: 50-check Meta Ads audit checklistreferences/tiktok-audit.md: 28-check TikTok Ads audit checklistreferences/brand-dna-template.md: Brand DNA schema and extraction guidereferences/image-providers.md: Provider config (Gemini/OpenAI/Stability/Replicate)references/google-creative-specs.md: PMax/RSA/YouTube generation-ready specsreferences/meta-creative-specs.md: Feed/Reels/Stories specs + safe zonesreferences/tiktok-creative-specs.md: 9:16 only + safe zone overlayreferences/gaql-notes.md: GAQL field compatibility, deduplication patterns, filter scope best practicesreferences/voice-to-style.md: Brand voice axis to visual attribute mapping for image generationreferences/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 catalogreferences/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-wiredaudit-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
