/personalization-subagent-pattern

name: personalization-subagent-pattern
description: Reusable approval-loop pattern for fanning out lead personalization across parallel Claude Code Task sub-agents. Shows the user 1 sample personalization, collects feedback, runs 10 more, approves, runs 10 more — stops when 2 consecutive rounds have zero edits, then scales to the full list. ALWAYS uses Claude Code Task tool sub-agents — never an external Anthropic/OpenAI API key. Use when any skill needs per-lead custom variables (situation lines, value lines, CTAs).

Personalization Sub-Agent Pattern

Cold email personalization at scale requires per-lead generation. Claude Code's Task tool lets you fan out to many sub-agents in parallel, each personalizing a slice of the lead list. This skill defines the reusable approval-loop pattern.

Always Task tool — never an API key

This skill runs entirely inside Claude Code via the Task tool. No Anthropic SDK calls, no OpenAI calls. This is intentional:

• **No extra API spend.** Uses your Claude Code plan.
• **No key management.** Works out of the box.
• **Parallel by design.** Claude Code spawns multiple Task sub-agents in one message, letting 100 leads finish in the time it takes to personalize 10.

At very large scale (1,000+ leads), the tuned prompt can optionally be shipped to the Anthropic API for throughput. But TUNING and normal campaign runs (under 500 leads) always go through the Task tool.

The approval loop (before full fan-out)

Don't personalize 500 leads and then discover the prompt is wrong. Loop first, then scale.

Round 0 — Sample on 1 lead

1. Pick one lead from the batch with a rich `company_description`. 2. Show the user: "Here's the company description I'm working with. Based on this, what would you say to personalize?" 3. Display what YOU (Claude) would generate for `situation_line`, `value_line`, `cta_soft`. 4. Ask: "Does this feel right? Edit it, and I'll re-tune."

Round 1-N — Batch of 10 with approval

1. Spawn one Task sub-agent with the current prompt + 10 leads. 2. Display all 10 results in a table:

   Lead                  | situation_line                          | value_line                    | cta_soft
   jane@acme.com         | You're building the only APM for Ruby.  | Our Ruby customers find ...   | Worth 10 min?
   john@otherco.com      | ...                                     | ...                           | ...

3. Ask: "Any edits? Point at the row number and say what's wrong." 4. If the user has edits, update the prompt (or add rules like "never use the word X") and re-run a new batch. 5. If the user has **zero edits for 2 consecutive rounds**, the prompt is locked. Scale to the full list.

Scale — Full fan-out

Once locked:

• Split remaining leads into batches of 10-20.
• Launch 3-10 parallel Task sub-agents (one per variant × batch).
• Merge results by `lead_id`.

When to use

• Any campaign where per-lead custom variables are needed (beyond just {first_name})
• When you have 50+ leads and want personalization without manual writing
• When `/auto-research-public` or similar orchestration skills need parallel personalization

Don't use this for

• Small batches (<10 leads) — just personalize inline in the main conversation (no fan-out needed)
• Static copy (same email to every lead) — personalization wastes tokens

When to use

• Any campaign where per-lead custom variables are needed (beyond just {first_name})
• When you have 50+ leads and want personalization without manual writing
• When `/auto-research-public` or similar orchestration skills need parallel personalization

Don't use this for

• Small batches (<20 leads) — just personalize inline in the main conversation
• Static copy (same email to every lead) — personalization wastes tokens

The pattern

1. Prepare the lead batch

Before fanning out, your lead batch should be a JSON array where each lead has:

{
  "lead_id": "<stable identifier>",
  "first_name": "<str>",
  "last_name": "<str>",
  "email": "<str>",
  "company_name": "<str>",
  "company_domain": "<str>",
  "company_description": "<1-3 sentences about what the company does>",
  "title": "<str>",
  "linkedin_url": "<optional>",
  "enrichment_data": { ... any extra signals ... }
}

The richer the `company_description`, the better the personalization. If you only have company names, the output will be generic.

2. Define the output schema

Decide up front what fields each sub-agent must return. Example:

{
  "lead_id": "<same id>",
  "situation_line": "<1 sentence — what you noticed about their company>",
  "value_line": "<1 sentence — connecting their situation to your offer>",
  "cta_soft": "<1 sentence — soft ask, e.g. 'worth a 15 min chat?'>"
}

Fewer fields = less that can go wrong. Default to 3 fields maximum per variant.

3. Split into variants (A/B/C)

If testing 3 copy variants, run 3 parallel sub-agents per company (or per batch). Each gets a different *angle* prompt:

• **Variant A**: Lead with a pain observation. "Noticed X on your site..."
• **Variant B**: Lead with a compliment + transition. "Your approach to Y is unique..."
• **Variant C**: Lead with a question. "How are you thinking about Z?"

This gives you 3x the data from one list — you can A/B/C test which angle resonates.

4. Batch size

• **Small batches are the right default: 10-20 leads per sub-agent.**
• Bigger batches = fewer agents = cheaper but worse quality (agent loses context)
• Smaller batches = more agents = higher quality but more context usage in parent

For 100 leads:

• 10 sub-agents × 10 leads = good quality
• 5 sub-agents × 20 leads = faster
• 2 sub-agents × 50 leads = quality drops

For 1000 leads:

• Consider running in rounds of 100 (to avoid hitting context limits in parent)
• Each round launches 10 sub-agents of 10 leads each

5. The sub-agent prompt template

Every personalization sub-agent gets a prompt of this shape:

You are personalizin