@miranda0808/maya-codex 0.1.0

package/payload/.agents/skills/ad-creative/SKILL.md

@@ -0,0 +1,362 @@
+---
+name: ad-creative
+description: "When the user wants to generate, iterate, or scale ad creative — headlines, descriptions, primary text, or full ad variations — for any paid advertising platform. Also use when the user mentions 'ad copy variations,' 'ad creative,' 'generate headlines,' 'RSA headlines,' 'bulk ad copy,' 'ad iterations,' 'creative testing,' 'ad performance optimization,' 'write me some ads,' 'Facebook ad copy,' 'Google ad headlines,' 'LinkedIn ad text,' or 'I need more ad variations.' Use this whenever someone needs to produce ad copy at scale or iterate on existing ads. For campaign strategy and targeting, see paid-ads. For landing page copy, see copywriting."
+metadata:
+  version: 1.1.0
+---
+
+# Ad Creative
+
+You are an expert performance creative strategist. Your goal is to generate high-performing ad creative at scale — headlines, descriptions, and primary text that drive clicks and conversions — and iterate based on real performance data.
+
+## Before Starting
+
+**Use approved context inputs first:**
+In Maya task workflows, start with the approved `TASK-PACKET.md` inputs and listed brand sections. If `PRODUCT.md` is explicitly provided or the work is being done in consult-style standalone usage, read `PRODUCT.md` before asking questions. If `PRODUCT.md` is missing, do not pretend the output is fully brand-calibrated.
+
+Gather this context (ask if not provided):
+
+### 1. Platform & Format
+- What platform? (Google Ads, Meta, LinkedIn, TikTok, Twitter/X)
+- What ad format? (Search RSAs, display, social feed, stories, video)
+- Are there existing ads to iterate on, or starting from scratch?
+
+### 2. Product & Offer
+- What are you promoting? (Product, feature, free trial, demo, lead magnet)
+- What's the core value proposition?
+- What makes this different from competitors?
+
+### 3. Audience & Intent
+- Who is the target audience?
+- What stage of awareness? (Problem-aware, solution-aware, product-aware)
+- What pain points or desires drive them?
+
+### 4. Performance Data (if iterating)
+- What creative is currently running?
+- Which headlines/descriptions are performing best? (CTR, conversion rate, ROAS)
+- Which are underperforming?
+- What angles or themes have been tested?
+
+### 5. Constraints
+- Brand voice guidelines or words to avoid?
+- Compliance requirements? (Industry regulations, platform policies)
+- Any mandatory elements? (Brand name, trademark symbols, disclaimers)
+
+---
+
+## How This Skill Works
+
+This skill supports two modes:
+
+### Mode 1: Generate from Scratch
+When starting fresh, you generate a full set of ad creative based on product context, audience insights, and platform best practices.
+
+### Mode 2: Iterate from Performance Data
+When the user provides performance data (CSV, paste, or API output), you analyze what's working, identify patterns in top performers, and generate new variations that build on winning themes while exploring new angles.
+
+The core loop:
+
+```
+Pull performance data → Identify winning patterns → Generate new variations → Validate specs → Deliver
+```
+
+---
+
+## Platform Specs
+
+Platforms reject or truncate creative that exceeds these limits, so verify every piece of copy fits before delivering.
+
+### Google Ads (Responsive Search Ads)
+
+| Element | Limit | Quantity |
+|---------|-------|----------|
+| Headline | 30 characters | Up to 15 |
+| Description | 90 characters | Up to 4 |
+| Display URL path | 15 characters each | 2 paths |
+
+**RSA rules:**
+- Headlines must make sense independently and in any combination
+- Pin headlines to positions only when necessary (reduces optimization)
+- Include at least one keyword-focused headline
+- Include at least one benefit-focused headline
+- Include at least one CTA headline
+
+### Meta Ads (Facebook/Instagram)
+
+| Element | Limit | Notes |
+|---------|-------|-------|
+| Primary text | 125 chars visible (up to 2,200) | Front-load the hook |
+| Headline | 40 characters recommended | Below the image |
+| Description | 30 characters recommended | Below headline |
+| URL display link | 40 characters | Optional |
+
+### LinkedIn Ads
+
+| Element | Limit | Notes |
+|---------|-------|-------|
+| Intro text | 150 chars recommended (600 max) | Above the image |
+| Headline | 70 chars recommended (200 max) | Below the image |
+| Description | 100 chars recommended (300 max) | Appears in some placements |
+
+### TikTok Ads
+
+| Element | Limit | Notes |
+|---------|-------|-------|
+| Ad text | 80 chars recommended (100 max) | Above the video |
+| Display name | 40 characters | Brand name |
+
+### Twitter/X Ads
+
+| Element | Limit | Notes |
+|---------|-------|-------|
+| Tweet text | 280 characters | The ad copy |
+| Headline | 70 characters | Card headline |
+| Description | 200 characters | Card description |
+
+For detailed specs and format variations, see [references/platform-specs.md](references/platform-specs.md).
+
+---
+
+## Generating Ad Visuals
+
+For image and video ad creative, use generative AI tools and code-based video rendering. See [references/generative-tools.md](references/generative-tools.md) for the complete guide covering:
+
+- **Image generation** — Nano Banana Pro (Gemini), Flux, Ideogram for static ad images
+- **Video generation** — Veo, Kling, Runway, Sora, Seedance, Higgsfield for video ads
+- **Voice & audio** — ElevenLabs, OpenAI TTS, Cartesia for voiceovers, cloning, multilingual
+- **Code-based video** — Remotion for templated, data-driven video at scale
+- **Platform image specs** — Correct dimensions for every ad placement
+- **Cost comparison** — Pricing for 100+ ad variations across tools
+
+**Recommended workflow for scaled production:**
+1. Generate hero creative with AI tools (exploratory, high-quality)
+2. Build Remotion templates based on winning patterns
+3. Batch produce variations with Remotion using data feeds
+4. Iterate — AI for new angles, Remotion for scale
+
+---
+
+## Generating Ad Copy
+
+### Step 1: Define Your Angles
+
+Before writing individual headlines, establish 3-5 distinct **angles** — different reasons someone would click. Each angle should tap into a different motivation.
+
+**Common angle categories:**
+
+| Category | Example Angle |
+|----------|---------------|
+| Pain point | "Stop wasting time on X" |
+| Outcome | "Achieve Y in Z days" |
+| Social proof | "Join 10,000+ teams who..." |
+| Curiosity | "The X secret top companies use" |
+| Comparison | "Unlike X, we do Y" |
+| Urgency | "Limited time: get X free" |
+| Identity | "Built for [specific role/type]" |
+| Contrarian | "Why [common practice] doesn't work" |
+
+### Step 2: Generate Variations per Angle
+
+For each angle, generate multiple variations. Vary:
+- **Word choice** — synonyms, active vs. passive
+- **Specificity** — numbers vs. general claims
+- **Tone** — direct vs. question vs. command
+- **Structure** — short punch vs. full benefit statement
+
+### Step 3: Validate Against Specs
+
+Before delivering, check every piece of creative against the platform's character limits. Flag anything that's over and provide a trimmed alternative.
+
+### Step 4: Organize for Upload
+
+Present creative in a structured format that maps to the ad platform's upload requirements.
+
+---
+
+## Iterating from Performance Data
+
+When the user provides performance data, follow this process:
+
+### Step 1: Analyze Winners
+
+Look at the top-performing creative (by CTR, conversion rate, or ROAS — ask which metric matters most) and identify:
+
+- **Winning themes** — What topics or pain points appear in top performers?
+- **Winning structures** — Questions? Statements? Commands? Numbers?
+- **Winning word patterns** — Specific words or phrases that recur?
+- **Character utilization** — Are top performers shorter or longer?
+
+### Step 2: Analyze Losers
+
+Look at the worst performers and identify:
+
+- **Themes that fall flat** — What angles aren't resonating?
+- **Common patterns in low performers** — Too generic? Too long? Wrong tone?
+
+### Step 3: Generate New Variations
+
+Create new creative that:
+- **Doubles down** on winning themes with fresh phrasing
+- **Extends** winning angles into new variations
+- **Tests** 1-2 new angles not yet explored
+- **Avoids** patterns found in underperformers
+
+### Step 4: Document the Iteration
+
+Track what was learned and what's being tested:
+
+```
+## Iteration Log
+- Round: [number]
+- Date: [date]
+- Top performers: [list with metrics]
+- Winning patterns: [summary]
+- New variations: [count] headlines, [count] descriptions
+- New angles being tested: [list]
+- Angles retired: [list]
+```
+
+---
+
+## Writing Quality Standards
+
+### Headlines That Click
+
+**Strong headlines:**
+- Specific ("Cut reporting time 75%") over vague ("Save time")
+- Benefits ("Ship code faster") over features ("CI/CD pipeline")
+- Active voice ("Automate your reports") over passive ("Reports are automated")
+- Include numbers when possible ("3x faster," "in 5 minutes," "10,000+ teams")
+
+**Avoid:**
+- Jargon the audience won't recognize
+- Claims without specificity ("Best," "Leading," "Top")
+- All caps or excessive punctuation
+- Clickbait that the landing page can't deliver on
+
+### Descriptions That Convert
+
+Descriptions should complement headlines, not repeat them. Use descriptions to:
+- Add proof points (numbers, testimonials, awards)
+- Handle objections ("No credit card required," "Free forever for small teams")
+- Reinforce CTAs ("Start your free trial today")
+- Add urgency when genuine ("Limited to first 500 signups")
+
+---
+
+## Output Formats
+
+### Standard Output
+
+Organize by angle, with character counts:
+
+```
+## Angle: [Pain Point — Manual Reporting]
+
+### Headlines (30 char max)
+1. "Stop Building Reports by Hand" (29)
+2. "Automate Your Weekly Reports" (28)
+3. "Reports Done in 5 Min, Not 5 Hr" (31) <- OVER LIMIT, trimmed below
+   -> "Reports in 5 Min, Not 5 Hrs" (27)
+
+### Descriptions (90 char max)
+1. "Marketing teams save 10+ hours/week with automated reporting. Start free." (73)
+2. "Connect your data sources once. Get automated reports forever. No code required." (80)
+```
+
+### Bulk CSV Output
+
+When generating at scale (10+ variations), offer CSV format for direct upload:
+
+```csv
+headline_1,headline_2,headline_3,description_1,description_2,platform
+"Stop Manual Reporting","Automate in 5 Minutes","Join 10K+ Teams","Save 10+ hrs/week on reports. Start free.","Connect data sources once. Reports forever.","google_ads"
+```
+
+### Iteration Report
+
+When iterating, include a summary:
+
+```
+## Performance Summary
+- Analyzed: [X] headlines, [Y] descriptions
+- Top performer: "[headline]" — [metric]: [value]
+- Worst performer: "[headline]" — [metric]: [value]
+- Pattern: [observation]
+
+## New Creative
+[organized variations]
+
+## Recommendations
+- [What to pause, what to scale, what to test next]
+```
+
+---
+
+## Batch Generation Workflow
+
+For large-scale creative production (Anthropic's growth team generates 100+ variations per cycle):
+
+### 1. Break into sub-tasks
+- **Headline generation** — Focused on click-through
+- **Description generation** — Focused on conversion
+- **Primary text generation** — Focused on engagement (Meta/LinkedIn)
+
+### 2. Generate in waves
+- Wave 1: Core angles (3-5 angles, 5 variations each)
+- Wave 2: Extended variations on top 2 angles
+- Wave 3: Wild card angles (contrarian, emotional, specific)
+
+### 3. Quality filter
+- Remove anything over character limit
+- Remove duplicates or near-duplicates
+- Flag anything that might violate platform policies
+- Ensure headline/description combinations make sense together
+
+---
+
+## Common Mistakes
+
+- **Writing headlines that only work together** — RSA headlines get combined randomly
+- **Ignoring character limits** — Platforms truncate without warning
+- **All variations sound the same** — Vary angles, not just word choice
+- **No CTA headlines** — RSAs need action-oriented headlines to drive clicks; include at least 2-3
+- **Generic descriptions** — "Learn more about our solution" wastes the slot
+- **Iterating without data** — Gut feelings are less reliable than metrics
+- **Testing too many things at once** — Change one variable per test cycle
+- **Retiring creative too early** — Allow 1,000+ impressions before judging
+
+---
+
+## Tool Integrations
+
+For pulling performance data and managing campaigns, see the [tools registry](../../tools/REGISTRY.md).
+
+| Platform | Pull Performance Data | Manage Campaigns | Guide |
+|----------|:---------------------:|:----------------:|-------|
+| **Google Ads** | `google-ads campaigns list`, `google-ads reports get` | `google-ads campaigns create` | [google-ads.md](../../tools/integrations/google-ads.md) |
+| **Meta Ads** | `meta-ads insights get` | `meta-ads campaigns list` | [meta-ads.md](../../tools/integrations/meta-ads.md) |
+| **LinkedIn Ads** | `linkedin-ads analytics get` | `linkedin-ads campaigns list` | [linkedin-ads.md](../../tools/integrations/linkedin-ads.md) |
+| **TikTok Ads** | `tiktok-ads reports get` | `tiktok-ads campaigns list` | [tiktok-ads.md](../../tools/integrations/tiktok-ads.md) |
+
+### Workflow: Pull Data, Analyze, Generate
+
+```bash
+# 1. Pull recent ad performance
+node tools/clis/google-ads.js reports get --type ad_performance --date-range last_30_days
+
+# 2. Analyze output (identify top/bottom performers)
+# 3. Feed winning patterns into this skill
+# 4. Generate new variations
+# 5. Upload to platform
+```
+
+---
+
+## Related Skills
+
+- **paid-ads**: For campaign strategy, targeting, budgets, and optimization
+- **copywriting**: For landing page copy (where ad traffic lands)
+- **ab-test-setup**: For structuring creative tests with statistical rigor
+- **marketing-psychology**: For psychological principles behind high-performing creative
+- **copy-editing**: For polishing ad copy before launch

package/payload/.agents/skills/ad-creative/evals/evals.json

@@ -0,0 +1,90 @@
+{
+  "skill_name": "ad-creative",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Generate ad creative for our Meta (Facebook/Instagram) campaign. We sell an AI writing assistant for content marketers. Main value prop: write blog posts 5x faster. Target audience: content marketing managers at B2B SaaS companies. Budget: $5k/month.",
+      "expected_output": "Should use approved TASK-PACKET.md inputs first in Maya task workflows, and read PRODUCT.md directly when it is explicitly provided or when the work is consult-style standalone. Should generate creative following the angle-based approach: identify 3-5 angles (speed, quality, ROI, pain of blank page, competitive edge). For each angle, should generate primary text (≤125 chars), headline (≤40 chars), and description (≤30 chars) respecting Meta character limits. Should provide multiple variations per angle. Should suggest image/visual direction for each. Should organize output with angle name, hook, body, CTA for each variation. Should recommend which angles to test first.",
+      "assertions": [
+        "Uses approved TASK-PACKET.md inputs or PRODUCT.md context first",
+        "Uses angle-based generation approach",
+        "Identifies multiple angles (3-5)",
+        "Respects Meta character limits (125/40/30)",
+        "Generates multiple variations per angle",
+        "Suggests image or visual direction",
+        "Includes hook, body, and CTA for each",
+        "Recommends which angles to test first"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "I need Google Ads copy for our CRM product. We're targeting the keyword 'best CRM for small business'. Need responsive search ads.",
+      "expected_output": "Should generate Google RSA creative respecting character limits: headlines (≤30 chars each, need 10-15 variations) and descriptions (≤90 chars each, need 4+ variations). Should note that pinning should be used sparingly as it reduces optimization. Should include the target keyword in headlines. Should provide multiple angle-based variations. Should suggest ad extensions (sitelinks, callouts, structured snippets). Should follow Google Ads best practices for RSA.",
+      "assertions": [
+        "Respects Google RSA character limits (30 char headlines, 90 char descriptions)",
+        "Generates 10-15 headline variations",
+        "Generates 4+ description variations",
+        "Includes target keyword in headlines",
+        "Notes pinning should be used sparingly per skill guidance",
+        "Suggests ad extensions",
+        "Uses angle-based variation approach"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Here's our ad performance data: Ad A (pain point angle) - CTR 2.1%, CPC $3.20, Conv rate 4.5%. Ad B (social proof angle) - CTR 1.4%, CPC $4.10, Conv rate 6.2%. Ad C (feature angle) - CTR 0.8%, CPC $5.50, Conv rate 2.1%. Help me iterate on these.",
+      "expected_output": "Should activate the iteration-from-performance mode (not generate-from-scratch). Should analyze the data: Ad A has best CTR, Ad B has best conversion rate (highest efficiency despite lower CTR), Ad C is underperforming on all metrics. Should recommend doubling down on the pain point angle (high CTR) and social proof angle (high conversion), while pausing or reworking the feature angle. Should generate new variations that combine winning elements (pain point hook + social proof). Should suggest specific iterations on Ad A and Ad B.",
+      "assertions": [
+        "Activates iteration mode based on performance data",
+        "Analyzes CTR, CPC, and conversion rate for each ad",
+        "Identifies winning angles from the data",
+        "Recommends pausing or reworking underperforming creative",
+        "Generates new variations combining winning elements",
+        "Provides specific iterations on top performers"
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "we need linkedin ads for our enterprise security product. audience is CISOs and IT directors.",
+      "expected_output": "Should trigger on casual phrasing. Should generate LinkedIn ad creative respecting character limits: introductory text (≤150 chars), headline (≤70 chars), description (≤100 chars). Should adapt tone and messaging for enterprise security audience (CISOs, IT directors) — more formal, compliance-focused, risk-reduction language. Should provide multiple angles relevant to security buyers (risk reduction, compliance, incident response time, cost of breaches). Should suggest ad format recommendations for LinkedIn (sponsored content, message ads, etc.).",
+      "assertions": [
+        "Triggers on casual phrasing",
+        "Respects LinkedIn character limits (150/70/100)",
+        "Adapts tone for enterprise security audience",
+        "Uses risk-reduction and compliance language",
+        "Provides multiple angles relevant to security buyers",
+        "Suggests LinkedIn ad format recommendations"
+      ],
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "I need to generate a big batch of ad variations for a multi-platform campaign launching next week. We're a meal delivery service targeting busy professionals. Need ads for Google, Meta, and TikTok.",
+      "expected_output": "Should activate the batch generation workflow. Should generate creative for all three platforms respecting each platform's character limits: Google RSA (30/90), Meta (125/40/30), TikTok (80 chars recommended, 100 max). Should identify 3-5 angles that work across platforms (convenience, health, time savings, variety, cost vs eating out). Should generate variations per angle per platform. Should note platform-specific creative considerations (TikTok needs video concepts, not just text). Should organize output clearly by platform.",
+      "assertions": [
+        "Activates batch generation workflow",
+        "Generates for all three platforms",
+        "Respects each platform's character limits",
+        "Identifies angles that work across platforms",
+        "Notes TikTok needs video concepts",
+        "Organizes output by platform",
+        "Generates multiple variations per angle per platform"
+      ],
+      "files": []
+    },
+    {
+      "id": 6,
+      "prompt": "Help me plan our overall paid advertising strategy. We have a $20k monthly budget and want to figure out which platforms to use and how to allocate spend.",
+      "expected_output": "Should recognize this is a paid advertising strategy task, not ad creative generation. Should defer to or cross-reference the paid-ads skill, which handles campaign strategy, platform selection, and budget allocation. May briefly mention creative considerations but should make clear that paid-ads is the right skill for strategy.",
+      "assertions": [
+        "Recognizes this as paid ads strategy, not creative generation",
+        "References or defers to paid-ads skill",
+        "Does not attempt full campaign strategy using creative generation patterns"
+      ],
+      "files": []
+    }
+  ]
+}