---
name: creative-analyzer
description: Activates when the user asks to analyze Meta Ads creative performance, identify winners and losers, detect creative fatigue, or get kill/scale recommendations for ads. Pulls live data from Meta via the connected MCP server (Pipeboard, Windsor, or Composio Metaads). Replaces Motion app's core analytics functionality. Always parses ad names according to the brand-kit naming convention to identify hook/persona/style patterns automatically.
---

# Creative Analyzer Skill

The core analysis engine of Pillar 3. Connects to your live Meta Ads data, identifies winners and losers, detects fatigue, and parses naming conventions to find what's actually driving results. Output feeds into the weekly-creative-report skill (for Monday reports) and the creative-strategist skill (for next-batch recommendations).

## Activation Rules

Activate when:
- The user asks to analyze ads, find winners, identify what's working, detect fatigue, or get performance insights
- The user runs any of the slash commands defined below
- The weekly-creative-report or creative-strategist skill calls this skill internally

## Prerequisites

1. **A Meta Ads MCP connected to Claude Code.** One of:
   - Pipeboard (`https://meta-ads.mcp.pipeboard.co/`) — recommended for most users
   - Windsor MCP (cross-channel attribution + creative analytics)
   - Composio Metaads MCP (if already installed from Pillar 2)
2. **At least 7 days of ad performance data** in the connected ad account (analysis is meaningless without enough data)
3. **brand-kit.md** in project root (for naming convention parsing)

If the MCP isn't connected, prompt the user to set it up first.

---

## Analysis Framework

### Winner identification

Apply these tiered thresholds to identify winners:

- **Winners:** ROAS above account average AND spend > $50
- **Stars:** ROAS in top 10% AND spend > $200
- **Consistent performers:** Maintaining above-average ROAS for 14+ consecutive days

These thresholds are defaults. The skill should adapt them based on what's stored in brand-kit.md (or prompt the user to set them on first run).

### Loser identification

- **Below-average ROAS** with spend > $100 (enough data to be conclusive, not just a small sample)
- **Urgent kill list:** Any ad spending > $50/day with ROAS below 0.5

### Fatigue detection

Flag any ad that meets ANY of these conditions:

- CTR declined 20%+ vs. its first 7 days of delivery
- Frequency exceeds 3.0 AND CTR is declining week-over-week
- CPA increased 25%+ vs. its first 7 days

Status labels:
- **HEALTHY:** No fatigue indicators triggered
- **WARNING:** One indicator triggered
- **CRITICAL:** Two or more indicators triggered, OR ad spending > $50/day with one indicator

### Pattern analysis (requires naming conventions)

Parse every ad name using the brand-kit pattern:
```
[brand]_[objective]_[hook]_[persona]_[style]_[version]_[date]
```

Group performance metrics by:
- Hook type (problem / benefit / social / curiosity)
- Persona (sarah / marcus / dana / jordan)
- Visual style (minimal / lifestyle / ugc / studio)
- Combination (specific hook x persona x style triplets)

For each grouping, calculate:
- Average ROAS
- Average CTR
- Average CPA
- Total spend
- Number of ads in the grouping

Identify:
- Best-performing hook (highest weighted ROAS)
- Best-performing persona
- Best-performing style
- Best-performing specific combination
- Worst-performing combinations (where to stop spending)

### Recommendations

For each CRITICAL fatigue ad: recommend specific refresh action
For each winner: recommend 2-3 variations to test next batch
For overall strategy: recommend creative brief for next batch based on patterns

---

## Output Structure

Always structure the analysis report as:

### A. Executive Summary (3 sentences)

What's working. What's dying. What to do about it.

Example:
> Problem-centric hooks targeting Sarah are dramatically outperforming everything else in your account this week, with an average ROAS of 3.2 vs. the account average of 1.8. Three ads are entering CRITICAL fatigue and should be paused or refreshed within 48 hours. Your next batch should test 4-6 new variations of the problem-centric/Sarah angle while killing the curiosity-hook variants entirely.

### B. Winners Table

| Ad name | Spend | ROAS | CTR | Days active | Status |
|---|---|---|---|---|---|
| vitapure_sales_problem_sarah_minimal_v1_20260801 | $890 | 3.4 | 2.1% | 18 | STAR |
| vitapure_sales_problem_sarah_lifestyle_v1_20260801 | $620 | 2.8 | 1.9% | 18 | WINNER |

### C. Kill List

Ads to pause immediately, with reason.

| Ad name | Spend | ROAS | Reason |
|---|---|---|---|
| vitapure_sales_curiosity_marcus_studio_v1_20260801 | $340 | 0.4 | URGENT: ROAS below 0.5 with significant spend |

### D. Fatigue Alerts

Ads approaching fatigue, with recommended action.

