The Complete Guide to AI Marketing Agents and Skills: OpenClaw and Claude Code vs. Hyper

---
name: paid-ads-daily-briefing
description: "Analyze daily ad performance from Google Ads and Meta Ads and deliver a formatted summary to Slack. Use when automating daily performance monitoring, setting up a morning advertising report, or creating scheduled PPC alerts."
metadata:
  version: 1.2.0
  integrations:
    ad_platforms: ["Hyper (native)", "Hyper MCP", "Custom ad platform MCP"]
    communication: ["Hyper (native)", "Slack MCP"]
---

# Paid Ads: Daily Performance Briefing

Provide a concise, actionable summary of yesterday's advertising performance across Google and Meta, delivered to a designated Slack channel. The goal is to surface what changed and what needs attention — not to recap every metric.

## Before Starting

1. Check for a .agents/product-marketing-context.md file. If it exists, read it first — it contains business goals, target CPA/ROAS, and key products that determine what counts as "good" or "bad" performance.
2. Confirm these parameters (ask if not provided):
    - Target CPA for lead gen campaigns (default: $75)
    - Target ROAS for e-commerce campaigns (default: 3.0)
    - Slack channel ID for delivery (e.g., C02A4B8XYZ)
    - Alert sensitivity — the % change threshold that warrants flagging (default: 20%)

## Workflow

1. **Schedule:** Run daily at 8:00 AM local time.
2. **Fetch data** for both Google Ads and Meta Ads. Pull the last full day (T-1) and the day before (T-2) at the campaign, ad group/ad set, and creative level. Required metrics: spend, impressions, clicks, cpa, roas, conversions, ctr.
3. **Analyze for anomalies:**
    - Flag campaigns where spend changed by more than the alert threshold. Categorize as "spike" or "drop" — this distinction matters because a 30% spike in a well-performing campaign is good news, while a 30% spike in a failing campaign is a budget leak.
    - Flag ad groups where CPA exceeds the target. Include the actual CPA and the gap above target so the reader can gauge severity at a glance.
    - Rank all active creatives by ROAS. Extract the top 3 and bottom 3 across both platforms.
    - Check for diminishing returns: if spend has increased for 3+ consecutive days without a corresponding increase in conversions, flag it. This pattern often indicates audience saturation or frequency fatigue.
4. **Format for Slack** using Block Kit. Organize into sections: Spend Alerts, CPA Alerts, Top Performers, Bottom Performers, Trends. Include a one-sentence recommendation per alert (e.g., "Consider pausing" or "Increase budget").
5. **Send** to the configured channel.

## Error Handling

- If an API call fails or returns no data, include "Data for [Platform] could not be retrieved" in the report. Never send an empty report — it looks like the automation broke.
- If total spend for a platform was $0, state that and skip the analysis for that platform. Division-by-zero on CPA/ROAS calculations will produce garbage.
- If only one platform returns data, send the report with what's available rather than waiting.
- Note at the top of every report that ad platform data can be delayed by up to 24 hours, so the numbers are preliminary.

---
name: meta-ads-campaign-builder
description: "Build and launch a complete Meta Ads campaign from a brief — including campaign structure, audience targeting, creative upload, and budget configuration. Use when launching new Meta ad campaigns, setting up Facebook or Instagram advertising, or automating campaign creation from a marketing brief."
metadata:
  version: 1.0.0
  integrations:
    ad_platforms: ["Hyper (native)", "Hyper MCP", "Custom ad platform MCP"]
    creative: ["Hyper (native — brand-aware generation)", "Flux API", "Gemini Imagen API"]
---

# Meta Ads: Campaign Creation & Launch

Take a campaign brief and translate it into a fully structured, correctly configured Meta Ads campaign — ready to go live. The goal is to handle the entire setup process: objective selection, audience configuration, placement strategy, creative upload, budget allocation, and launch — with the same care an experienced media buyer would apply.

## Before Starting

Confirm these inputs (ask if not provided):
- Campaign objective in business terms (e.g., "generate leads for a SaaS product," "drive online purchases," "build awareness for a product launch")
- Target audience description (demographics, interests, behaviors, or existing custom/lookalike audience IDs)
- Geographic targeting (countries, regions, or radius targeting)
- Daily or lifetime budget
- Creative assets (images/videos) or a brief for generating them
- Landing page URL
- Pixel ID and conversion event to optimize for
- Campaign naming convention (if the account uses one)

## Workflow

1. **Map the business objective to Meta's campaign objectives.** This is where most mistakes happen. Meta offers six Advantage+ objectives: Awareness, Traffic, Engagement, Leads, App Promotion, and Sales. "Generate leads" could mean Leads objective (on-platform lead forms) or Sales objective optimized for a lead event on the website. Clarify the distinction before proceeding — the wrong choice means Meta's algorithm optimizes for the wrong behavior.
2. **Configure Campaign Budget Optimization (CBO).** Use CBO rather than ad set-level budgets in most cases — it lets Meta allocate spend across ad sets based on performance. Set a minimum spend per ad set (10-20% of the daily budget) to prevent Meta from starving a new ad set before it has enough data.
3. **Build ad sets with audience structure:**
    - Create 2-3 ad sets with distinct audience segments: one broad (Advantage+ Audience with suggested targeting), one interest-based, one lookalike (if a source audience exists). This structure tests audience approaches against each other.
    - Set exclusions to prevent overlap — exclude purchasers from prospecting ad sets, exclude one interest group from another if they share significant overlap.
    - Use Advantage+ Placements unless the creative is format-specific (e.g., Reels-only video). Manual placement selection usually reduces reach without improving performance.
