ads

name	ads
description	End-to-end paid advertising skill for Claude Code: strategy generation, copy production, multi-platform audit, and client-ready reporting. Orchestrates 31 specialized sub-skills and 15 agents across Google, Meta, YouTube, LinkedIn, TikTok, Microsoft, and Apple Ads. 250+ weighted checks, 11 industry templates, 5-agent parallel strategy builds, a guided zero-to-sales blueprint, a guided execution companion that takes you from blueprint to launched campaigns and ongoing optimization, PDF + HTML reports, and AI creative generation.
argument-hint	blueprint [url] | blueprint-execution | strategy <url> | quick <url> | audience <url> | copy <platform> | hooks | video <product> | creative-brief <product> | creative-audit | funnel <url> | budget [amount] | keywords <url> | testing <campaign> | landing <url> | plan <industry> | competitor <url> | report-pdf | audit | google | meta | youtube | linkedin | tiktok | microsoft | apple | dna <url> | create | generate | photoshoot | math | test | help
license	MIT

maxym-ai-ads — The Unified Paid Ads Skill

A single /ads command that covers the full paid advertising lifecycle:

1. Upstream strategy — starting from a URL, generate personas, platform-specific copy, scroll-stopping hooks, video scripts, funnel architecture, A/B test plans, budget allocation, keyword research, and a client-ready PDF report.
2. Downstream audit — technical analysis of live ad accounts across Google, Meta, YouTube, LinkedIn, TikTok, Microsoft, and Apple Ads, with 250+ weighted checks, compliance quality gates, industry templates, and a 0-100 Ads Health Score.

The router below maps each sub-command to the sub-skill that owns it.

---

Quick Reference

🌟 Guided Experience (recommended for first-time users)

Command	What it does
/ads blueprint [url]	Flagship guided workflow — STRATEGY. Walks the user through all 5 phases of the Zero-to-Sales Blueprint interactively. Asks an initial questionnaire, runs each phase automatically, pauses at phase boundaries for confirmation, blocks on critical decision gates, and produces a final PDF + interactive HTML report + launch checklist. Supports --resume to continue after an interruption.
/ads blueprint-execution	Flagship guided workflow — EXECUTION. Takes the output of /ads blueprint and guides the user through putting it into practice: closes blocking gaps, pre-launch tracking setup, per-platform campaign build (step-by-step Meta/Google/LinkedIn/TikTok/Microsoft/Apple), launch day sequencing, learning-phase observation, and the bi-weekly optimization loop (3× Kill Rule, 20% Scaling Rule, creative fatigue detection). Accepts pasted metrics / CSV / screenshots. Produces a live HTML dashboard, per-platform setup guides, and an execution log.

Strategy & Planning

Command	What it does
/ads strategy <url>	5-agent parallel strategy build with Ad Readiness Score (0-100). Full report.
/ads quick <url>	60-second ad readiness snapshot: value prop, offer, trust, CTA, platform pick.
/ads audience <url>	Detailed audience personas with platform-specific targeting parameters.
/ads plan <industry>	Strategic ad plan using industry template (see Industries below).
/ads keywords <url>	Google Ads keyword strategy: match types, groupings, negatives.
/ads competitor <url>	Cross-platform competitor intelligence + "beat the competition" playbook.

Creative & Copy

Command	What it does
/ads copy <platform>	Platform-specific ad copy: Google RSA/PMax, Meta, LinkedIn, TikTok, YouTube, Pinterest.
/ads hooks	20 scroll-stopping hooks across proven psychological frameworks.
/ads video <product>	Video ad scripts in three durations: 15s, 30s, 60s.
/ads creative-brief <product>	Creative brief for designers, editors, photographers, and UGC creators.
/ads creative-audit	Cross-platform creative quality audit (copy, video, image, fatigue, diversity).

Funnel, Budget & Testing

Command	What it does
/ads funnel <url>	Full TOFU/MOFU/BOFU funnel architecture with retargeting flows.
/ads budget [amount]	With amount → allocation plan (3 scenarios + scaling roadmap). Without → budget audit.
/ads testing <campaign>	A/B testing plan with hypothesis, significance, duration, sample size.
/ads landing <url>	Landing page audit + CRO rewrite (flags --audit-only / --strategy-only).

Multi-Platform Audit

Command	What it does
/ads audit	Full multi-platform audit with 6 parallel subagents (Google, Meta, Creative, Tracking, Budget, Compliance).
/ads google	Google Ads deep analysis — Search, PMax, Display, YouTube, Demand Gen.
/ads meta	Meta Ads deep analysis — Facebook, Instagram, Advantage+.
/ads youtube	YouTube Ads — Skippable, Bumper, Shorts, Masthead.
/ads linkedin	LinkedIn Ads deep analysis — Sponsored Content, Message, Lead Gen, Thought Leader.
/ads tiktok	TikTok Ads deep analysis — Creative, Smart+, Spark, TikTok Shop.
/ads microsoft	Microsoft / Bing Ads — Copilot placements, Import, CTV inventory.
/ads apple	Apple Ads (App Store) — Search tab, Today tab, Custom Product Pages.