| Ad name | Status | Trigger | Recommendation |
|---|---|---|---|
| vitapure_sales_benefit_dana_lifestyle_v1_20260801 | WARNING | CTR declined 23% from first week | Refresh creative within 7 days; same hook/persona, new visual variation |

### E. Pattern Insights

Hook/persona/style scorecards.

**Hook performance:**
| Hook | Avg ROAS | Avg CTR | Total spend | Ad count |
|---|---|---|---|---|
| problem | 2.9 | 2.0% | $1,840 | 6 |
| benefit | 1.7 | 1.3% | $1,200 | 6 |
| social | 1.5 | 1.5% | $890 | 6 |
| curiosity | 0.8 | 0.9% | $720 | 6 |

(Same structure for personas and styles.)

### F. Next Steps

Specific creative brief for the next batch:

```
Recommended batch for next week:

Top combinations to scale (4-6 variations each):
1. problem + sarah + minimal (current STAR)
2. problem + sarah + lifestyle (current WINNER)

Untested combinations to try (2-3 variations each):
1. problem + dana + minimal (untested, but adjacent to winners)
2. problem + sarah + ugc (new style for the winning hook+persona)

Drop entirely:
- All curiosity hook variants (consistently lowest performer)

Estimated batch size: ~16-20 new ads
Estimated production cost via Pillar 1: ~$15
```

---

## Slash Commands

### `/creative-analyzer [time-range]`

Run the full analysis on a specified time range.

**Usage:**
```
/creative-analyzer last 14 days
/creative-analyzer 2026-07-15 to 2026-07-31
/creative-analyzer this month
```

**Default:** Last 14 days if no time range specified.

### `/quick-check`

A fast version that returns just the executive summary and the kill list. Use for daily quick-checks.

### `/calibrate-thresholds`

Adapt the winner/loser/fatigue thresholds to your specific account's averages.

**Workflow:**
1. Pull last 90 days of account-level data
2. Calculate account average ROAS, CTR, CPA
3. Suggest new thresholds:
   - Winner threshold: account average * 1.0
   - Star threshold: top 10% of last 90 days
   - Urgent kill threshold: ROAS < (account average * 0.3)
4. Save thresholds to brand-kit.md so they persist across runs
5. Apply going forward

### `/explain [ad-name]`

Deep-dive analysis on a single ad.

**Usage:**
```
/explain vitapure_sales_problem_sarah_minimal_v1_20260801
```

**Returns:**
- Full performance history (daily metrics over the ad's lifetime)
- Comparison to account averages
- Comparison to other ads with the same hook
- Comparison to other ads with the same persona
- Fatigue trajectory chart (text-based)
- Specific recommendations

### `/cohort [hook|persona|style]`

Analyze all ads in a specific cohort.

**Usage:**
```
/cohort hook problem
/cohort persona sarah
/cohort style minimal
```

---

## Cross-Skill Integration

**Calls into this skill:**
- The user (directly via slash commands)
- weekly-creative-report (runs every Monday)
- creative-strategist (when generating next-batch recommendations)

**This skill calls:**
- The connected Meta Ads MCP (Pipeboard / Windsor / Composio)
- brand-kit (for naming convention parsing and threshold calibration)

**Output flows to:**
- weekly-creative-report (consumes the analysis)
- creative-strategist (uses pattern insights to build next matrix)
- Pillar 1's static-ad-designer (the next-batch creative brief becomes the input for the next matrix)

---

## Common Issues and Fixes

### "I don't see naming convention patterns in the output"

Most likely cause: ad names in the account don't follow the brand-kit pattern. Check by running:
```
List my 20 most recent ads. Do their names match the pattern 
[brand]_[objective]_[hook]_[persona]_[style]_[version]_[date]?
```

If they don't, this skill can still produce winners/losers/fatigue, but pattern analysis will be unavailable. Either:
- Rename existing ads to match the pattern (10-15 min one-time effort)
- Or accept that pattern insights only work for ads launched AFTER you adopted the convention (Pillar 2's bulk-uploader enforces it for all new ads)

### "ROAS data is missing"

Most common cause: Meta Pixel or Conversions API not properly tracking purchases. Without conversion data, ROAS can't be calculated. Fall back to CTR and CPC analysis until tracking is fixed. The skill should detect this automatically and switch to a CTR-based winner/loser methodology.

### "Numbers don't match what I see in Ads Manager"

Most likely cause: time range mismatch. Meta Ads Manager defaults to the account's local timezone; the MCP may use UTC. Specify timezone explicitly:
```
/creative-analyzer last 14 days timezone:America/New_York
```

---

## Output Format Note

For Monday reports (called by weekly-creative-report skill), output should be condensed and email-friendly.

For ad-hoc deep dives (user calling this skill directly), output should be comprehensive with full tables.

The skill should detect the calling context and adjust verbosity accordingly.