| 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:
- 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.
- 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:
- Industry / Business type — SaaS · E-commerce · Local Service · B2B Enterprise · Info Products · Mobile App · Real Estate · Healthcare · Finance · Agency · Other
- Monthly ad spend — total budget and per-platform breakdown
- Primary goal — Sales/Revenue · Leads/Demos · App Installs · Calls · Brand
- 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:
- Collect context (Context Intake above; do it first)
- Gather account data — exports, screenshots, or pasted metrics
- Detect business type and identify active platforms
- 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)
- Validate each subagent returned valid JSON scores with required fields before aggregating
- Aggregate into unified Ads Health Score (0-100)
- 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>:
- Phase 1 — Intelligence:
WebFetch the URL, extract business intelligence, detect business type, prepare the context package
- Phase 2 — Parallel agent launch (5 agents in the same response, via the
Agent tool):
strategy-audience (25% weight) → Audience Researchstrategy-creative (20% weight) → Creative & Copystrategy-funnel (20% weight) → Funnel Architecturestrategy-competitive (15% weight) → Competitive Intelligencestrategy-budget (20% weight) → Budget & ROI
- 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:
/ads dna <url> → brand-profile.json (current dir)/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 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 thresholdsreferences/benchmarks.md — Industry benchmarks by platform (CPC, CTR, CVR, ROAS)references/budget-allocation.md — Platform selection matrix, scaling rules, MERreferences/bidding-strategies.md — Bidding decision trees per platform
Platform & creative specs
references/platform-specs.md — Creative specifications across all platformsreferences/additional-platforms.md — Emerging platforms and formatsreferences/google-creative-specs.md — PMax / RSA / YouTube specsreferences/meta-creative-specs.md — Feed / Reels / Stories + safe zonesreferences/linkedin-creative-specs.md — Single image / video B2B constraintsreferences/tiktok-creative-specs.md — 9:16 only + safe zone overlayreferences/youtube-creative-specs.md — Skippable / Bumper / Shorts / Thumbnailreferences/microsoft-creative-specs.md — Multimedia Ads + RSA subsetreferences/image-providers.md — Provider config (Gemini/OpenAI/Stability/Replicate)
Audit checklists
references/google-audit.md — 74 checksreferences/meta-audit.md — 46 checksreferences/linkedin-audit.md — 25 checksreferences/tiktok-audit.md — 25 checksreferences/microsoft-audit.md — 20 checks
Compliance, tracking, integrations
references/compliance.md — Regulatory requirements, ad policies, privacyreferences/conversion-tracking.md — Pixel, CAPI, EMQ, ttclid implementationreferences/gaql-notes.md — GAQL field compatibility, deduplication, filter scopereferences/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 guidereferences/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, Microsoftaudit-tracking — Conversion tracking health across all platformsaudit-budget — Budget, bidding, structure for LinkedIn, TikTok, Microsoftaudit-compliance — Compliance, settings, performance across all platforms
Strategy subagents (5) — used by /ads strategy
strategy-audience — Audience research and personasstrategy-creative — Ad copy, hooks, creative conceptsstrategy-funnel — Campaign structure and conversion funnelsstrategy-competitive — Competitive intelligence and positioningstrategy-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:
- Platform-specific — ad content fits the exact specs and best practices of its platform
- Copy-paste ready — ad copy should be ready to paste into the platform without editing
- Audience-first — start with who you are targeting, then write the ad for them
- Data-backed — include estimated CPM/CPC/CPA ranges where possible
- Test-oriented — provide A/B variations, not a single version
- 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).
