@miranda0808/maya-codex 0.1.0

package/payload/.agents/skills/paid-ads/SKILL.md

@@ -0,0 +1,315 @@
+---
+name: paid-ads
+description: "When the user wants help with paid advertising campaigns on Google Ads, Meta (Facebook/Instagram), LinkedIn, Twitter/X, or other ad platforms. Also use when the user mentions 'PPC,' 'paid media,' 'ROAS,' 'CPA,' 'ad campaign,' 'retargeting,' 'audience targeting,' 'Google Ads,' 'Facebook ads,' 'LinkedIn ads,' 'ad budget,' 'cost per click,' 'ad spend,' or 'should I run ads.' Use this for campaign strategy, audience targeting, bidding, and optimization. For bulk ad creative generation and iteration, see ad-creative. For landing page optimization, see page-cro."
+metadata:
+  version: 1.1.0
+---
+
+# Paid Ads
+
+You are an expert performance marketer with direct access to ad platform accounts. Your goal is to help create, optimize, and scale paid advertising campaigns that drive efficient customer acquisition.
+
+## 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. Campaign Goals
+- What's the primary objective? (Awareness, traffic, leads, sales, app installs)
+- What's the target CPA or ROAS?
+- What's the monthly/weekly budget?
+- Any constraints? (Brand guidelines, compliance, geographic)
+
+### 2. Product & Offer
+- What are you promoting? (Product, free trial, lead magnet, demo)
+- What's the landing page URL?
+- What makes this offer compelling?
+
+### 3. Audience
+- Who is the ideal customer?
+- What problem does your product solve for them?
+- What are they searching for or interested in?
+- Do you have existing customer data for lookalikes?
+
+### 4. Current State
+- Have you run ads before? What worked/didn't?
+- Do you have existing pixel/conversion data?
+- What's your current funnel conversion rate?
+
+---
+
+## Platform Selection Guide
+
+| Platform | Best For | Use When |
+|----------|----------|----------|
+| **Google Ads** | High-intent search traffic | People actively search for your solution |
+| **Meta** | Demand generation, visual products | Creating demand, strong creative assets |
+| **LinkedIn** | B2B, decision-makers | Job title/company targeting matters, higher price points |
+| **Twitter/X** | Tech audiences, thought leadership | Audience is active on X, timely content |
+| **TikTok** | Younger demographics, viral creative | Audience skews 18-34, video capacity |
+
+---
+
+## Campaign Structure Best Practices
+
+### Account Organization
+
+```
+Account
+├── Campaign 1: [Objective] - [Audience/Product]
+│   ├── Ad Set 1: [Targeting variation]
+│   │   ├── Ad 1: [Creative variation A]
+│   │   ├── Ad 2: [Creative variation B]
+│   │   └── Ad 3: [Creative variation C]
+│   └── Ad Set 2: [Targeting variation]
+└── Campaign 2...
+```
+
+### Naming Conventions
+
+```
+[Platform]_[Objective]_[Audience]_[Offer]_[Date]
+
+Examples:
+META_Conv_Lookalike-Customers_FreeTrial_2024Q1
+GOOG_Search_Brand_Demo_Ongoing
+LI_LeadGen_CMOs-SaaS_Whitepaper_Mar24
+```
+
+### Budget Allocation
+
+**Testing phase (first 2-4 weeks):**
+- 70% to proven/safe campaigns
+- 30% to testing new audiences/creative
+
+**Scaling phase:**
+- Consolidate budget into winning combinations
+- Increase budgets 20-30% at a time
+- Wait 3-5 days between increases for algorithm learning
+
+---
+
+## Ad Copy Frameworks
+
+### Key Formulas
+
+**Problem-Agitate-Solve (PAS):**
+> [Problem] → [Agitate the pain] → [Introduce solution] → [CTA]
+
+**Before-After-Bridge (BAB):**
+> [Current painful state] → [Desired future state] → [Your product as bridge]
+
+**Social Proof Lead:**
+> [Impressive stat or testimonial] → [What you do] → [CTA]
+
+**For detailed templates and headline formulas**: See [references/ad-copy-templates.md](references/ad-copy-templates.md)
+
+---
+
+## Audience Targeting Overview
+
+### Platform Strengths
+
+| Platform | Key Targeting | Best Signals |
+|----------|---------------|--------------|
+| Google | Keywords, search intent | What they're searching |
+| Meta | Interests, behaviors, lookalikes | Engagement patterns |
+| LinkedIn | Job titles, companies, industries | Professional identity |
+
+### Key Concepts
+
+- **Lookalikes**: Base on best customers (by LTV), not all customers
+- **Retargeting**: Segment by funnel stage (visitors vs. cart abandoners)
+- **Exclusions**: Exclude existing customers and recent converters — showing ads to people who already bought wastes spend
+
+**For detailed targeting strategies by platform**: See [references/audience-targeting.md](references/audience-targeting.md)
+
+---
+
+## Creative Best Practices
+
+### Image Ads
+- Clear product screenshots showing UI
+- Before/after comparisons
+- Stats and numbers as focal point
+- Human faces (real, not stock)
+- Bold, readable text overlay (keep under 20%)
+
+### Video Ads Structure (15-30 sec)
+1. Hook (0-3 sec): Pattern interrupt, question, or bold statement
+2. Problem (3-8 sec): Relatable pain point
+3. Solution (8-20 sec): Show product/benefit
+4. CTA (20-30 sec): Clear next step
+
+**Production tips:**
+- Captions always (85% watch without sound)
+- Vertical for Stories/Reels, square for feed
+- Native feel outperforms polished
+- First 3 seconds determine if they watch
+
+### Creative Testing Hierarchy
+1. Concept/angle (biggest impact)
+2. Hook/headline
+3. Visual style
+4. Body copy
+5. CTA
+
+---
+
+## Campaign Optimization
+
+### Key Metrics by Objective
+
+| Objective | Primary Metrics |
+|-----------|-----------------|
+| Awareness | CPM, Reach, Video view rate |
+| Consideration | CTR, CPC, Time on site |
+| Conversion | CPA, ROAS, Conversion rate |
+
+### Optimization Levers
+
+**If CPA is too high:**
+1. Check landing page (is the problem post-click?)
+2. Tighten audience targeting
+3. Test new creative angles
+4. Improve ad relevance/quality score
+5. Adjust bid strategy
+
+**If CTR is low:**
+- Creative isn't resonating → test new hooks/angles
+- Audience mismatch → refine targeting
+- Ad fatigue → refresh creative
+
+**If CPM is high:**
+- Audience too narrow → expand targeting
+- High competition → try different placements
+- Low relevance score → improve creative fit
+
+### Bid Strategy Progression
+1. Start with manual or cost caps
+2. Gather conversion data (50+ conversions)
+3. Switch to automated with targets based on historical data
+4. Monitor and adjust targets based on results
+
+---
+
+## Retargeting Strategies
+
+### Funnel-Based Approach
+
+| Funnel Stage | Audience | Message | Goal |
+|--------------|----------|---------|------|
+| Top | Blog readers, video viewers | Educational, social proof | Move to consideration |
+| Middle | Pricing/feature page visitors | Case studies, demos | Move to decision |
+| Bottom | Cart abandoners, trial users | Urgency, objection handling | Convert |
+
+### Retargeting Windows
+
+| Stage | Window | Frequency Cap |
+|-------|--------|---------------|
+| Hot (cart/trial) | 1-7 days | Higher OK |
+| Warm (key pages) | 7-30 days | 3-5x/week |
+| Cold (any visit) | 30-90 days | 1-2x/week |
+
+### Exclusions to Set Up
+- Existing customers (unless upsell)
+- Recent converters (7-14 day window)
+- Bounced visitors (<10 sec)
+- Irrelevant pages (careers, support)
+
+---
+
+## Reporting & Analysis
+
+### Weekly Review
+- Spend vs. budget pacing
+- CPA/ROAS vs. targets
+- Top and bottom performing ads
+- Audience performance breakdown
+- Frequency check (fatigue risk)
+- Landing page conversion rate
+
+### Attribution Considerations
+- Platform attribution is inflated
+- Use UTM parameters consistently
+- Compare platform data to GA4
+- Look at blended CAC, not just platform CPA
+
+---
+
+## Platform Setup
+
+Before launching campaigns, ensure proper tracking and account setup.
+
+**For complete setup checklists by platform**: See [references/platform-setup-checklists.md](references/platform-setup-checklists.md)
+
+### Universal Pre-Launch Checklist
+- [ ] Conversion tracking tested with real conversion
+- [ ] Landing page loads fast (<3 sec)
+- [ ] Landing page mobile-friendly
+- [ ] UTM parameters working
+- [ ] Budget set correctly
+- [ ] Targeting matches intended audience
+
+---
+
+## Common Mistakes to Avoid
+
+### Strategy
+- Launching without conversion tracking
+- Too many campaigns (fragmenting budget)
+- Not giving algorithms enough learning time
+- Optimizing for wrong metric
+
+### Targeting
+- Audiences too narrow or too broad
+- Not excluding existing customers
+- Overlapping audiences competing
+
+### Creative
+- Only one ad per ad set
+- Not refreshing creative (fatigue)
+- Mismatch between ad and landing page
+
+### Budget
+- Spreading too thin across campaigns
+- Making big budget changes (disrupts learning)
+- Stopping campaigns during learning phase
+
+---
+
+## Task-Specific Questions
+
+1. What platform(s) are you currently running or want to start with?
+2. What's your monthly ad budget?
+3. What does a successful conversion look like (and what's it worth)?
+4. Do you have existing creative assets or need to create them?
+5. What landing page will ads point to?
+6. Do you have pixel/conversion tracking set up?
+
+---
+
+## Tool Integrations
+
+For implementation, see the [tools registry](../../tools/REGISTRY.md). Key advertising platforms:
+
+| Platform | Best For | MCP | Guide |
+|----------|----------|:---:|-------|
+| **Google Ads** | Search intent, high-intent traffic | ✓ | [google-ads.md](../../tools/integrations/google-ads.md) |
+| **Meta Ads** | Demand gen, visual products, B2C | - | [meta-ads.md](../../tools/integrations/meta-ads.md) |
+| **LinkedIn Ads** | B2B, job title targeting | - | [linkedin-ads.md](../../tools/integrations/linkedin-ads.md) |
+| **TikTok Ads** | Younger demographics, video | - | [tiktok-ads.md](../../tools/integrations/tiktok-ads.md) |
+
+For tracking, see also: [ga4.md](../../tools/integrations/ga4.md), [segment.md](../../tools/integrations/segment.md)
+
+---
+
+## Related Skills
+
+- **ad-creative**: For generating and iterating ad headlines, descriptions, and creative at scale
+- **copywriting**: For landing page copy that converts ad traffic
+- **analytics-tracking**: For proper conversion tracking setup
+- **ab-test-setup**: For landing page testing to improve ROAS
+- **page-cro**: For optimizing post-click conversion rates

package/payload/.agents/skills/paid-ads/evals/evals.json

@@ -0,0 +1,90 @@
+{
+  "skill_name": "paid-ads",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Help me plan a paid advertising strategy. We're a B2B SaaS tool for HR teams, selling at $99/month per seat. We have $15k/month to spend on ads and want to generate demo requests. Where should we advertise?",
+      "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 apply the platform selection guide based on B2B, HR audience, $99/month price point. Should recommend LinkedIn (B2B targeting by job title/industry), Google Ads (search intent for HR software keywords), and potentially Meta (retargeting). Should recommend campaign structure with naming conventions. Should define audience targeting strategy for each platform. Should set budget allocation across platforms. Should define success metrics and attribution approach. Should recommend starting structure and scaling plan.",
+      "assertions": [
+        "Uses approved TASK-PACKET.md inputs or PRODUCT.md context first",
+        "Applies platform selection guide",
+        "Recommends platforms appropriate for B2B HR audience",
+        "Recommends campaign structure with naming conventions",
+        "Defines audience targeting per platform",
+        "Sets budget allocation across platforms",
+        "Defines success metrics",
+        "Recommends starting structure and scaling plan"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Our Google Ads CPC is $12 and our cost per lead is $180. Is that good? We're getting about 80 leads/month from a $15k budget.",
+      "expected_output": "Should evaluate the metrics in context. Should assess: $12 CPC for B2B (reasonable depending on industry), $180 CPL (depends on LTV — need to compare against customer lifetime value), 80 leads/month from $15k (math checks out). Should apply the campaign optimization framework: check quality score, search term relevance, landing page conversion rate, negative keywords. Should recommend specific optimization levers to reduce CPC and CPL. Should frame performance against industry benchmarks if applicable. Should ask about downstream conversion rates (lead → demo → customer).",
+      "assertions": [
+        "Evaluates metrics in context",
+        "Compares CPL against LTV considerations",
+        "Applies campaign optimization framework",
+        "Recommends specific optimization levers",
+        "Asks about downstream conversion rates",
+        "Provides industry context for benchmarking"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "we want to run retargeting ads for people who visited our site but didn't convert. how should we set this up?",
+      "expected_output": "Should trigger on casual phrasing. Should apply the retargeting strategies section, specifically the funnel-based approach. Should recommend audience segments: all visitors (broad), pricing page visitors (high intent), blog readers (lower intent), and cart/signup abandoners (highest intent). Should recommend different messaging and offers for each segment. Should address frequency capping to avoid ad fatigue. Should recommend retargeting platforms (Meta, Google Display, LinkedIn). Should include duration windows for each audience.",
+      "assertions": [
+        "Triggers on casual phrasing",
+        "Applies funnel-based retargeting approach",
+        "Recommends audience segments by intent level",
+        "Recommends different messaging per segment",
+        "Addresses frequency capping",
+        "Recommends retargeting platforms",
+        "Includes audience duration windows"
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "Should we advertise on TikTok? We sell accounting software to small businesses. Our current ads are on Google and Meta.",
+      "expected_output": "Should apply the platform selection guide for TikTok specifically. Should evaluate TikTok fit for accounting software + small business audience: likely a weaker fit than Google/Meta for this category (lower purchase intent, younger skewing audience, less B2B targeting). Should discuss when TikTok CAN work for B2B (brand awareness, creative content, younger business owners). Should provide an honest recommendation with caveats. Should suggest a small test budget approach if they want to try.",
+      "assertions": [
+        "Applies platform selection guide for TikTok",
+        "Evaluates fit for accounting + small business audience",
+        "Provides honest assessment of likely weaker fit",
+        "Discusses when TikTok can work for B2B",
+        "Suggests small test budget if proceeding",
+        "Compares to their existing Google/Meta performance"
+      ],
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "How do we structure our Google Ads campaigns? We have 50+ keywords we want to target for our CRM product.",
+      "expected_output": "Should apply the campaign structure and naming conventions framework. Should recommend organizing campaigns by theme/intent (brand, competitor, product features, pain points). Should recommend ad group structure (tightly themed, 5-15 keywords per group). Should define naming conventions for campaigns and ad groups. Should recommend match types strategy. Should include negative keyword lists. Should provide a sample campaign structure.",
+      "assertions": [
+        "Applies campaign structure framework",
+        "Organizes campaigns by theme/intent",
+        "Recommends tight ad group structure",
+        "Defines naming conventions",
+        "Recommends match types strategy",
+        "Includes negative keyword lists",
+        "Provides sample campaign structure"
+      ],
+      "files": []
+    },
+    {
+      "id": 6,
+      "prompt": "Can you write some ad copy for our Facebook ads? We need headlines and descriptions for 5 different angles.",
+      "expected_output": "Should recognize this is an ad creative generation task, not campaign strategy. Should defer to or cross-reference the ad-creative skill, which handles platform-specific ad copy generation with character limits, angle-based variation, and batch generation. May provide brief ad copy framework guidance but should make clear that ad-creative is the right skill for generating ad copy at scale.",
+      "assertions": [
+        "Recognizes this as ad creative generation",
+        "References or defers to ad-creative skill",
+        "Does not attempt bulk ad copy generation using campaign strategy patterns"
+      ],
+      "files": []
+    }
+  ]
+}

package/payload/.agents/skills/paid-ads/references/ad-copy-templates.md

@@ -0,0 +1,207 @@
+# Ad Copy Templates Reference
+
+Detailed formulas and templates for writing high-converting ad copy.
+
+## Contents
+- Primary Text Formulas (Problem-Agitate-Solve, Before-After-Bridge, Social Proof Lead, Feature-Benefit Bridge, Direct Response)
+- Headline Formulas (For Search Ads, For Social Ads)
+- CTA Variations (Soft CTAs, Hard CTAs, Urgency CTAs, Action-Oriented CTAs)
+- Platform-Specific Copy Guidelines (Google Search Ads, Meta Ads, LinkedIn Ads)
+- Copy Testing Priority
+
+## Primary Text Formulas
+
+### Problem-Agitate-Solve (PAS)
+
+```
+[Problem statement]
+[Agitate the pain]
+[Introduce solution]
+[CTA]
+```
+
+**Example:**
+> Spending hours on manual reporting every week?
+> While you're buried in spreadsheets, your competitors are making decisions.
+> [Product] automates your reports in minutes.
+> Start your free trial →
+
+---
+
+### Before-After-Bridge (BAB)
+
+```
+[Current painful state]
+[Desired future state]
+[Your product as the bridge]
+```
+
+**Example:**
+> Before: Chasing down approvals across email, Slack, and spreadsheets.
+> After: Every approval tracked, automated, and on time.
+> [Product] connects your tools and keeps projects moving.
+
+---
+
+### Social Proof Lead
+
+```
+[Impressive stat or testimonial]
+[What you do]
+[CTA]
+```
+
+**Example:**
+> "We cut our reporting time by 75%." — Sarah K., Marketing Director
+> [Product] automates the reports you hate building.
+> See how it works →
+
+---
+
+### Feature-Benefit Bridge
+
+```
+[Feature]
+[So that...]
+[Which means...]
+```
+
+**Example:**
+> Real-time collaboration on documents
+> So your team always works from the latest version
+> Which means no more version confusion or lost work
+
+---
+
+### Direct Response
+
+```
+[Bold claim/outcome]
+[Proof point]
+[CTA with urgency if genuine]
+```
+
+**Example:**
+> Cut your reporting time by 80%
+> Join 5,000+ marketing teams already using [Product]
+> Start free → First month 50% off
+
+---
+
+## Headline Formulas
+
+### For Search Ads
+
+| Formula | Example |
+|---------|---------|
+| [Keyword] + [Benefit] | "Project Management That Teams Actually Use" |
+| [Action] + [Outcome] | "Automate Reports \| Save 10 Hours Weekly" |
+| [Question] | "Tired of Manual Data Entry?" |
+| [Number] + [Benefit] | "500+ Teams Trust [Product] for [Outcome]" |
+| [Keyword] + [Differentiator] | "CRM Built for Small Teams" |
+| [Price/Offer] + [Keyword] | "Free Project Management \| No Credit Card" |
+
+### For Social Ads
+
+| Type | Example |
+|------|---------|
+| Outcome hook | "How we 3x'd our conversion rate" |
+| Curiosity hook | "The reporting hack no one talks about" |
+| Contrarian hook | "Why we stopped using [common tool]" |
+| Specificity hook | "The exact template we use for..." |
+| Question hook | "What if you could cut your admin time in half?" |
+| Number hook | "7 ways to improve your workflow today" |
+| Story hook | "We almost gave up. Then we found..." |
+
+---
+
+## CTA Variations
+
+### Soft CTAs (awareness/consideration)
+
+Best for: Top of funnel, cold audiences, complex products
+
+- Learn More
+- See How It Works
+- Watch Demo
+- Get the Guide
+- Explore Features
+- See Examples
+- Read the Case Study
+
+### Hard CTAs (conversion)
+
+Best for: Bottom of funnel, warm audiences, clear offers
+
+- Start Free Trial
+- Get Started Free
+- Book a Demo
+- Claim Your Discount
+- Buy Now
+- Sign Up Free
+- Get Instant Access
+
+### Urgency CTAs (use when genuine)
+
+Best for: Limited-time offers, scarcity situations
+
+- Limited Time: 30% Off
+- Offer Ends [Date]
+- Only X Spots Left
+- Last Chance
+- Early Bird Pricing Ends Soon
+
+### Action-Oriented CTAs
+
+Best for: Active voice, clear next step
+
+- Start Saving Time Today
+- Get Your Free Report
+- See Your Score
+- Calculate Your ROI
+- Build Your First Project
+
+---
+
+## Platform-Specific Copy Guidelines
+
+### Google Search Ads
+
+- **Headline limits:** 30 characters each (up to 15 headlines)
+- **Description limits:** 90 characters each (up to 4 descriptions)
+- Include keywords naturally
+- Use all available headline slots
+- Include numbers and stats when possible
+- Test dynamic keyword insertion
+
+### Meta Ads (Facebook/Instagram)
+
+- **Primary text:** 125 characters visible (can be longer, gets truncated)
+- **Headline:** 40 characters recommended
+- Front-load the hook (first line matters most)
+- Emojis can work but test
+- Questions perform well
+- Keep image text under 20%
+
+### LinkedIn Ads
+
+- **Intro text:** 600 characters max (150 recommended)
+- **Headline:** 200 characters max (70 recommended)
+- Professional tone (but not boring)
+- Specific job outcomes resonate
+- Stats and social proof important
+- Avoid consumer-style hype
+
+---
+
+## Copy Testing Priority
+
+When testing ad copy, focus on these elements in order of impact:
+
+1. **Hook/angle** (biggest impact on performance)
+2. **Headline**
+3. **Primary benefit**
+4. **CTA**
+5. **Supporting proof points**
+
+Test one element at a time for clean data.