Brand scoping

Outputs live under ~/notes/Klaviyo/<brand>/<subfolder>/, where <brand> is resolved at run time from the connected Klaviyo account's organizationName attribute (via mcp__claude_ai_Klaviyo__klaviyo_get_account_details). For ExampleBrand, this resolves to ExampleBrand. If multiple brands are connected, ask Will which brand the current run is for.

/klaviyo-segment

Klaviyo's segment builder is powerful but verbose. This skill takes a one-line natural-language definition and outputs both the human-readable rule + the Klaviyo segment JSON. Will pastes the JSON into the Klaviyo segment builder OR applies via API.

Flow

1. Parse the natural language — extract conditions. Categories:

• RFM: Recency (last order date), Frequency (order count), Monetary (lifetime value)
• Engagement: opened email in last N days, clicked in last N days, never opened, etc.
• Behavior: viewed product, added to cart, abandoned cart, browsed category
• Lifecycle: subscribers / customers / VIPs / lapsed
• Profile: location, language, custom property

1. Resolve metric names — Klaviyo's event metrics are brand-specific. Call mcp__claude_ai_Klaviyo__klaviyo_get_metrics to confirm the exact metric names (Placed Order, Active on Site, Viewed Product, etc.). Don't fabricate.
2. Build the segment definition — combine conditions with AND/OR logic. Show the resolved rule in plain English before generating JSON.
3. Generate the JSON spec — match Klaviyo's segment definition schema (Klaviyo segment API format).
4. Estimate segment size — if possible, use mcp__claude_ai_Klaviyo__klaviyo_query_metric_aggregates to ballpark how many profiles match. If exact unavailable, give a rough lower/upper bound.
5. Save — ~/notes/Klaviyo/<brand>/segments/[slug].md with NL definition + resolved rule + JSON + setup steps + estimated size.
6. Deploy — run scripts/deploy_segment.py <spec.md> which POSTs to Klaviyo's segments API using KLAVIYO_API_KEY from .env. Returns the new segment id + Klaviyo URL. If deploy fails (auth, schema, etc.) surface the API error verbatim.
7. Print summary — show the rule, segment id, Klaviyo URL, and link to the saved spec.

Common segment patterns

Output structure

# Segment — [slug]

**NL definition:** ...
**Resolved rule:** ...
**Estimated size:** N profiles (±error)
**Last updated:** YYYY-MM-DD

## JSON spec

{ "name": "...", "definition": { "condition_groups": [...] } }

## Klaviyo setup steps
1. Audience → Lists & Segments → Create List/Segment → Segment
2. Name: ...
3. Definition: ...
4. Save

What this skill does NOT do

• Does not maintain segments — set-and-forget per definition.
• Does not handle dynamic re-segmentation logic — segments are condition definitions, Klaviyo handles the live filtering.
• Does not delete or modify existing segments — create-only by design.

Failure modes

• Ambiguous NL request → ask Will to clarify the threshold ("how recent is recent?", "how high is high-LTV?").
• Metric not in account → tell Will which event needs to be tracked first; don't fabricate.
• Segment likely to be too small to be useful → surface and suggest a relaxed version.