4. **Configure optimization and bidding:**
    - Set the conversion event that matches the business goal. For lead gen: Lead or CompleteRegistration. For e-commerce: Purchase (not AddToCart — optimizing for AddToCart finds browsers, not buyers).
    - Use "Maximize conversions" bid strategy for new campaigns. Cost cap and ROAS targets require historical data to work effectively — setting them on a new campaign usually just restricts delivery.
    - Set the attribution window to 7-day click, 1-day view (Meta's default and generally the best starting point).
5. **Upload and configure creatives:**
    - If assets are provided, upload them with correct aspect ratios per placement: 1:1 for Feed, 9:16 for Stories/Reels, 1.91:1 for right column.
    - If a brief is provided instead of assets, generate images using the configured creative integration (Hyper generates on-brand creatives using your logo, colors, and design system; standalone APIs generate generic images from a style prompt). Constrain to no text in the image — Meta penalizes text-heavy images and text renders poorly at small sizes.
    - Write primary text (max 125 chars for optimal display), headline (max 40 chars), and description for each ad. The primary text should address the audience's pain point. The headline should state the value proposition. The description is often truncated — use it for supporting detail, not critical information.
    - Create 3-5 ad variations per ad set. More variations give Meta's algorithm more to test.
6. **Set naming conventions.** Apply consistent naming at every level: Campaign: [Brand]_[Objective]_[Date]. Ad Set: [Audience]_[Geo]_[Optimization]. Ad: [Creative_Type]_[Angle]_[Version]. Without consistent naming, analyzing results across dozens of campaigns becomes impossible.
7. **Review and launch.** Before publishing, verify: Pixel is firing on the landing page, conversion event is correctly configured, daily budget matches the brief, audiences don't overlap excessively, and creative assets meet Meta's specifications.

## Error Handling

- If the Pixel is not detected on the landing page URL, flag this as a blocking issue. Launching without tracking wastes the entire budget.
- If a creative asset fails Meta's review (text policy, prohibited content), log the rejection reason and continue with remaining creatives.
- If the campaign's estimated audience size is below 100,000, warn that delivery may be limited and suggest broadening targeting.
- After launch, schedule a check-in 24 hours later to verify the campaign is delivering and learning phase metrics are on track.

---
name: google-ads-pmax-optimization
description: "Monitor, analyze, and optimize Google Ads Performance Max campaigns — including asset group performance, search theme refinement, audience signal tuning, and budget allocation. Use when managing PMax campaigns, analyzing Performance Max results, optimizing Google Ads automated campaigns, or diagnosing underperforming PMax asset groups."
metadata:
  version: 1.0.0
  integrations:
    ad_platforms: ["Hyper (native)", "Hyper MCP", "Custom ad platform MCP"]
---

# Google Ads: Performance Max Optimization

Provide ongoing management and optimization of Performance Max campaigns by analyzing asset group performance, refining search themes, tuning audience signals, and managing budget allocation. PMax is powerful but opaque — the value of this skill is surfacing actionable insights from limited reporting and making the adjustments that keep the algorithm pointed in the right direction.

## Before Starting

Confirm these parameters (ask if not provided):
- Google Ads account ID (Customer ID)
- Target CPA or target ROAS for each PMax campaign
- Business context: what products/services each campaign promotes, and what a "good" conversion looks like
- Brand terms to monitor (to assess how much PMax cannibalizes branded search)
- Review frequency (default: weekly)

## Workflow

1. **Schedule:** Run weekly, every Monday.
2. **Pull campaign-level performance.** Fetch spend, conversions, conversion value, CPA, ROAS, impression share, and search impression share for each PMax campaign. Compare against the previous week and the 4-week average. Flag any campaign where CPA increased by more than 15% or ROAS dropped by more than 15%.
3. **Analyze asset group performance.** Within each campaign, break performance down by asset group. Identify asset groups that are consuming disproportionate budget relative to their conversion rate — PMax will sometimes funnel spend into a high-impression, low-conversion asset group because it's optimizing for a local maximum rather than the campaign goal.
4. **Review asset performance ratings.** Google rates individual assets (headlines, descriptions, images, videos) as Low, Good, or Best. Extract assets rated "Low" and flag them for replacement. Assets rated "Best" should be studied for patterns — if all top-performing headlines mention a specific feature or benefit, that's a signal for creative direction.
5. **Audit search themes.** Pull the search terms report (where available — PMax reporting is limited but provides category-level insights). Check if the campaign is capturing relevant queries or drifting into irrelevant territory. Recommend new search themes to add or existing ones to remove. Each asset group supports up to 25 search themes — use them to steer the algorithm.
6. **Check for brand cannibalization.** Compare PMax's branded search impressions against dedicated branded Search campaigns. If PMax is capturing a large share of branded queries, those conversions likely would have happened anyway — the PMax campaign is taking credit for cheap branded traffic rather than finding new customers. Recommend brand exclusions at the campaign level if this pattern is significant.
7. **Evaluate audience signals.** Review the audience signals attached to each asset group. Signals are directional hints, not hard restrictions — Google will expand beyond them. If a campaign is performing well, the original signals are working as a starting point. If performance is poor, the signals may be too narrow or too broad. Recommend adjustments.
8. **Generate a weekly report** with: campaign-level performance summary, asset group breakdown with recommendations, underperforming assets to replace, search theme recommendations, brand cannibalization assessment, and overall budget allocation recommendation.

## Error Handling

- PMax reporting is intentionally limited by Google. If specific metrics aren't available (e.g., placement-level data), note the gap and work with what's available rather than making assumptions.
- Do not evaluate PMax performance during the learning period (typically 6-8 weeks for new campaigns, 1-2 weeks after significant changes). Making adjustments during learning disrupts the algorithm.
- If a PMax campaign has fewer than 30 conversions in the evaluation period, note that the data is insufficient for reliable analysis. Recommend either extending the evaluation window or increasing budget.
- Watch for the "PMax steals from Search" pattern: if a standard Search campaign's impression share drops when PMax launches, the two campaigns are likely competing. Recommend restructuring.

---
name: competitive-intelligence-meta-ads
description: "Scrape and analyze a competitor's latest ads from the Meta Ads Library. Use when researching competitor advertising, building a swipe file, understanding a competitor's messaging strategy, or preparing for a creative brainstorm with competitive context."
metadata:
  version: 1.1.0
  integrations:
    scraping: ["Hyper (native — built-in Meta Ads Library scraper)", "Browser automation"]
---

# Competitive Intelligence: Meta Ads Library Analysis

Systematically scrape a competitor's active ads from the Meta Ads Library, categorize their strategy, and produce a structured competitive intelligence report.

## Before Starting

Confirm these inputs (ask if not provided):
- Competitor's Facebook Page URL (e.g., https://www.facebook.com/competitorinc)
- Competitor's name (used in file naming and report headers)
- Time window to analyze (default: last 7 days)
- Any specific focus areas (e.g., "only video ads" or "only ads linking to pricing pages")

## Workflow

1. **Navigate** to the Meta Ads Library filtered for the competitor. URL format: https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=ALL&q=[PAGE_NAME]&sort_data[direction]=desc&sort_data[mode]=relevancy_monthly_grouped
2. **Filter** to "Active" ads within the configured time window.
3. **Scrape all ads.** Scroll through the results, waiting 2 seconds between scrolls for content to load. Stop when 3 consecutive scrolls produce no new ads. For each ad, extract: primary text, image/video thumbnail URL, headline, CTA text, destination URL, and approximate launch date.
4. **Save creative assets** locally. Use a consistent naming convention: [competitor]_[YYYY-MM-DD]_[sequential_number].jpg.
5. **Categorize each ad** along three dimensions:
    - **Core Offer:** discount, free trial, webinar, content download, direct purchase, or brand awareness
    - **Messaging Angle:** pain point, benefit highlight, social proof, urgency/scarcity, comparison, or educational
    - **Inferred Audience:** based on language, imagery, and where the landing page sits in the funnel
6. **Identify patterns.** Look beyond individual ads: Are they running multiple angles for the same offer (a sign of creative testing)? Increasing or decreasing creative volume? Running sequential campaigns that tell a story?
7. **Generate the report** as competitor_report_[competitor_name]_[date].md:
    - Executive summary of their current advertising strategy (2-3 paragraphs)
    - Volume metrics: total active ads, new ads in the time window, image vs. video ratio
    - Table of all ads: Creative Link | Headline | Offer Type | Messaging Angle | Audience | Destination URL
    - Strategic observations and recommended counter-positioning for your team

## Error Handling

- If the Meta Ads Library UI changes and element selectors break, stop and report the issue. A partial scrape with incorrect data is worse than no scrape.
- If the library returns no results, verify the page URL is correct before reporting.
- If an individual ad's creative fails to save, log the failure and continue — don't block the entire report over one missing image.

---
name: ad-creative-testing-at-scale
description: "Generate and launch a full set of Meta Ads from a creative matrix of topics, personas, and visual styles. Use for large-scale A/B testing, creative iteration, campaign launches, or systematic ad creative exploration across multiple messaging angles."
metadata:
  version: 1.0.0
  integrations:
    ad_platforms: ["Hyper (native)", "Hyper MCP", "Custom ad platform MCP"]
    creative: ["Hyper (native — brand-aware, generates from URL/brief)", "Flux API", "Gemini Imagen API"]
---

# Ad Creative Testing at Scale

Take a creative matrix (topics x personas x visual styles) and generate every combination as a complete Meta ad — copy, image, and upload. This approach replaces the manual process of writing and designing dozens of ad variations by hand, which is the main bottleneck in creative testing at scale.

## Before Starting

Confirm these inputs (ask if not provided):
- Path to creative_matrix.txt or the matrix content directly
- Meta Ads Campaign ID and Ad Set ID
- Brand voice guidelines, reference copy, or website URL for brand extraction
- Maximum number of ads to create as a safety limit (default: 27)

## Workflow

1. **Parse the creative matrix.** Read creative_matrix.txt. Expected format uses section headers:
    --TOPICS--
    AI-powered automation
    Save 10 hours a week
    Reduce human error
    --PERSONAS--
    Marketing Manager
    Agency Owner
    Solo Founder
    --STYLES--
    Minimalist typography on dark background
    Abstract tech illustration
    Lifestyle photo with text overlay
2. **Calculate all combinations** (Topic x Persona x Style). Display the total count. If it exceeds the safety limit, ask the user to either raise the limit or trim the matrix. Launching 200 ads by accident is expensive and clutters the ad account — this confirmation step prevents it.
3. **For each combination, generate the ad:**
    - **Copy:** Write a headline (max 40 chars) and primary text (max 125 chars) tailored to the specific combination. The headline should address the persona's pain point directly. The primary text should frame the topic as the solution. Each variation should feel distinct — if they all read like the same ad with a swapped noun, the test won't reveal anything useful.
    - **Image:** Generate using the configured creative integration. On Hyper, images are generated on-brand using your logo, colors, and design system — with no text in the image (Meta penalizes text-heavy images). With external APIs, construct a prompt specifying the visual style, brand colors (if known), and the no-text constraint. Save locally.
    - **Upload** to the ad platform with the headline, primary text, and image.
4. **Add all creatives to the campaign** in a loop.
5. **Generate a tracking CSV** mapping each ad to its Topic, Persona, Style, Headline, and Creative ID. Without this, analyzing results later requires manually cross-referencing dozens of ads.

## Error Handling

- If image generation fails, log the error, skip that combination, and continue. Note all skipped combinations in the final summary.
- If Meta rejects a creative (e.g., text policy violation), log the rejection reason and continue. Don't halt the entire batch over one rejected ad.
- Name each creative systematically: [Topic_short]_[Persona_short]_[Style_short]_[Date]. This makes the Ads Manager readable when you have 27+ creatives.
- Before creating each ad, check if one with the same name already exists. Skip duplicates.

---
name: paid-media-budget-pacing
description: "Keep monthly ad spend on track by calculating pacing ratios and adjusting daily campaign budgets. Use when automating budget management, preventing overspending, ensuring campaigns pace correctly through the month, or optimizing budget utilization toward end-of-month."
metadata:
  version: 1.1.0
  integrations:
    ad_platforms: ["Hyper (native)", "Hyper MCP", "Custom ad platform MCP"]
---

# Paid Media: Budget Pacing & Management

Prevent over- or under-spending of the monthly advertising budget by making small, daily adjustments to campaign daily budgets. The key insight is that ad platform "daily budgets" are soft limits — actual spend can vary by 20%+ on any given day, so pacing needs active management rather than set-and-forget.

## Before Starting

Confirm these parameters (ask if not provided):
- Total monthly budget (e.g., $10,000)
- Pacing tolerance (default: 5% — act if spend deviates by more than this from ideal pace)
- Maximum budget adjustment per campaign per day (default: 10%)
- Minimum daily budget floor per campaign (default: $10 — going lower effectively pauses the campaign)
- Maximum daily budget ceiling per campaign (default: 2x the original daily budget — prevents runaway spend)
- Priority metric for budget increases (default: ROAS)

## Workflow

1. **Schedule:** Run daily at 7:00 AM.
2. **Calculate pacing:**
    - Ideal Daily Pace = Total Budget / Total Days in Month
    - Ideal MTD Spend = Ideal Daily Pace * Days Passed
    - Pacing Ratio = Actual MTD Spend / Ideal MTD Spend
    - A ratio of 1.0 means perfectly on pace. Above 1.0 means over-spending. Below 1.0 means under-spending.
3. **Fetch spend data.** Get MTD spend and ROAS broken down by campaign.
4. **Adjust based on pacing:**
    - **Over-pacing (ratio > 1 + tolerance):** Identify the top 3 campaigns by spend. Decrease their daily budget by the configured adjustment percentage. Never go below the floor — a $2/day budget doesn't generate meaningful data, it just wastes the minimum spend.
    - **Under-pacing (ratio < 1 - tolerance):** Identify the top 3 campaigns by ROAS. Increase their daily budget by the configured adjustment percentage. Never exceed the ceiling. Prioritizing by ROAS ensures extra budget goes to what's already working, not spread equally across underperformers.
    - **On-pace:** Log "Pacing on track" with the current ratio. No action needed.
5. **End-of-month acceleration.** In the last 3 days of the month, double the adjustment percentage. Unused budget at month-end is wasted allocation. If under-pacing by more than 15% with 2 days remaining, flag for manual review — the gap may be too large for automated adjustments alone.
6. **Log every change:** campaign ID, campaign name, old budget, new budget, pacing ratio, and reason. Budget changes without a paper trail are untraceable when something goes wrong.

## Error Handling

- If spend data for a campaign is unavailable, skip it and note the gap in the log.
- If the API returns a rate limit error, wait 60 seconds and retry once.
- On first run, store the original daily budget for each campaign. This becomes the reference point for ceiling calculations across future runs.

---
name: google-ads-negative-keywords
description: "Analyze Google Ads search term reports to find irrelevant queries wasting budget and add them as negative keywords. Use when reducing wasted ad spend, cleaning up Google Ads accounts, automating negative keyword management, or improving campaign efficiency through search term hygiene."
metadata:
  version: 1.2.0
  integrations:
    ad_platforms: ["Hyper (native)", "Hyper MCP", "Custom ad platform MCP"]
---

# Google Ads: Negative Keyword Management

Continuously improve campaign efficiency by identifying irrelevant search queries that are burning budget without converting, and adding them as negative keywords. This skill automates the cleanup that PPC managers typically do manually every Monday morning.

## Before Starting

Confirm these parameters (ask if not provided):
- Minimum click threshold for a search term to be reviewed (default: 10 clicks with zero conversions)
- Negative keyword match type (default: exact match)
- Application level (default: ad group — more precise than campaign-level negatives because a term that's irrelevant in one ad group might be valuable in another)
- Additional negative patterns beyond the default list
- Review period (default: last 7 days)

## Workflow

1. **Schedule:** Run weekly, every Monday.
2. **Fetch the search term report** for the configured period. Pull: search term, clicks, impressions, conversions, cost, ad group, and campaign.
3. **Filter for waste.** Extract terms where conversions == 0 AND clicks >= the configured threshold. Calculate wasted spend for each term.
4. **Pattern matching.** Check each filtered term against the negative pattern list:
    Default patterns: ["free", "jobs", "how to", "reviews", "cheap", "salary", "reddit", "youtube", "tutorial", "course", "download", "cracked", "torrent", "diy", "internship", "template", "example", "sample"]
    Also flag terms that are clearly unrelated to the account's product/service.
5. **Classify by confidence:**
    - **Auto-negate (high confidence):** Contains a negative pattern and no product-relevant keywords. Add these immediately.
    - **Review queue (medium confidence):** Contains a negative pattern BUT also contains a relevant product keyword. These need human judgment — "free CRM tutorial" might be irrelevant for a paid CRM, but "free trial CRM" is a high-intent query. Save to review_queue_[date].md.
    - **Skip (low confidence):** Zero conversions but no pattern match, and fewer than 20 clicks. These terms may just need more data before judging them.
    This classification matters because blindly negating every zero-conversion term blocks queries that simply haven't converted *yet* — especially for high-consideration B2B products with long sales cycles.
6. **Add negative keywords.** For each auto-negate term, add as exact match at the ad group level.
7. **Check for duplicates** before adding. If the negative already exists, skip it.
8. **Generate a weekly summary:**
    - Total negatives added
    - Estimated spend saved (sum of wasted spend on negated terms)
    - Terms sent to the review queue
    - Top 5 most expensive wasted terms
    - If more than 50 terms qualify for auto-negation in a single week, flag for manual review — this usually indicates a broader targeting problem (wrong match types, too-broad keywords) rather than just a few bad queries.

---
name: ab-testing-statistical-analysis
description: "Monitor running A/B tests and declare a winner when statistical significance is reached. Use when automating A/B test analysis, eliminating bias from test conclusions, ensuring optimal budget allocation, or preventing tests from running too long past significance."
metadata:
  version: 1.1.0
  integrations:
    ad_platforms: ["Hyper (native)", "Hyper MCP", "Custom ad platform MCP"]
    communication: ["Hyper (native)", "Slack MCP"]
---

# A/B Testing: Statistical Analysis & Optimization

Monitor active A/B tests, apply a two-proportion z-test when minimum sample sizes are met, and declare a winner only when the statistics warrant it. The value here is twofold: stopping winning tests from running too long (leaving money on the table) and stopping losing tests from being called too early (wasting the data collected so far).

## Before Starting

Confirm these parameters (ask if not provided):
- Minimum confidence level to declare a winner (default: 95%)
- Minimum conversions per variation before concluding (default: 50 — below this, conversion rates are too noisy to be meaningful)
- Minimum test duration (default: 7 days — this guards against the novelty effect, where new ads temporarily outperform due to freshness rather than quality)
- Action on the losing variation: auto-pause or flag for human review
- Slack channel for notifications (optional)

## Workflow

1. **Schedule:** Run daily.
2. **Identify active tests.** Filter for campaigns containing "A/B Test" or "Test" in the name, or tagged with a test label.
3. **Check eligibility.** For each test:
    - Calculate days since launch. If below the minimum duration, skip it and note how many days remain. Even if the data looks significant early, the novelty effect can reverse results after day 3-4.
    - Fetch performance data for each variation: conversions, impressions, clicks, spend, conversion rate.
    - Check the minimum sample size. If any variation has fewer than the required conversions, skip and note the gap.
4. **Calculate statistical significance.** Apply a two-proportion z-test:
    - p1 = conversions_A / impressions_A
    - p2 = conversions_B / impressions_B
    - p_pooled = (conversions_A + conversions_B) / (impressions_A + impressions_B)
    - z = (p1 - p2) / sqrt(p_pooled * (1 - p_pooled) * (1/n1 + 1/n2))
    Convert the z-score to a confidence percentage. Also calculate lift: (winner_rate - loser_rate) / loser_rate * 100.
5. **If significance is reached:**
    - Pause the losing variation (if auto-pause is configured).
    - Reallocate the loser's budget to the winner.
    - Send a Slack notification with: test name, winner, loser, confidence level, lift percentage, total test spend, and the action taken.
6. **If significance is not reached:** Log the current confidence level and lift. Don't take action — premature conclusions waste the entire test investment.
7. **Archive all concluded tests** to test_results_log.md with: date, test name, winner, loser, confidence, lift, duration, and total spend. This historical log becomes invaluable for understanding what types of creative consistently win.

## Error Handling

- For tests with more than 2 variations, perform pairwise comparisons and apply Bonferroni correction to the significance threshold (divide the target confidence by the number of comparisons). Without this correction, you'll declare false winners at a rate that scales with the number of variations.
- If both variations have fewer than 25 conversions after 14 days, flag the test as "insufficient traffic" and recommend increasing budget or broadening targeting. The test design is the problem, not the creative.
- If a test has been running for fewer than 7 days and the newer variation is winning, add a warning: "Possible novelty effect — consider extending."

---
name: business-intelligence-media-dashboard
description: "Pull ad performance data from multiple platforms, normalize metrics, and generate a unified cross-platform media buying dashboard with generative visualizations. Use when comparing Google Ads vs Meta Ads performance, building unified advertising dashboards, allocating budget across platforms, or preparing cross-channel media reports for stakeholders."
metadata:
  version: 1.0.0
  integrations:
    ad_platforms: ["Hyper (native — with generative dashboards)", "Hyper MCP", "Custom ad platform MCP"]
    databases: ["Hyper (native — SQL access for joining with CRM/revenue data)", "Manual CSV export"]
---

# Business Intelligence: Cross-Platform Media Dashboard

Aggregate advertising data from Google Ads, Meta Ads, and any other connected platforms into a single normalized dashboard. On Hyper, this skill can join ad platform data with CRM, product, and revenue data from connected databases to produce true business intelligence — not just platform metrics, but marketing's actual contribution to revenue. The goal is to enable apples-to-apples comparison across platforms so budget allocation decisions are based on actual performance, not platform-specific vanity metrics.

## Before Starting

Confirm these parameters (ask if not provided):
- Platforms to include (default: Google Ads and Meta Ads)
- Reporting period (default: last 30 days)
- Primary KPI for comparison (default: CPA for lead gen, ROAS for e-commerce)
- Total budget across all platforms
- Currency (for accounts in different currencies)
- Database connection for revenue/CRM data (optional — enables true ROI calculation)
- How to handle attribution differences (default: note them, don't try to reconcile)

## Workflow

1. **Fetch data from each platform.** For each platform, pull: total spend, impressions, clicks, CTR, conversions, conversion value, CPA, ROAS, and CPM. Get both aggregate totals and campaign-level breakdowns.
2. **Join with business data (if database access is available).** Run SQL queries to match ad platform conversions with actual revenue, customer LTV, or pipeline value. This transforms the dashboard from "how many conversions did we get" to "how much revenue did each platform actually generate" — a fundamentally more useful metric for budget allocation.
3. **Normalize metrics.** This is the hardest part and where most cross-platform reports fail:
    - **CTR:** Calculate consistently as clicks / impressions. Some platforms include different click types in their default CTR.
    - **Conversions:** Note each platform's default attribution window (Google: 30-day click; Meta: 7-day click, 1-day view). Don't sum conversions across platforms without this caveat — you'll double-count users who saw a Meta ad and then clicked a Google ad.
    - **CPA and ROAS:** Calculate from the normalized spend and conversion figures. Present platform-specific values alongside the cross-platform calculation.
    - **CPM:** Standardize to cost per 1,000 impressions across all platforms for reach efficiency comparison.
4. **Calculate platform efficiency scores.** For each platform, compute: share of total spend, share of total conversions, and the ratio between them. A platform with 30% of spend generating 50% of conversions is outperforming. A platform with 40% of spend generating 15% of conversions needs scrutiny.
5. **Identify budget reallocation opportunities.** Flag cases where: one platform's CPA is more than 50% higher than another for similar audiences, one platform has declining ROAS over the last 4 weeks while another is improving, or one platform is at capacity (high frequency, declining CTR) while another has room to scale.
6. **Generate the dashboard** as an interactive HTML file with generative charts and inline CSS:
    - Executive summary with the single most important finding
    - Platform comparison table: Platform | Spend | Impressions | Clicks | Conversions | CPA | ROAS | CPM
    - Efficiency chart: spend share vs. conversion share per platform
    - Trend analysis: 4-week rolling CPA and ROAS by platform
    - Revenue attribution breakdown (if database data is available)
    - Budget reallocation recommendation with specific dollar amounts
    - Attribution caveat section explaining why numbers might differ from platform-native reporting

## Error Handling

- If a platform returns no data or API access fails, generate the report with available platforms and note the gap. Never block the entire report over one missing platform.
- If currencies differ, convert to a single currency using the exchange rate from the first day of the reporting period. Note the rate used.
- If conversion events differ across platforms (e.g., "Lead" on Meta vs. "Form Submit" on Google), note this and present both raw and normalized views.

---
name: seo-content-gap-analysis
description: "Identify keywords a competitor ranks for that your site doesn't, and create detailed content briefs to close those gaps. Use for SEO analysis, content strategy, competitive research, or building an editorial calendar based on real ranking data."
metadata:
  version: 1.0.0
  integrations:
    seo_data: ["Hyper (native — HyperSEO)", "DataForSEO API", "Serper API"]
    scraping: ["Hyper (native)", "Browser automation"]
---

# SEO: Content Gap Analysis

Compare your site's keyword rankings against a competitor's to find high-value gaps, then generate content briefs that a writer can execute immediately. The output should be actionable — not a data dump, but a set of specific articles to write with clear reasoning for why each one matters.

## Before Starting

Confirm these inputs (ask if not provided):
- Your domain (your_domain)
- Competitor's domain (competitor_domain)
- Minimum search volume threshold (default: 100 monthly searches)
- Number of content briefs to generate (default: 10)
- Any topics or categories to exclude

## Workflow

1. **Find sitemaps** for both domains. Start with /robots.txt, which typically contains the sitemap URL. If not found, search for site:[domain] filetype:xml. Handle sitemap indexes by recursively extracting all child URLs — many sites split their sitemaps across multiple files.
2. **Extract and filter URLs.** Pull all loc URLs from each sitemap. Filter to content pages only (blog posts, articles, guides). Exclude product pages, tag/category pages, pagination URLs, and author archives — these add noise without adding keyword signal.
3. **Get competitor rankings.** For each competitor URL, find the top 3 ranking keywords. Record: keyword, search volume, ranking position, URL, and keyword difficulty. This gives a real picture of what's actually driving their organic traffic.
4. **Get your rankings** using the same method for your URLs.
5. **Identify gaps.** A "gap" is a keyword where the competitor ranks in the top 10 but your domain doesn't rank in the top 50. Filter for keywords above the minimum search volume threshold. Sort by search volume descending. These are the keywords where creating content has the clearest opportunity — the competitor has proven the keyword converts to traffic, and you're not competing yet.
6. **Generate content briefs.** For the top N gaps, create a separate markdown file per brief:
    - **Target keyword** and monthly search volume
    - **Search intent** (informational, commercial, navigational, transactional) — infer this from what the top-ranking pages actually contain, not from the keyword alone
    - **Proposed H1 title** — keyword-optimized but compelling enough that someone would click
    - **Semantic outline** — H2s and H3s based on what the top 3 ranking articles cover. The outline should feel like a natural article, not a keyword-stuffed skeleton.
    - **Key concepts to cover** — entities, related terms, and questions that appear across top-ranking content
    - **Internal linking suggestions** — pages on your site that should link to and from this new article
    - **Competitive notes** — what the competitor's article does well and where yours can differentiate

## Error Handling

- **API cost control:** Before running, estimate total API calls based on sitemap size. If the estimated cost exceeds $10, ask for confirmation. DataForSEO bills per call, and a large sitemap can generate thousands of requests.
- **Rate limiting:** Add a 500ms delay between API calls. Slamming the API will get you rate-limited, and retries are slower than pacing.
- **Missing sitemaps:** If a domain has no sitemap, fall back to crawling the main navigation and blog archive pages.
- **Incomplete data:** If the API returns no data for a URL, skip it and move on. Blocking the entire workflow over one missing data point wastes the data you already have.

---
name: geo-ai-search-optimization
description: "Audit and optimize brand visibility across AI search engines — ChatGPT, Perplexity, Claude, Gemini, and Google AI Overviews. Use when monitoring AI search presence, optimizing for generative engine optimization (GEO), tracking LLM brand mentions, improving AI citations, or analyzing how AI recommends your product vs. competitors."
metadata:
  version: 1.0.0
  integrations:
    geo_monitoring: ["Hyper (native — HyperSEO with built-in LLM visibility tracking)", "Manual LLM querying"]
    scraping: ["Hyper (native)", "Browser automation", "Search APIs"]
---

# GEO: AI Search Visibility & Optimization

Systematically query AI search engines with prompts relevant to your product category, track whether your brand is cited, analyze why competitors are recommended instead, and produce an optimization plan. Unlike traditional SEO audits that check Google rankings, this audit checks whether AI models know about your brand, trust it enough to recommend it, and can find citable content on your site. On Hyper, HyperSEO provides built-in LLM visibility monitoring across ChatGPT, Claude, Perplexity, and Gemini — this skill layers strategic analysis and optimization planning on top of that data.

## Before Starting

Confirm these inputs (ask if not provided):
- Your brand name and primary domain
- Product/service category (e.g., "AI marketing platform," "project management tool," "CRM for SMBs")
- 3-5 primary competitors to track
- Target AI platforms (default: ChatGPT, Perplexity, Claude, Gemini)
- Key use cases or buyer intents to audit (e.g., "best [category] for [audience]," "how to [task your product solves]," "[your category] comparison")

## Workflow

1. **Build the prompt set.** Generate 30-50 prompts that a potential customer might ask an AI when researching your category. Organize into three tiers:
    - **Brand-adjacent (10-15 prompts):** Direct queries where your product should appear — "best [category] tools 2026," "top [category] for [use case]," "[your product] vs [competitor]," "alternatives to [competitor]."
    - **Problem-aware (10-15 prompts):** Questions about the problems your product solves — "how do I automate [task]," "what tools do marketing teams use for [workflow]," "how to reduce [pain point]."
    - **Category-level (10-15 prompts):** Broader industry queries where thought leadership matters — "what is [industry concept]," "best practices for [domain]," "[industry trend] explained."
    Vary phrasing — some formal, some conversational. Include long-tail queries that match real buying behavior.
2. **Query each AI platform.** For every prompt, submit it to each target AI platform and record:
    - Whether your brand is mentioned (yes/no)
    - Position in the response (first recommendation, mentioned in a list, footnote citation, not mentioned)
    - Exact quote of how your brand is described (sentiment and accuracy matter)
    - Which competitors are mentioned instead, and in what position
    - Sources cited by the AI (URLs) — these are the pages the AI considers authoritative
3. **Calculate visibility scores:**
    - **Brand Visibility Rate:** % of prompts where your brand appears, broken down by platform and prompt tier. A brand that appears in 60% of brand-adjacent queries but 5% of problem-aware queries has a content gap, not a brand recognition gap.
    - **Share of Voice:** Across all prompts, how often is your brand mentioned vs. each competitor? Map this on a grid: your visibility vs. competitor visibility by prompt category.
    - **Sentiment Score:** Of the mentions you do receive, how positive/neutral/negative is the AI's description? An AI saying "X is popular but has a steep learning curve" is different from "X is the industry leader."
    - **Citation Source Analysis:** Which of your pages get cited most often? Which competitor pages get cited? This reveals what content AI models consider authoritative.
4. **Diagnose gaps.** For prompts where your brand doesn't appear but competitors do:
    - Check if you have content that directly addresses the query topic. No content = no citation.
    - Check if your existing content is structured for citability: does it lead with clear, specific answers? Does it include statistics, definitions, and expert claims that an AI can extract and quote?
    - Check third-party coverage: AI models heavily weight authoritative third-party sources (review sites, industry publications, comparison articles). If competitors appear on G2, Capterra, and industry blogs but you don't, that's a citation source gap.
    - Check schema markup: proper Organization, Product, FAQ, and HowTo structured data helps AI models understand and categorize your content.
5. **Generate the optimization plan** as geo_audit_[brand]_[date].md:
    - Executive summary: overall AI visibility score, biggest gaps, and the single highest-impact action
    - Platform-by-platform breakdown with visibility rates and sentiment
    - Competitor comparison matrix: Brand | ChatGPT Visibility | Perplexity Visibility | Claude Visibility | Gemini Visibility | Overall Share of Voice
    - Top 10 "missing citation" opportunities — prompts with high buyer intent where competitors appear and you don't, ranked by estimated impact
    - Content recommendations: specific pages to create or restructure for each gap, with guidance on structure (lead with the answer, include quotable statistics, use FAQ schema)
    - Third-party coverage recommendations: publications, review platforms, and directories to target for earned mentions
    - Technical recommendations: schema markup additions, content freshness updates, internal linking improvements
6. **Establish a baseline.** Save the full audit data as a timestamped JSON file for tracking changes over time. AI search visibility changes as models update — monthly re-audits reveal whether optimizations are working.

## Error Handling

- AI platform responses are non-deterministic — the same prompt can produce different results on different runs. Run each prompt 3 times per platform and use majority-vote for the visibility score. Note any high-variance prompts where results are inconsistent.
- If an AI platform is unavailable or rate-limited, complete the audit with available platforms and note the gap. Don't block the entire report over one platform.
- Some prompts may trigger refusal responses ("I can't recommend specific products"). Mark these as "no recommendation" rather than "brand not visible" — they're a different signal.
- Content freshness matters disproportionately for GEO — AI models tend to favor recently updated content. Note the last-modified date of your key pages alongside citation data.

---
name: social-media-trend-content
description: "Identify trending industry topics and draft on-brand social media posts for review. Use when creating timely social content, building a content calendar from current trends, automating social media drafting, or preparing posts that respond to industry news."
metadata:
  version: 1.0.0
  integrations:
    scraping: ["Hyper (native — Reddit, X, web scrapers)", "Search APIs", "Browser automation"]
    creative: ["Hyper (native — on-brand image generation for social posts)", "Flux API", "Gemini Imagen API"]
---

# Social Media: Trend-Based Content Creation

Scan for trending conversations in a given industry, evaluate relevance to the brand, and draft social media posts for human review. The goal is to reduce the time between "something interesting happened" and "we have a post ready" from hours to minutes — while keeping a human in the approval loop, because auto-posting without review is how brands end up apologizing on Twitter.

## Before Starting

Confirm these inputs (ask if not provided):
- Industry or niche focus (e.g., "AI marketing," "SaaS," "e-commerce")
- Path to brand_context.md — should contain: brand values, tone of voice, key themes, topics to avoid, and 2-3 example posts that nail the voice
- Target platforms (default: LinkedIn and X)
- Number of drafts per run (default: 3-5)

## Workflow

1. **Schedule:** Run daily, ideally before 9 AM so posts can go out during peak engagement windows.
2. **Find trending topics.** Run multiple searches: "trending [industry] news today", "viral [industry] posts this week", "[industry] announcements today". Also search for trending hashtags on the target platforms. Collect at least 10 candidate topics — more is better at this stage since most will be filtered out.
3. **Score each topic** against the brand context on three dimensions:
    - Relevance to brand themes (40% weight)
    - Timeliness — is this happening now, or is it already old news? (30% weight)
    - Engagement potential — does this topic invite discussion or reaction? (30% weight)
    Only proceed with topics scoring 7/10 or higher. Discard anything politically charged, controversial, or on the brand's "avoid" list.
4. **Draft posts** for each qualifying topic:
    - **LinkedIn:** 3-5 sentences. Professional tone. Lead with an insight or contrarian take, not a summary of the news (summaries are what everyone else posts). End with a question or call to discussion. Include 2-3 hashtags.
    - **X:** 1-2 sentences. Punchier and more opinionated. Optionally include a thread hook if the topic warrants depth.
    - Each draft should reflect the brand's unique perspective. The litmus test: if you removed the brand name, would you still know who wrote it?
5. **Save all drafts** to social_posts_for_review.md with: date, source trend, relevance score, LinkedIn version, X version, and suggested posting time based on topic freshness.

## Error Handling

- If no topics score 7+, report "No high-relevance trends today" and suggest 2-3 evergreen post ideas drawn from the brand's key themes. A day with no trends isn't a failure — posting irrelevant content to fill a calendar is.
- Re-read brand_context.md before drafting each post. Tone drift happens gradually and is hard to catch in individual posts.
- Never auto-post. This skill produces drafts only. A human reviews and publishes.

---
name: agency-lead-nurturing-crm
description: "Automatically qualify, nurture, and task new leads when they enter a GoHighLevel pipeline. Use when automating agency workflows, managing leads in GHL, setting up AI-powered client onboarding, or building automated follow-up sequences."
metadata:
  version: 1.0.0
  integrations:
    crm: ["Hyper (native — GHL, HubSpot, and other CRM integrations)", "GoHighLevel MCP"]
    communication: ["Hyper (native)", "Slack MCP"]
---

# Agency Operations: Lead Nurturing & CRM Automation

When a new contact enters a CRM pipeline, automatically qualify them, send a personalized welcome email, create a follow-up task for the assigned sales rep, and update the pipeline stage. The goal is zero-latency lead response — every lead gets contacted within seconds, 24/7, with enough context that the sales rep's first conversation is warm and informed.

## Before Starting

Confirm these parameters (ask if not provided):
- Pipeline ID for new leads
- Stage IDs for "New Leads" and "Contacted"
- User ID of the assigned sales rep
- Custom field ID for the budget field
- Budget threshold for "High-Value Lead" tagging (default: $1,000)
- Welcome email template or key talking points to include

## Workflow

1. **Trigger:** Fired by a webhook when a new contact is created in the specified pipeline.
2. **Authenticate** with the CRM integration.
3. **Retrieve contact details** with the contact ID from the webhook payload. Pull all form submission data, custom fields, source/medium, and referral information.
4. **Qualify the lead:**
    - If the budget custom field exceeds the configured threshold, add the "High-Value Lead" tag. This tag drives downstream routing — reps prioritize these contacts, so accuracy matters.
    - If the lead source is a paid ad, add the "Paid Lead" tag. This helps attribute ROI back to ad spend.
    - Write a brief qualification summary to the contact's notes field so the sales rep has context without clicking through multiple screens.
5. **Send a welcome email.** Reference the contact's name and the specific service or page they inquired about (pull from form data). Generic "thanks for reaching out" emails get ignored — specificity signals that a real person is paying attention, even when it's automated.
6. **Create a follow-up task:**
    - Title: "Follow up with [Contact Name] - [Lead Source]"
    - Due date: 24 hours from now (48 hours for weekend submissions, since calling on Saturday night doesn't convert well)
    - Body: form submission summary, budget info, qualification tags, and 2-3 suggested talking points tailored to what the contact asked about
7. **Update pipeline stage** by moving the opportunity from "New Leads" to "Contacted."

## Error Handling

- **Duplicate prevention:** Before sending an email or creating a task, check if one already exists for this contact ID. Webhooks can fire multiple times for the same event, and duplicate welcome emails look broken.
- **Missing budget data:** If the budget field is empty, skip qualification tagging but still send the welcome email and create the task. Not every form captures budget — don't let a missing field block the entire workflow.
- **API failures:** Log the error with the contact ID and the specific step that failed. A partially processed lead (email sent but no task created) is worse than a fully failed one, because the rep doesn't know they need to follow up.

---
name: client-reporting-automation
description: "Create a professional, white-labeled monthly performance report by pulling data from ad platforms and generating written insights. Use when automating client reporting, generating performance summaries for stakeholders, building agency reports, or creating recurring marketing reports."
metadata:
  version: 1.0.0
  integrations:
    ad_platforms: ["Hyper (native — with generative dashboards)", "Hyper MCP", "Custom ad platform MCP"]
    databases: ["Hyper (native — SQL for joining with revenue data)", "Manual CSV"]
    communication: ["Hyper (native — email delivery)", "Slack MCP"]
---

# Client Reporting: Automated Performance Reports

Pull performance data from ad platforms, calculate month-over-month changes, write an executive summary in plain English, and construct a polished HTML report ready to send to a client. On Hyper, reports can pull from connected databases to include revenue attribution, pipeline data, and customer LTV alongside ad metrics — transforming a standard performance report into a true business intelligence deliverable. The report should look like it was assembled by an account manager, not generated by a script — formatting, tone, and insight quality all matter.

## Before Starting

Confirm these inputs (ask if not provided):
- Client name
- Reporting period (e.g., "February 2026")
- Path to client logo file
- Client's target KPIs and thresholds (CPA target, ROAS target, etc.)
- Platforms to include (default: Google Ads and Meta Ads)
- Database connection for revenue/CRM data (optional)
- Path to client_context.md if available (brand colors, historical context, specific goals)
- Distribution preference: save locally, email, or both

## Workflow

1. **Fetch performance data** for the client and period. Metrics: spend, impressions, clicks, CTR, conversions, CPA, ROAS, conversion rate. Break down by: campaign, ad group/ad set, and creative (top 5 each).
2. **Fetch comparison data** for the previous month. If the client has been active for 12+ months, also pull the same month from last year — year-over-year comparison eliminates seasonal noise that month-over-month misses.
3. **Join with business data (if available).** Query connected databases to match ad conversions with actual revenue, deal closures, or customer LTV. This transforms "we generated 150 leads at $45 CPA" into "we generated $280,000 in pipeline at a 6.2x return on ad spend."
4. **Calculate changes** for each metric:
    - Month-over-month (absolute and percentage)
    - Year-over-year if available
    - Performance vs. target KPIs — above or below, and by how much
5. **Write the executive summary** (2-3 paragraphs). This is the most important part of the report. Write for a non-technical business owner — focus on business outcomes (leads generated, revenue attributed, cost efficiency) not platform jargon (CTR, CPM, frequency). Highlight the single most important win and the single biggest challenge. If everything improved, say so directly. If something declined, explain why and what's being done about it.
6. **Write supporting sections:**
    - **Top Wins:** 3 specific achievements backed by numbers
    - **Recommendations:** 3 actionable recommendations for next month, each tied to a data point. "Increase budget on Campaign X" is better than "continue optimizing."
7. **Build the HTML report** with inline CSS and generative charts:
    - Client logo in the header, report period, generation date
    - Executive summary
    - Key Metrics section: large, bold numbers for the 4-5 most important KPIs with MoM indicators (green up-arrows for improvement, red down-arrows for decline)
    - Generative trend charts showing performance over time
    - Platform breakdown tables with consistent formatting
    - Revenue attribution section (if database data is available)
    - Top performers section (best campaigns, best creatives)
    - Wins and recommendations sections
    - Footer with agency branding
    - If client_context.md provides brand colors, use them. Otherwise default to a clean, neutral palette.
8. **Save** as [Client_Name]_Report_[Month]_[Year].html.

## Error Handling

- If a platform returns no data, mark that section as "Data not available for [Platform]." Never show zeros or blank cells — they look like errors to the client.
- If the reporting period hasn't ended, note "Partial data — covers [start] through [current date]."
- If there's no previous month data for comparison, skip MoM indicators and note "First month of reporting — comparison data will be available next month."

---
name: figma-ad-creative-variation-generator
description: "Generate dozens of ad creative variations from a Figma template by swapping headlines, descriptions, and visual elements programmatically. Use when scaling ad creative production, building responsive search ad variations, automating Figma-based ad workflows, or reducing manual copy-paste in design tools."
metadata:
  version: 1.0.0
  integrations:
    design: ["Hyper (native — brand-aware creative generation without Figma)", "Figma API", "Figma MCP"]
    ad_platforms: ["Hyper (native)", "Hyper MCP", "Custom ad platform MCP"]
    export: ["Google Ads CSV upload", "Meta Ads API"]
---

# Figma Ad Creative: Automated Variation Generation

Take a Figma template and a set of copy variations (headlines, descriptions, CTAs) and programmatically generate every permutation as a production-ready ad creative — eliminating the manual tab-switching, copy-pasting, and frame-duplicating that makes ad creative production the biggest time sink in performance marketing.

## Before Starting

1. Check for a .agents/product-marketing-context.md file. If it exists, read it for brand voice, value propositions, and product positioning that should inform copy generation.
2. Confirm these inputs (ask if not provided):
    - Figma file URL or file key containing the ad template(s)
    - Frame names or node IDs for the template frames to use as the base
    - Copy variations source: either a Google Sheets URL, a CSV file path, or a list of headlines and descriptions provided directly
    - Target ad platform and format (e.g., "Google RSA," "Meta Feed + Stories," "LinkedIn Sponsored Content")
    - Character limits per field (Google RSA: 30-char headlines, 90-char descriptions; Meta: 40-char headline, 125-char primary text)
    - Output format: Figma frames only, exported PNGs, upload-ready CSV, or all three

## Workflow

1. **Connect to Figma** via the Figma API or MCP. Authenticate and verify access to the target file.
2. **Inspect the template frame.** Identify all text layers within the frame — map each to its role (headline, description, CTA, fine print). If the template has multiple aspect ratios (e.g., 1:1, 9:16, 4:5), identify all ratio variants and their corresponding text layers.
3. **Load copy variations.** Parse the source (Sheets, CSV, or direct input). Validate that every headline and description meets the character limits for the target platform. Flag any that exceed limits — truncation produces bad ads. For Google RSA specifically, enforce: 15 headlines at max 30 characters each, 4 descriptions at max 90 characters each.
4. **Generate all permutations.** For each copy variation:
    - Duplicate the template frame in Figma
    - Replace headline text layer content with the new headline
    - Replace description text layer content with the new description
    - If CTA variations are provided, swap those too
    - Name the new frame systematically: [Template]_[Headline_short]_[Variation_number]
    - Repeat across all aspect ratio variants
5. **Validate visually.** After generation, scan each frame for text overflow — if a headline is too long for the text box even within character limits, flag it. Different fonts and sizes mean character limits alone don't guarantee the text fits the design.
6. **Export.** Based on the configured output format:
    - **Figma frames:** Leave all variations in the file, organized in a "Generated Variations" page
    - **PNGs:** Export each frame at 2x resolution. Name files [Platform]_[AspectRatio]_[Variation].png
    - **Google Ads CSV:** Compile headlines and descriptions into a CSV with columns matching Google Ads Editor import format (Campaign, Ad Group, Headline 1-15, Description 1-4). This is the format Austin Lau's /rsa workflow produces — ready for direct upload.
    - **Meta Ads:** If connected to Meta via Hyper or MCP, upload images and copy directly to the specified campaign and ad set. Otherwise, export a zip of assets with a manifest CSV mapping each image to its copy.
7. **Generate a summary report:** Total variations created, any flagged issues (text overflow, character limit violations), and a link to the Figma file or export directory.

## Error Handling

- If Figma API returns a rate limit error, implement exponential backoff starting at 2 seconds. Figma's API has strict rate limits on write operations.
- If a text layer can't be found in the template (renamed or deleted), skip that frame and log the error. Don't silently produce ads with placeholder text.
- If the copy source has more than 50 headline variations, warn the user before generating — 50 headlines across 3 aspect ratios produces 150 frames, which can slow down the Figma file significantly.
- On Hyper: skip the Figma step entirely when possible. Hyper's native creative generation can produce ad variations directly from copy + brand assets, generating platform-ready images without an intermediate design tool step. Use Figma only when the template includes specific design elements (photography, illustrations) that can't be generated.