Creative Generation Pipeline

Command	What it does
/ads dna <url>	Extract brand DNA from a website → brand-profile.json.
/ads create	Generate campaign concepts + copy deck → campaign-brief.md.
/ads generate	Generate AI ad images from brief → ad-assets/ directory.
/ads photoshoot	Product photography in 5 styles (Studio, Floating, Ingredient, In Use, Lifestyle).

Utilities & Reporting

Command	What it does
/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	Client-ready PDF strategy/audit report via ReportLab.
/ads help	Show the full command list.
/ads (no args)	Alias for /ads help.

---

Routing Table

Each sub-command loads its matching sub-skill from skills/ads-*/SKILL.md.

Sub-command	Sub-skill path
blueprint	skills/ads-blueprint/
blueprint-execution	skills/ads-blueprint-execution/
strategy	skills/ads-strategy/
quick	skills/ads-quick/
audience	skills/ads-audience/
plan	skills/ads-plan/
keywords	skills/ads-keywords/
competitor	skills/ads-competitor/
copy	skills/ads-copy/
hooks	skills/ads-hooks/
video	skills/ads-video/
creative-brief	skills/ads-creative-brief/
creative-audit	skills/ads-creative-audit/
funnel	skills/ads-funnel/
budget	skills/ads-budget/
testing	skills/ads-testing/
landing	skills/ads-landing/
audit	skills/ads-audit/
google	skills/ads-google/
meta	skills/ads-meta/
youtube	skills/ads-youtube/
linkedin	skills/ads-linkedin/
tiktok	skills/ads-tiktok/
microsoft	skills/ads-microsoft/
apple	skills/ads-apple/
dna	skills/ads-dna/
create	skills/ads-create/
generate	skills/ads-generate/
photoshoot	skills/ads-photoshoot/
math	skills/ads-math/
test	skills/ads-test/
report-pdf	skills/ads-report-pdf/

---

Smart Routing (Disambiguation)

When a user types an ambiguous short command, ask once, briefly:

• /ads creative → ask: "Do you want a creative brief for designers (creative-brief) or a quality audit of existing ads (creative-audit)?"
• /ads test vs /ads testing → explain: test is the PPC A/B calculator; testing is the full A/B testing plan for a campaign.

For typos, propose the closest match (e.g. competitors → competitor; headsup → hooks).

---

Context Intake (Required before any audit or analysis)

Collect this context before running audit or strategy work. Ask in one message:

1. Industry / Business type — SaaS · E-commerce · Local Service · B2B Enterprise · Info Products · Mobile App · Real Estate · Healthcare · Finance · Agency · Other
2. Monthly ad spend — total budget and per-platform breakdown
3. Primary goal — Sales/Revenue · Leads/Demos · App Installs · Calls · Brand
4. Active platforms — currently advertising on which networks?

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

Use the collected 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 ($500/mo account priorities ≠ $50k/mo account)

---

Orchestration Logic — Full Audit

When the user runs /ads audit:

1. Collect context (Context Intake above; do it first)
2. Gather account data — exports, screenshots, or pasted metrics
3. Detect business type and identify active platforms
4. Dispatch 6 subagents in parallel via the Task tool with context: fork:
   • audit-google (G01-G74, 74 checks)
   • audit-meta (M01-M46, 46 checks)
   • audit-creative (cross-platform creative audit)
   • audit-tracking (conversion tracking health)
   • audit-budget (budget, bidding, structure for LinkedIn/TikTok/Microsoft)
   • audit-compliance (compliance + settings + performance, all platforms)
5. Validate each subagent returned valid JSON scores with required fields before aggregating
6. Aggregate into unified Ads Health Score (0-100)
7. Produce a prioritized action plan with Quick Wins

For single-platform audits (/ads google, /ads meta, …) load the sub-skill directly; still collect context first.

---

Orchestration Logic — Strategy Build

When the user runs /ads strategy <url>:

1. Phase 1 — Intelligence: WebFetch the URL, extract business intelligence, detect business type, prepare the context package
2. Phase 2 — Parallel agent launch (5 agents in the same response, via the Agent tool):
   • strategy-audience (25% weight) → Audience Research
   • strategy-creative (20% weight) → Creative & Copy
   • strategy-funnel (20% weight) → Funnel Architecture
   • strategy-competitive (15% weight) → Competitive Intelligence
   • strategy-budget (20% weight) → Budget & ROI
3. Phase 3 — Synthesis: compute the composite Ad Readiness Score (0-100) and write the final unified report

---

Creative Generation Pipeline

Sequential but each step is independently runnable:

1. /ads dna <url> → brand-profile.json (current dir)
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 the 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 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

Available industry templates for /ads plan <industry>: saas · ecommerce · local-service · b2b-enterprise · info-products · mobile-app · real-estate · healthcare · finance · agency · generic

---

Quality Gates (Hard Rules)

Never violate these rules regardless of what the user asks:

• Never recommend Broad Match without Smart Bidding (Google)
• 3× Kill Rule: flag any ad group/campaign with CPA >3× target for pause
• Budget sufficiency: Meta ≥5× CPA per ad set, TikTok ≥50× CPA per ad group
• Learning phase: never recommend edits during an 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: always verify tracking stack (Consent Mode V2, CAPI, Events API, AdAttributionKit) before optimization recommendations
• PDF report quality: when generating via /ads report-pdf, use scripts/generate_report.py with --check first; fix any warnings before --output. Reports must have clean layout, 0.75in margins, word-wrapped cells, no oversized charts, page numbers and section dividers, captions on every visual, and zero empty sections

---

Reference Files

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

Path resolution: references live at ads/references/ (repo) → ~/.claude/skills/ads/references/ (after install). When a sub-skill or agent references ads/references/*.md, resolve to that installed path.

Scoring & benchmarks

• references/scoring-system.md — Weighted scoring algorithm and grading thresholds
• references/benchmarks.md — Industry benchmarks by platform (CPC, CTR, CVR, ROAS)
• references/budget-allocation.md — Platform selection matrix, scaling rules, MER
• references/bidding-strategies.md — Bidding decision trees per platform

Platform & creative specs

• references/platform-specs.md — Creative specifications across all platforms
• references/additional-platforms.md — Emerging platforms and formats
• references/google-creative-specs.md — PMax / RSA / YouTube specs
• references/meta-creative-specs.md — Feed / Reels / Stories + safe zones
• references/linkedin-creative-specs.md — Single image / video B2B constraints
• references/tiktok-creative-specs.md — 9:16 only + safe zone overlay
• references/youtube-creative-specs.md — Skippable / Bumper / Shorts / Thumbnail
• references/microsoft-creative-specs.md — Multimedia Ads + RSA subset
• references/image-providers.md — Provider config (Gemini/OpenAI/Stability/Replicate)

Audit checklists

• references/google-audit.md — 74 checks
• references/meta-audit.md — 46 checks
• references/linkedin-audit.md — 25 checks
• references/tiktok-audit.md — 25 checks
• references/microsoft-audit.md — 20 checks

Compliance, tracking, integrations

• references/compliance.md — Regulatory requirements, ad policies, privacy
• references/conversion-tracking.md — Pixel, CAPI, EMQ, ttclid implementation
• references/gaql-notes.md — GAQL field compatibility, deduplication, filter scope
• references/mcp-integration.md — Live API integrations for competitive data

Creative & brand

• references/copy-frameworks.md — 6 copy frameworks (AIDA, PAS, BAB, 4P, FAB, Star-Story-Solution)
• references/brand-dna-template.md — Brand DNA schema and extraction guide
• references/voice-to-style.md — Brand voice axis → visual attribute mapping

---

Ads Health Score (0-100)

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

Aggregate = Σ(Platform_Score × 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 (31)

This skill orchestrates 31 specialized sub-skills grouped by purpose.

Guided experience (2): ads-blueprint · ads-blueprint-execution Strategy & planning (6): ads-strategy · ads-quick · ads-audience · ads-plan · ads-keywords · ads-competitor Creative & copy (5): ads-copy · ads-hooks · ads-video · ads-creative-brief · ads-creative-audit Funnel, budget & testing (4): ads-funnel · ads-budget · ads-testing · ads-landing Audit (7 platforms + orchestrator): ads-audit · ads-google · ads-meta · ads-youtube · ads-linkedin · ads-tiktok · ads-microsoft · ads-apple Creative pipeline (4): ads-dna · ads-create · ads-generate · ads-photoshoot Utilities & reporting (3): ads-math · ads-test · ads-report-pdf

---

Subagents (15)

For parallel analysis during full audits and strategy builds.

Audit subagents (6) — used by /ads audit

• audit-google — Google Ads checks (G01-G74)
• audit-meta — Meta Ads checks (M01-M46)
• audit-creative — Creative quality for LinkedIn, TikTok, Microsoft
• audit-tracking — Conversion tracking health across all platforms
• audit-budget — Budget, bidding, structure for LinkedIn, TikTok, Microsoft
• audit-compliance — Compliance, settings, performance across all platforms

Strategy subagents (5) — used by /ads strategy

• strategy-audience — Audience research and personas
• strategy-creative — Ad copy, hooks, creative concepts
• strategy-funnel — Campaign structure and conversion funnels
• strategy-competitive — Competitive intelligence and positioning
• strategy-budget — Budget allocation and ROI projection

Creative pipeline helpers (4) — used by /ads create, /ads generate, /ads photoshoot

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

---

Output Standards

All outputs follow these rules:

1. Platform-specific — ad content fits the exact specs and best practices of its platform
2. Copy-paste ready — ad copy should be ready to paste into the platform without editing
3. Audience-first — start with who you are targeting, then write the ad for them
4. Data-backed — include estimated CPM/CPC/CPA ranges where possible
5. Test-oriented — provide A/B variations, not a single version
6. Client-ready — reports should be presentable to clients without editing

File outputs default to the current working directory with descriptive filenames. PDF reports are generated via scripts/generate_ads_pdf.py (and scripts/generate_report.py for audit PDFs).