ads
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.
How do I install this agent skill?
npx skills add https://github.com/hainrixz/claude-ads --skill adsIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides a comprehensive suite for advertising audit and optimization across Meta, Google, and TikTok. It facilitates data collection via MCP servers, direct APIs, and manual exports. While it follows standard industry practices for ad-tech tooling, it includes several external dependencies and a mechanism to ingest brand data from external URLs, which creates a surface for indirect prompt injection.
- Socketwarn
1 alert: gptAnomaly
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
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 20 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 conciencia | Campaign awareness — tracks what Claude knows and doesn't know about real business results (closed customers, lead quality) of WhatsApp / form / call campaigns; dated check-ins cross-referenced with platform clicks and messages → real close rate. |
/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 startfirst — it saves ~30 sec per future command. Proceed inline instead? (Y/N) HonorN(proceed) by falling back to the inline Context Intake below. - Exit code
0(profile present) → parse the JSON and use the savedcontext.industry,context.monthly_spend_usd,context.primary_goal,context.active_platformsdirectly. Do NOT re-ask. Only re-ask if a field isnull/empty.
Then, for the same set of commands, run:
python3 scripts/conciencia.py due
If due is non-empty, before the requested command ask ONE
AskUserQuestion: "Tengo pendiente saber cómo le fue a <campaign(s)>.
¿Me cuentas ahora?" → Ahora runs the /ads conciencia check-in (Phase 3)
for every overdue campaign in one message, then resumes the requested
command · Después runs conciencia.py snooze <key> --days 1 for each and
continues. Never block the requested command on it.
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
generictemplate 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 startat 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_platformsif available) - Spawn subagents via Task tool with
context: fork— only forcontext.active_platforms(or those withconnections.<p>.tier != "skipped"):audit-google,audit-meta,audit-tiktok - Validate: each subagent writes both
<platform>-audit-results.jsonand<platform>-audit-results.md. Parse the JSON and validate againstreferences/audit-output-schema.jsonbefore 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.mdand generate the unified Ads Health Score (0-100) - Create prioritized action plan from the
quick_winsandcritical_issuesarrays of each JSON - Business-outcome awareness — for lead / message / call / form campaigns, run
python3 scripts/conciencia.py list. If an audited campaign has an awareness file, add itsclose_rate,cost_per_closeandjunk_rate(with check-in counts) next to the platform CPL in the summary and classify it with the reading table inreferences/conciencia.md. If none exists, report the business outcome asN/Aand offer/ads conciencia registrar. Skip for e-commerce with a purchase pixel. - Persist to history — for each new audit JSON:
python3 scripts/profile.py save-audit <platform>-audit-results.json. This feeds/ads nextregression detection. - Suggest the next step — point the user at
/ads nextfor 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.jsonin 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 usescripts/generate_report.pywith--checkfirst. 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--checkbefore--outputand 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 startand read by every command.references/audit-history-schema.json: Schema for~/.claude-ads/history/index.json— the audit log/ads nextreads for regression detection.references/conciencia-schema.json: Schema for~/.claude-ads/conciencia/<platform>-<campaign_id>.json— business outcomes per campaign written by/ads conciencia.references/conciencia.md: Awareness formulas (close rate, cost per close, junk rate), the platform-vs-business reading table, and threshold rules.references/setup-meta.md/setup-google.md/setup-tiktok.md: Step-by-step OAuth + MCP + manual connection walkthroughs loaded by/ads startPhase 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 20 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-conciencia: Campaign awareness — dated business-outcome check-ins (real conversations, qualified, closed, revenue, junk) cross-referenced with platform metrics; writes
conciencia-de-campana.md - 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
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/hainrixz/claude-ads/ads">View ads on skillZs</a>