The care goes into deliverability. Engaged only, bounces suppressed, recent buyers held out of the promotional sends. All sensible. None of it says anything about who a message is for, and inside that one engaged audience a customer who has bought twelve times sits next to someone who bought once, eleven months ago, and both get the same email.

The usual fix is a VIP segment. Somebody picks a number of orders, three or five, since it sounded about right, and everyone above it is a VIP. A lapsed segment gets built the same way, with a round number of days. Those thresholds are guesses, and every segment built on them inherits the guess.

RFM is the same instinct with the guessing taken out.

Three questions, scored from your own data

RFM asks three questions about every customer. How recently did they buy. How often do they buy. How much have they spent.

Klaviyo scores each answer 1, 2 or 3 and joins them into a three digit number, so 333 is your best customer and 111 is someone who has effectively left. Then it sorts everyone into six groups: Champions, Loyal, Recent, Needs Attention, At Risk and Inactive.

Here is how the scores are assigned.

• Recency. 3 if they bought in the last 180 days, 2 if in the last 365, 1 if longer ago than that.

• Frequency. 3 for the top third of your customers by order count, usually three or more orders. 2 for the middle third, usually two. 1 for the bottom third, usually one.

• Monetary. 3 for the top third by total spend, 2 for the middle third, 1 for the bottom.

Note the asymmetry. Recency uses fixed boundaries. Frequency and spend are percentiles of your own list, so the bar for being a top spender is set by your customers, and it moves as they change. Two brands with identical customers can have different Champions counts. That is the whole difference between this and the VIP segment somebody eyeballed.

The groups are instructions

Read the six groups as a set of instructions rather than a set of labels.

Needs Attention and At Risk look similar and are different problems. One holds a valuable customer who has stopped buying. The other holds a marginal customer on the way out. Sending both the same win-back email with the same discount is the mistake RFM exists to prevent.

The discount question is where the money is. A code sent to Champions buys nothing, since they were going to order anyway. The same code sent to At Risk might buy back a customer. Same offer, completely different economics, and until you can tell the two groups apart you are paying for both.

Movement is worth more than membership

When Klaviyo runs the report it writes three properties onto every profile: the current group, the previous group, and the date the group last changed.

Most people segment on the first one and stop. The other two are where the value is. A customer sitting in Champions needs nothing from you. A customer who was in Champions last month and is not this month is a situation, and one you can trigger a flow on the day it happens. Same in the other direction. Somebody who has just crossed from Loyal into Champions is a candidate for whatever you do for your best customers, and that transition is worth marking.

The properties refresh nightly. So each group stops being an audience you send to and becomes an event you respond to. That reframe has changed how I build retention programs more than any single flow has.

How I use it

The VIP tier is the obvious use, so start there and get past it.

The top group becomes a real VIP tier, with perks that are different rather than bigger, and its own landing page that feels like a different place. The segment decides who gets in. The experience is what makes it worth being in. Most VIP programs are a larger discount sent to a smaller list, which trains your best customers to wait for it.

A tier is one use of a six-group framework. Four more earn their place.

Every group gets a flow, triggered by arrival. Each group is a segment, and entering it starts the sequence. Somebody who lands in At Risk gets the At Risk emails the day they land there, rather than whenever the next campaign happens to go out. The group stops being an audience you send to and becomes an event you respond to.

One segment exists only to catch people moving up. It holds customers who have just crossed from Loyal into Champions, with a flow behind it. Klaviyo does not ship that. You define it because you have decided that transition is worth marking, and marking it is cheap.

The groups leave the inbox. Champions and Loyal become the seed for lookalike audiences, since people who resemble your best customers are a better acquisition target than people who resemble everyone who has ever bought. The drifting groups go the other way, into retargeting.

Predictive sits on top. RFM tells you which group somebody is in. Klaviyo's expected date of next order tells you roughly when they are due back. One gives you a reason to send and the other gives you a time. They come from the same data requirements, so if you qualify for one you qualify for both.

None of those four is a bigger discount, which is the point. RFM is worth having because it tells you who somebody is to your business. What you do with that ought to be more imaginative than a coupon.

The catch, and the workaround

Klaviyo's RFM report is a paid add-on. Even with the subscription it will not run until the account has at least 500 purchasing customers, 180 days of order history and some customers with three or more orders. That second barrier excludes a lot of the brands with the most to gain from this.

So I build it by hand, from ordinary segments. Recency is exact, since the segment builder can do "placed order zero times in the last 180 days" and that is Klaviyo's own boundary. Frequency is close: three or more orders, two, one. Spend is the awkward one, since the predictive property you would use carries the same 500 customer threshold.

This is the part Claude does, and it is the part I would not want to do by hand.

The hard part of building this yourself is knowing where the thresholds go. Two of the three axes are percentiles of your own list, and the segment builder will not tell you what your percentiles are. Through the Klaviyo connector Claude pulls the distribution of order counts and tells me where the thirds fall. One question, instead of an export and an afternoon in a spreadsheet.

Spend is the axis Klaviyo will not calculate for an account under its thresholds. Shopify has every order regardless. So Claude pulls the order history through the Shopify connector, groups it by customer, and takes the cutoffs from source. The number Klaviyo declined to give me was in the other system all along, and the job is joining the two.

One limit worth knowing: the Klaviyo connector reads segments but does not create them. So once the numbers are known, the six groups get entered by hand in the segment builder. Twenty minutes, once, and they maintain themselves.

What you get before you send anything

The shape of the six groups tells you what kind of business you are running. Lots of Recent and few Loyal: you are good at getting a first order and bad at getting a second. Lots of Needs Attention: you built something people liked and then stopped looking after them. Most brands I work with have never seen that picture, and it usually settles an argument they have been having for months.

The full build, with the exact score combinations for each group and the segment conditions, is on the blog: RFM Segmentation in Klaviyo, and How to Build It Without the Paid Tier.

The first page of results was five different companies, each with a guide on how to connect Klaviyo to Google Sheets, each arriving at the same recommendation, which happened to be their own connector.

There is nothing shady about that. Klaviyo has no native Google Sheets integration, a gap exists, and companies filled it. The guides are genuinely good. They rank because somebody was paid to make them rank. Nobody is paying to explain the route I actually use.

What stayed with me was the pattern rather than the pricing. Five results, one recommendation, and the recommendation is always a subscription.

What you are really buying

A connector authenticates to your account, lets you choose fields, writes them into a sheet, and then refreshes on a schedule.

That last part is the product. The export is trivial. Klaviyo hands you a CSV in four clicks. What you are paying for is that it happens again next Monday without you.

Once I saw it that way I started seeing the same shape everywhere. Almost every tool I have ever bought was sold on recurrence. It runs weekly. It updates in real time. It syncs continuously. Recurrence is what turns software into a subscription, so recurrence is what gets built and what gets marketed.

Which shaped what exists. Anything worth repeating got tooling. Anything you needed once got nothing.

The two kinds of work

I went back through the last few months of client work and looked at what I had actually wanted to know.

Some of it repeated. The same performance picture, every week, for every send. That set is small and it barely changes.

The rest was one-offs, and the one-offs never came back in the same shape twice. A segment that looked wrong. A pattern in reorder timing. Whether the discount-led sends were training people to wait. There are more of these than anyone can plan for, and they are where most of the useful answers came from.

For years those two needs had completely different economics. The recurring set could justify a pipeline, because you build it once and it pays back weekly. The one-offs justified nothing. Each was too small to warrant setup, so I either did it by hand or skipped it.

Skipping is the expensive habit, and it is invisible. You never find out what the unasked questions would have told you.

What changed

Both sets got cheap at the same time, and that is the part I underrated.

Klaviyo has an MCP connector. So does Google Drive. Connect them to Claude and you can ask for a specific cut of data in plain English, and get a sheet back that answers only that. No API work, no code, no new subscription.

The same setup also runs on a schedule. My weekly campaign report is built this way. Every send, with the list it went to, opens, click-through, revenue per recipient, spam complaints and unsubscribes. It runs on its own and fills in the gaps in the spreadsheet without me opening anything.

So the two things I had been treating as separate purchases turned out to be one thing. Ask once, or have it ask every Monday. Same connection, same plain English, different cadence.

That collapsed the calculation I used to make. When pulling a custom cut took an afternoon, only questions that looked important justified the effort, and I had to guess in advance which ones those were. The ones that turned out to matter usually looked minor going in. Now the guess costs nothing, so I stopped making it.

What replaced the test

I used to ask whether I would need an answer again, because that decided whether it was worth building anything at all.

That has turned into a setting rather than a decision. How often do I want this? Once, weekly, monthly. Nothing about the answer changes, only how often it arrives.

Which makes the old split look like what it always was. Recurring work got tooling because recurring work could be billed monthly. One-off work got nothing, since nobody can sell a subscription to a question you ask once.

Most accounts I see still carry the shape of that. A standing report nobody reads, and a stack of unasked questions that would change what they do next quarter. The report exists because reports were the thing being sold. The questions went unasked because nothing was ever marketed as the answer to them.

The connector companies are not wrong about their product. Plenty of people need a report that arrives on Monday, and they built a good way to get one.

The schedule was just never the thing you were buying. It was the billing model, and it shaped what got built for twenty years.

I gave Claude one screenshot and it designed my entire video title system.

Not a mood board. Not "here are some font ideas." A working system: hook cards, lower thirds, step cards, and an end card, all spec'd at 1080x1920 with exact sizes my video editor can use without asking me a single question.

Here's the whole process, including the parts where I pushed back.

The brief was one screenshot

I've been posting more video — Reels, Shorts, talking-head clips with captions. Every video needed a title card and I was eyeballing it in the editor every single time. Different fonts, different sizes, no system.

So I opened Claude Design, dropped in a single frame grab from a video whose style I liked, and typed one sentence: explore color and type pairings for my videos.

It didn't start designing. It asked questions first. What format — vertical, square, horizontal? What kind of videos? Which on-screen elements need a treatment — title cards, lower thirds, end cards? Where do they run?

Two minutes of tapping answers. Then it went to work with my actual design system attached — my navy, my gold, my sage, my Montserrat. Not a generic palette.

Six pairings, same headline

The first pass came back with six title card options. The detail that made them comparable: every card used the same headline. "Segment like a pro, in Klaviyo."

That sounds small. It isn't. When every option carries different copy, you end up judging the words instead of the design. Same words everywhere means you're only comparing type and color.

Each card came with its own spec line: font, size, line height, hex codes. And each one had a drop zone where I could drag in a real frame grab from my footage to see the type over actual video, not a flat background.

The script font fight

One option matched my reference almost exactly. But the script font — the handwritten accent that says "in Klaviyo" — bothered me. I told Claude exactly that: we need a better script font.

It came back with nine candidates. Same lockup, same optical size, side by side. Under each one, a note I wouldn't have thought to ask for: how the font survives Reels compression. Thin scripts fall apart when Instagram crunches your video. Two of the nine got flagged for exactly that.

I picked Kaushan Script. It took about two minutes, and the choice swapped through every card automatically.

Three fonts, three jobs

By the third round we had a locked system:

• Anton carries the hook. Uppercase, huge, always gold on navy.

• Montserrat carries everything that has to be read. Captions, CTAs, eyebrow text.

• Kaushan is the one handwritten accent per frame. Never a full sentence.

Claude wrote the usage rules without being asked. Minimum sizes. Color roles — Anton is always gold, Kaushan is always white, never the reverse. Safe margins so the Reels UI never covers the text.

Then it spec'd the whole kit

Once the hook card was locked, I asked for the rest: lower third, step card, end card.

This is where it got genuinely useful. Two decisions it made on its own:

The lower third has no script font at all. Claude flagged that a handwritten accent collides with burned-in captions, so it dropped it there. That's a judgment call I'd expect from a designer, not a chat window.

The end card is flat navy with no footage behind it, because my brand rules say no photography as background. It read my design system and followed it.

Every frame came with real 1080x1920 numbers. Anton 192px over two lines. Kaushan 126 with a 48px overlap. Eyebrow 120px off the bottom so the platform UI never covers it. My editor gets a spec sheet, not a vibe.

What I'd tell you to steal

If you try this yourself:

1. Bring a reference. One screenshot of something you like beats three paragraphs of description.

2. Attach your design system first. The whole exercise works because every option stayed inside my colors. Without that anchor you get generic output.

3. Push back in plain language. "We need a better script font" was enough. You don't need design vocabulary.

4. Ask for the spec, not just the picture. The numbers are what make it usable next week.

The whole thing — exploration, revisions, final specs, plus a LinkedIn carousel about the process — took one afternoon.

I break down a build like this one every week. Come along.

Become a Member — $5/month

The hours went on typing. Twenty-two campaigns, and every one of them needed a brief for the copy, a brief for the design, a testing checklist for the Klaviyo build, deliverables for client review, and segment logic for deployment. Then due dates across all of it. Then the dependencies between all of it. Then the whole thing again the following month, from nothing.

How Claude builds the board

Three mechanics replaced that work:

• Claude writes every brief, with specifications a designer can open and start from.

• Due dates calculate backward from the send date.

• Each subtask stays locked until the one before it closes, so design never begins on copy that is still moving.

I walk through the full board above. Five minutes.

Where the campaign data ends up

One thing to add, since it happens after the walkthrough ends. Data comes back into the board. Claude reads Klaviyo and writes each campaign's revenue into its own record, and the Figma link lands in the design task once the design is finished. By the end of a cycle, one record holds the campaign details, the copy, the design, the revenue, the campaign type and the segments it went to.

That is six things that normally sit in five tools with no connection between them. Asana, Klaviyo, Shopify and Figma each answer their own question, and none of them answers mine. With all of it in one place Claude can read, I ask about the month instead of opening four tabs and reconciling by eye.

The next stage after this one is the build itself. I wrote up how Claude builds my Klaviyo emails from the Figma files.

They’re right. It does, if you work the way I worked in June.

I spent one session that month building the same email five different ways. Every attempt started the same: read the Figma file, walk the component tree, guess at which property controls which thing, screenshot it, get it wrong, correct it. By the end I had a decent email and a bill that made no sense for what I’d produced.

The design was never the expensive part. The rediscovery was.

What I want to do here is explain exactly where the money goes in an AI-assisted design workflow, because once you see the mechanism, the fix is obvious and most people are optimizing the wrong thing.

Want more of these breakdowns? Subscribe for free.

Cost tracks turns, not complexity

Here is the thing almost nobody accounts for when they start using AI for production work.

Every call to the model re-sends the entire conversation up to that point. The model has no memory between calls. So each time you say “now change the headline,” you are also silently re-sending everything that came before it, and you pay for all of it again.

Which means cost doesn’t grow in a straight line. It grows on a curve.

Walk through it with round numbers. Say every turn adds 1,000 tokens.

• Turn 1: you send 1,000. You pay for 1,000.

• Turn 2: you send 2,000. Running total 3,000.

• Turn 3: you send 3,000. Running total 6,000.

• Turn 20: you send 20,000. Running total 210,000.

Twenty turns of a thousand tokens each isn’t 20,000 tokens. It’s 210,000. Step nineteen pays for everything before it, and step twenty pays for that.

Augment Code ran the numbers on this with a real agent loop. Their ten-step file-reading agent burned 472,500 input tokens. The same work in a single pass took 9,000. That’s a 43x difference, and the output was the same.

So “expensive” doesn’t mean what you think it means. A big email is not expensive. A long conversation about a small email is expensive.

That reframes the whole problem. You are not trying to make the work smaller. You are trying to make the conversation shorter.

Two kinds of turns, and they don’t cost the same

Once you know turns are the unit of cost, the next question is which turns you can delete.

They split cleanly into two types.

Writing is cheap. “Set this headline to that.” “Swap this price to $54.95.” “Hide this section.” These instructions are a handful of tokens each, and they are the actual work. This is the part that produces the email.

Reading is where the money goes. Asking the model to look at a Figma frame and understand it means pulling the entire structure of that frame into context. Every node, every property, every nested component instance, every variant. On a real email template that is an enormous amount of text, and Figma’s own documentation warns that without tight scoping, requests get slower and more token-hungry as the file grows.

One discovery read can cost more than the entire build that follows it.

And here’s the part that should bother you: without a system, you do that read at the start of every single email. Every month, you pay full price to teach the model things it already worked out last month. The knowledge evaporates the moment the session ends.

The third cost is being wrong

There’s a cost most people don’t count at all, and in my June session it was the biggest one.

Wrong guesses.

A bad guess doesn’t cost you one turn. It costs you three: the turn where you do the wrong thing, the turn where you notice, and the turn where you fix it. Then, because of the re-billing curve above, all three of those turns get charged again by every turn that follows them for the rest of the session.

Without a system you don’t only take more turns. You take more wrong turns, and they compound faster than the useful ones.

In my case one client’s Figma file has two components with errors in them. Any attempt to read their properties hangs for about sixty seconds and then fails. I discovered this the expensive way, several times, before I wrote it down.

Now it’s in the file. Line item. Don’t read these two, edit their text directly instead. That single sentence has probably saved more than the rest of the document combined.

If this is useful so far, share it with someone who’s building with AI.

Where the tokens sit matters as much as how many

This is the part I appreciated late, and it makes the gap wider than the raw token counts suggest.

Anthropic caches parts of your prompt. Per their documentation, re-reading cached content costs 0.1x the normal input price. One tenth. Writing to the cache costs slightly more than normal the first time (1.25x), then you’re reading at 10% from then on.

But there’s a condition, and the condition is everything.

The cached content has to be a stable prefix. It sits at the top of the conversation and it has to be byte-identical every time. Anything that changes invalidates the cache at that level and everything after it as well.

Now look at the two ways of working.

A system file is stable by definition. It’s a document. It doesn’t change between builds. It loads once at the top of the conversation and every single turn after that re-reads it at a tenth of the price.

Discovery is the exact opposite. It’s different every time, it lands in the middle of the message history rather than at the top, and when it changes it takes the cacheability of everything after it down with it.

So the system approach doesn’t only use fewer tokens. It puts the tokens it does use in the position that costs 90% less to re-read, while the discovery approach puts them in the worst possible position.

One note on honesty here: the default cache lifetime is five minutes, with a one-hour option. That covers an active build session comfortably. It does not carry across months. So the saving is real within a build, not between them.

What I built instead

None of this required anything exotic. It required writing things down.

The system has three parts.

One, a component library in Figma. Product card, section header, hero, price tier row, testimonial, divider, trust badges. Each exists once as a master with named properties. Nothing gets hand-built if a component covers it.

Two, matching blocks on the Klaviyo side. Every Figma component has a counterpart in how the template gets assembled. The Figma frame isn’t a picture of the email. It’s the same object one step earlier.

Three, and this is the part people skip, a written build file. The library is not the system. The library plus the document that explains it is the system.

That document contains the things that are otherwise expensive to rediscover:

• Which campaign type clones which existing frame

• The exact node IDs of every master component

• The property key for every editable field

• Which components are broken and how to work around them

• Where product prices and URLs get verified from

• What claims are banned in the copy

• The QA checklist before handoff

It’s about 4,000 tokens. It loads once at the start of a build and the build goes straight to swapping content. No looking around.

Section five of mine is literally titled “Writes, not reads.” That’s the whole thesis in three words.

Anthropic’s own guidance on this points the same direction. In their context engineering guide they note that “runtime exploration is slower than retrieving pre-computed data,” and recommend a hybrid that retrieves some context up front. The build file is the pre-computed data.

The Klaviyo half: don’t build what already exists

There’s a saving on the Klaviyo side that has nothing to do with tokens, and it’s the one I’d implement first if you’re starting from scratch, because it’s free.

Klaviyo has universal blocks. Save a block once and it’s available across every template in the account.

So the header and footer never get built. Not by me, not by Claude, not ever again. They already exist. They get dropped into the editor at the end.

The template that actually gets constructed is only the part of the email that is genuinely new that month, which is usually just the middle section.

For scale: the footer alone is around 10KB of the rendered email. That’s 10KB nobody has to assemble, review, or QA, every single send.

One practical warning, learned the hard way and now written into my build file: once a universal block has been added to a template in the editor, API edits to that template start failing. So the order matters. Build the template, make every programmatic edit, then add the universal blocks last.

The argument that isn’t about money

I’ve spent this whole piece on cost because that was the objection. But the cost argument is not actually the strongest one.

Models get worse as context fills up.

Anthropic describes the mechanism plainly: transformers create “n² pairwise relationships for n tokens,” and every token you add competes for attention with every other token. They call the result context rot. Performance degrades as the window fills, and it degrades before you hit any hard limit.

Sit with what that means for a discovery-heavy build.

You open the session by dumping an enormous, mostly irrelevant description of a Figma file into context. Then you try to do careful, detailed work inside the remains of that window, with the model’s attention already spread across thousands of tokens of component tree it will never need again.

The discovery-heavy build is not just the more expensive way to produce the email. It’s the way that produces the worse email.

That’s the reason I’d keep the system even if tokens were free.

If you’re starting from nothing

The order that worked for me, in decreasing order of return:

1. Set up universal blocks in Klaviyo first. Header, footer, anything repeated. Costs nothing, saves work immediately, no AI involved.

2. Build the Figma components you use more than twice. Don’t try to anticipate everything. Let the third repetition tell you what deserves to be a component.

3. Write down what you learn the moment you learn it. Node IDs, property names, the thing that broke. This is the step that pays back most, and it feels like admin, which is why people skip it.

4. Record your failures explicitly. “Don’t read component X, it hangs” is worth more than most of the positive instructions in my file.

5. Then let the model work from the document, not from the file.

Here’s the skeleton, stripped of anything client-specific. Steal it.

# [Client] Email Build

## Preflight
- Where the brief comes from; what to take from it, what to ignore
- How to confirm the right file is open before doing anything
- Where new frames go on the canvas

## Campaign type to clone source
| Campaign type   | Frame to clone   |
|-----------------|------------------|
| Product roundup | [node id]        |
| Sale / promo    | [node id]        |
| Testimonial     | [node id]        |

## Component map
| Component | Master ID | Property keys | Known issues |

## Data truth
- Where prices, stock, and URLs get verified
- Claims that are banned in copy

## Execution rules
- Writes, not reads
- One concern per call
- Verify with a screenshot, never with a read

## QA checklist
- [ ] Brand tokens correct
- [ ] Every link verified live
- [ ] No leftover template copy

Five headings. That’s it. Mine grew to 4,000 tokens over several months of client work, one hard-won line at a time.

I didn’t build any of this to save tokens. I built it so that no campaign would start from nothing, and so that the same email would come out the same way twice.

The token part turned out to be a side effect of the same decision.

Found this useful? Subscribe for free, and forward it to whoever on your team is about to learn this the expensive way.

Subscribe now

Used together they do more than fill a calendar. They keep you visible, remove friction, reward the people who stay, and keep the list healthy enough to sell to when it matters.

Every example in this post is live client work, built in Klaviyo.

Stay visible

1. Content emails

A content email turns work you’ve already produced into a campaign.

It’s the easiest slot in the calendar to fill. Lead with your strongest recent post, keep the list short, and send the traffic back to the site.

The right layout depends on how much you publish. A brand posting weekly needs a different structure than one posting twice a year.

2. Follow us on socials

Social gives you a way to stay present between sends, and a second route to the same customer if the inbox goes quiet.

The ask works when you tell people what they’ll actually get there. Behind the scenes, community, first look. Not just a row of icons.

These examples all lead with the reason to follow, then the icons.

3. SMS sign-up

Your email list is the best place to build your SMS list. The audience is already engaged and already trusts you.

The ask works when the incentive is genuinely SMS only. Early access, a drop, or a code they can’t get anywhere else.

Every example here makes the keyword impossible to miss. That’s the whole design job.

Remove friction

4. AfterPay, Klarna, Sezzle

Buy now, pay later is already on your site. An email explaining how it works turns it into a reason to buy.

It builds confidence before checkout and answers the question your support inbox keeps getting.

Every version here answers the same thing: what happens after I click?

5. Testimonial emails

You’ve already earned the reviews. A testimonial email puts them in front of the people who haven’t reached your product pages yet.

It answers hesitation in a customer’s voice rather than your own, which is the version people believe.

Pick the review that names the hesitation, not the one with the most stars.

Reward

6. Birthday emails

Birthday campaigns are the most personal send in the calendar, and one of the few customers look forward to.

The work is in the capture. A preference center or a birthday club invite gets you the date plus everything else worth knowing, without slowing down signup.

That’s what these are really doing. The gift is the reason to fill in the form.

7. Loyalty

Loyalty emails work hardest when the reward changes with the tier.

Look at the two versions here. Same offer, same design, different multiplier, sent to different member levels. The email does the segmenting.

Points balance, ways to earn, and what the points are actually worth. Show all three or the program stays theoretical.

Advocate

8. Ambassador emails

Your best customers are already recommending you. An ambassador email gives them a reason to do it publicly.

Be specific about the exchange. What they get, what you’re asking for, and how to start.

These all lead with the invitation rather than the application form. The ask should feel like a compliment.

Keep the list healthy

9. Manage preferences

A preference email is the cheapest alternative to an unsubscribe.

Most people who want out want less, not nothing. Give them frequency and topic controls and a share of them stay.

It also gives you the data to send better, which is the part most brands skip.

10. List cleaning

A smaller engaged list outperforms a large quiet one. Sunsetting subscribers who stopped opening protects your sender reputation and your inbox placement.

Send one last email first. Ask them to stay, give them a reason, and let the people who mean it opt back in.

Two of these put the unsubscribe button and the discount side by side. That’s the honest version, and it works.

How many of the ten are live on your list? Three or four is normal. It’s also the fastest gap to close, because none of these depend on a launch or a season. They can be built this month and run for years.

I publish these systems as I build them, out of real client work. Subscribe for free and you’ll get the next one.

Subscribe now

Last time I wrote about how Claude builds my Klaviyo emails, and I said the whole thing has a prerequisite: the Figma file has to be built from components, not loose layers. I left it there. This is the part I skipped.

Start with a question. If you wanted to change the body font across a brand’s emails, how long would that take?

In most Figma files the answer is that you open every email and change it one at a time, and you miss two. In a file built properly the answer is that you change one thing.

That gap is what a design system is.

What it actually is

A design system is the set of decisions made once and stored somewhere the file itself can reach.

Tokens are named decisions. Not a hex code sitting in a fill, but a name like text/primary that every heading points at. Components are the reusable pieces, built once with defined variants instead of copied and drifted. Rules are the constraints written into the components themselves, so the wrong choice isn’t available rather than merely discouraged.

Most brands have a brand guide and believe that covers it. A brand guide describes the rules in a PDF. A design system makes them the easiest available option. The difference isn’t documentation. It’s enforcement.

What it’s actually worth

Four things, in the order you’ll notice them.

Speed comes first. The one properly trained designer I’ve worked with who built systems produced an email in about a third of the time anyone else needed, because she was assembling rather than deciding. That compounds fast when your business is sending emails every week.

Maintenance comes second, and it’s the font question above. Every uncontrolled decision is a future job.

Consistency comes third, and it’s the one clients feel without being able to name it. A subscriber should recognize an email before they read the sender name, and recognition is built from repetition, which only exists if the pieces repeat.

Accessibility comes fourth, and it’s the one that actually convinced me. An eyebrow style in one of my component sets was rendering a soft brand color at 11px on white. It failed contrast across all eight variants of that component, and I hadn’t noticed for months. I rebound it once and every email built afterward inherited the fix.

The emails already sent stay broken. Email is the one medium where you only ever get to fix forward, which is exactly why the fix has to live in the component and not in a reviewer’s attention.

Why it stopped being optional

For about ten years none of this was necessary, and the workflow explains why. A designer built the email in Figma. Then someone sliced it, or an implementer rebuilt it in Klaviyo by eye. A person can look at a flat design and reproduce it. Components were never required for that handoff to work.

What changed is that Claude now does the designing. It isn’t looking at anything. It assembles from whatever the file actually contains, and if the file contains loose layers there is nothing to assemble from, so it invents.

I found that out the slow way, by pointing Claude at a file full of loose layers and getting back emails with colors I never chose. I assumed the model was the problem. The file was the problem.

So here is the order I build in now. The order matters more than people expect, because each step makes the next one cheaper, and doing them out of sequence means redoing work.

Start with what you already sent

Before you build anything, go and look at the last three months of emails for the brand.

Screenshot every button. Put them side by side on a single Figma page. Do the same for headings, then for product blocks.

You will find eleven buttons. Slightly different greens, three corner radii, four font sizes, two of them with shadows that nobody remembers adding. This is called an interface inventory, and it comes from Brad Frost, who put it more plainly than I can: you don’t need to be a designer to recognize that having 37 unique button styles probably isn’t a good idea.

Do this first for two reasons. It tells you what components you actually need rather than what you imagine you need. And when a client asks why they should pay for this, the inventory is the argument. It is very hard to look at eleven buttons and claim everything is fine.

Tokens before components

A token is a named decision. Not a hex code sitting in a fill, but a name that points to the hex code, which every component then points at.

Build these before you build a single component, because components should reference tokens and retrofitting that later means opening every component again.

You need three groups to start.

Color. Text colors, surface colors, border colors, accents.

Type. A real scale with real sizes. Display sizes for headings, body sizes, a caption size, a legal size. The point of a scale is that it forecloses argument. Nobody hand-sets 34px because it felt right that morning, because 34 isn’t on the scale.

Spacing and layout. Frame width, side gutters, the vertical rhythm between sections, image aspect ratios.

That last group is the one people skip, and it’s the one that makes emails feel like they belong together even when the content is completely different.

Name things for what they do, not what they look like

This is the single decision that determines whether the system survives a rebrand.

If you name a color brand-navy, you have encoded the appearance. When the brand moves to charcoal next year, you either rename the token everywhere or live with a token called navy that renders charcoal.

If you name it text/primary, you have encoded the job. Changing what primary means updates every heading in every email at once, and the name stays true.

The convention that has settled across the field is three tiers. A reference tier holds the literal values. A semantic tier names the jobs and points at the reference tier. Components point at the semantic tier and never at raw values.

In practice for email you can usually collapse this into two tiers and be fine. What you cannot do is skip the semantic layer, because that layer is the entire mechanism by which one change propagates.

Build two color ramps, not one

This is the most useful specific thing I can give you, and it is the fix for the eyebrow problem I described earlier.

Brand palettes are usually designed for packaging and social. They are full of soft, pretty tints. Then someone uses one of those tints for a small uppercase label on a white background, and it fails contrast badly. Not marginally. Around 2:1 when the accessible minimum is 4.5:1.

The fix is not to police it in review. The fix is to build the palette so it cannot happen. Two ramps.

One pastel ramp, for decoration only. Chips, tinted backgrounds, large numerals.

One darker ramp of the same hues, for text on light backgrounds. Same family, deep enough to pass.

Then bind every text layer in every component to the text ramp. The pretty version is still available for the jobs it’s good at, and it is structurally unavailable for the job it fails at.

There’s an honest limit here that the people who run large public design systems are careful about, and I’ll repeat it. A design system does not make things accessible. It converts a recurring judgment into a one-time engineering decision. Content, context, and real testing still have to happen. What the system does is shrink the surface where mistakes are possible.

Components, and the variants rule

Now build the pieces. The inventory told you which ones.

For most e-commerce brands the core set is smaller than people fear. A header. A hero. A section header. A product tile and a product grid. A feature row. A button, and a button block with its padding and micro-copy bundled. A divider. Trust callouts. A footer.

That’s maybe a dozen components covering most of what you send.

The rule that matters: use variants, not copies. If your hero can be full bleed, or have text above, or have text below, that is one component with three variants. It is not three components. The moment it’s three components, they drift, because someone will improve one and not the others.

Same for state. A free shipping bar that reads differently above and below the threshold is one component with two states.

Every component has to survive the trip into your ESP

This is the part that makes email different from product design, and it’s where systems built by web designers fall apart.

Your design system does not live in Klaviyo. It cannot. Klaviyo has universal content, which is the closest native equivalent, but it doesn’t nest, it unlinks automatically in transactional flows, and the template API cannot reference it. Anything built programmatically gets a detached copy.

So Figma holds the truth and Klaviyo receives output. Which means every component you design has to be expressible as something Klaviyo can actually build. If you design a component that has no clean equivalent in the drag and drop editor, you have designed a thing that will be rebuilt by hand every single time, and the system leaks there permanently.

Practically: know what your ESP’s blocks are before you finalize component structure. Design a component and its block equivalent together. When you get this right, a build becomes translation. When you get it wrong, it becomes reinterpretation, and reinterpretation is where inconsistency comes back in through the side door.

Naming is the interface

The least glamorous section and one of the most important.

Name your image slots consistently, including the intended aspect ratio. Name your frames with a convention that includes date, campaign and version. Number your sections in visual order.

None of this matters when a human is reading the file, because a human can see what’s a hero and what’s a footer. It matters enormously when anything else reads the file, because names are the only labels it has. A file where every layer is called Rectangle 47 is a file that has to be guessed at.

Keep it alive

A design system that nobody maintains becomes documentation, and documentation gets ignored.

Two habits are enough for a small operation.

Keep a written log of component-level issues and what you did about them. Not a general to-do list. Specifically: what was wrong, in which component, and what changed. When a system spans months and clients, this is the only thing that stops you rediscovering the same problem twice.

And decide in advance what happens when the documentation and the built component disagree. I got this wrong once. A spec said a primary button should be black with a two-pixel radius. The built component was gray with a five-pixel radius. I assumed the spec was right and nearly corrected a component that was correct. The rule I use now is that when the document and the build disagree, you ask, you don’t auto-correct. The build often contains a decision that never made it back into the doc.

What Claude does, and what you decide

Claude can build the component library. It can set it up from an existing brand, extend it as your template library grows, and rebuild components when the system changes. That part is genuinely no longer manual work.

What it can’t do is decide what good looks like for this brand. Which grays are safe. Whether the hero should carry text or sit clean. What the brand’s rhythm is. Those are judgments, they’re specific to a brand, and they’re the part that stays yours.

Which is the actual answer to the question designers keep asking about all this. The production work is going. The system design is not, and it was always the more valuable half. It just wasn’t the half anyone was paying for.

I publish these as I build them, out of real client work. Subscribe for free and you’ll get the next one.

Subscribe now

I had connected Claude to my Figma designs and told it to build them in Klaviyo. Simple idea. Every email came out different. Odd colors, free designs, elements I never put there. It got creative on my behalf, and creativity is the last thing you want in email production.

I did this long enough to know the problem wasn’t the model. The problem was me. Nothing in my setup told Claude how my design translates into a Klaviyo template, so it guessed. Anything that guesses will eventually guess wrong.

This post is the system I built to make it stop guessing. It now produces finished Klaviyo templates, real drag-and-drop templates with live text, in minutes per email.

If you’re new here: I teach e-commerce operators how to run their marketing operations on Claude. Subscribe for free and you’ll get every system I build.

The fix: components equal blocks

The unlock was a mapping, not a prompt.

Every component in my Figma library corresponds to a specific block in the Klaviyo editor. Hero component, hero block. Product row component, product row block. When Claude knows exactly how each component translates, there is nothing left to interpret. The creativity stopped and the consistency started.

This has a hard prerequisite most Figma files fail: your emails have to be built from components, not loose elements. I said this to an agency team I was training, and I’ll repeat it here: open your Figma file and look. If your designs are separate text boxes, objects and images grouped to look like an email, no system can read them reliably. Componentize first. That is the biggest unlock, and it costs a designer a few days once.

Around the mapping sits a small amount of structure. Each client gets one folder tree: Brand, Klaviyo, Figma, campaigns, reports, reference. Each folder has its own instructions, and there is always a CLAUDE.md file that tells Claude what to do in that context. Design tokens live with the design system. Instructions alone are not a system. The tokens, the skills and the reference docs have to live where the work happens.

The backbone: Asana holds the truth

The second half of the system has nothing to do with design. It’s about where information lives.

Every campaign is an Asana task, and the task holds everything: the copy, the segment, the send time, inclusions and exclusions, links to the products. When I ran a team, every send also lived on one marketing calendar view. An open task meant an email not yet scheduled. When everything was closed by end of day, I knew every campaign for every client was set up, and I stopped checking.

Before the copy exists, there’s a brief. This is the stage most teams skip. I watched a copywriter go straight from campaign idea to finished subject lines in one chat, and the team couldn’t figure out why the output felt off. Nothing was wrong with the prompt. The missing piece was the stage where the campaign gets figured out: what this send is, who gets it, what the offer is. Brief feeds copy, copy feeds the task, the task feeds the build.

One line I add to every brief prompt: ask me questions if you need any more information. Claude guesses when you leave gaps. It asks when you tell it to.

Know an email marketer still building campaigns by hand? Share this with them.

The build: one command, two links

My production month has a shape.

I spend about a week designing everything in Figma. All the campaigns, refined until I’m sure. Then I sit down for one build session and paste the same slash command over and over. Each time it gets two links: the Figma frame and the Asana task. That’s the entire input.

The first email of a session takes about 10 minutes, because Claude reads through the skills, the tokens and the documentation before it touches anything. Every email after that builds in minutes, because the context is already loaded. This is why I batch. One email here, one email there pays the warm-up cost every single time.

Two reliability rules I learned the hard way. Feed it one campaign at a time; give Claude five at once and it starts getting sloppy and missing things. And for flows, strategy comes first: I have Claude lay the flow out as a chart in Figma, a map you can look at and argue with, before anything gets built through the API. The build is the cheap part now. Knowing exactly what you meant to build is still the work.

What lands in Klaviyo

This is the part people don’t believe until they see it.

The template that lands in Klaviyo is a real drag-and-drop template built from live text blocks. Not JPEG slices. Not one big image pretending to be an email. Live text, editable blocks, the same template a careful human would build.

And it arrives complete: alt tags on every image, links in place, subject line and preview text already written from the Asana brief. Corrections work the same way as builds. I tell Claude what to fix, and it goes and fixes it.

I still go in and polish. Padding, spacing, the last few details. It’s never absolutely perfect, and I’ve stopped expecting that. What it is, is structurally complete, with all the error-prone busywork already done.

Slicing was never the bottleneck

An agency owner pushed back on me: slicing an email into a template is the most basic function there is, why complicate it with AI.

He was right that slicing is easy. But slicing was never where the time went. The time goes into everything around it: the alt tags, the links, cloning the campaign, renaming it, assigning segments, setting inclusions and exclusions, scheduling the send. Multiply by every email on the calendar, for every client. That’s the part worth automating, and it’s all information the Asana task already holds.

Which is the real reason I built this, and it isn’t speed, although the speed is real. It eliminates errors. Everything gets pulled from the source instead of retyped by a tired human at 6pm. The wrong link, the missing alt tag, the segment that didn’t get excluded. Those mistakes don’t survive a system that never retypes anything.

The odd colors were the price of not having a system. The system was the fix.

Everything in this post came out of real client work, and so will the next one. Subscribe for free if you want these systems as I build them.

But for most e-commerce operators, these frameworks add complexity without proportional benefit. This lesson covers simpler approaches that keep you in control.

The Framework Temptation

Frameworks are tempting because they promise to solve coordination problems automatically. Define your agents, specify their relationships, let the framework handle the rest.

The reality:

• Learning curve. Every framework has its own concepts, syntax, and quirks. Time spent learning the framework is time not spent building your actual system.

• Abstraction costs. Frameworks abstract away details. Sometimes those details matter. When something breaks, you’re debugging both your logic AND the framework.

• Changing landscape. AI tooling evolves rapidly. Today’s hot framework might be tomorrow’s abandoned project. Building on shifting foundations is risky.

• Overkill for most uses. If you’re coordinating 2-4 agents in a Claude.ai workflow, you don’t need industrial-strength orchestration.

Manual Orchestration: You as the Router

The simplest orchestration pattern: you do it.

You have multiple Claude Projects, each specialized for a role. You move information between them. You decide when to proceed. You handle exceptions.

This works because:

• You understand the workflow. You know what should happen next. You know what success looks like at each stage.

• You can handle exceptions. When something unexpected happens, you can adapt. No framework anticipates every edge case.

• You maintain quality control. Each handoff is an opportunity to review. You catch problems before they propagate.

• The overhead is manageable. Copy-pasting handoffs between projects takes seconds. It’s not a bottleneck for workflows with 2-5 steps.

The workflow:

1. Start task with appropriate specialist agent

2. Review output

3. If satisfactory, copy handoff data to next agent

4. If not satisfactory, iterate with current agent

5. Repeat until workflow complete

It’s not automated. But automation isn’t always the goal. Sometimes control and quality matter more than speed.

Claude as Its Own Coordinator: The Meta-Agent Pattern

The Meta-Agent Pattern

Here’s a pattern that helps with complex workflows: use Claude itself as a planning layer.

Create a “meta-agent” — a Claude project whose job is to coordinate other agents. It doesn’t do the work itself; it decides what work needs to happen and in what order.

The meta-agent’s system prompt:

ROLE

You are a workflow coordinator. You receive high-level tasks and decompose them into specialist subtasks. You specify what each specialist should do and what information they need.

AVAILABLE SPECIALISTS

Copywriter: Creates email copy given a brief

Analyst: Analyzes data and produces insights

PM: Creates tasks and manages timelines

Builder: Implements in Klaviyo

TASK

When given a request, produce a coordination plan. For each step, specify: (1) Which specialist; (2) What inputs they need; (3) What output is expected; (4) What quality criteria apply; (5) Dependencies on other steps.

How it works:

You bring a complex task to the meta-agent: “Create January email campaign calendar with copy for the first two campaigns.”

The meta-agent produces a plan:

Step 1 — Analyst: Review last year’s January performance to identify winning themes. Input: January campaign data. Output: Theme recommendations.

Step 2 — PM: Create January calendar structure with key dates and campaigns. Input: January dates, theme recommendations. Output: Calendar framework.

Step 3 — Copywriter: Write copy for January campaigns. Input: Calendar framework, theme recommendations, brand voice guide. Output: Draft copy for 2 campaigns.

Step 4: Human review of copy, then iterate or proceed.

Important: Planning vs. Execution

In Claude.ai, the meta-agent produces a plan — it doesn’t execute it.

You’re still the coordinator. You take the meta-agent’s plan and manually move between specialist projects, providing each one with the inputs specified, reviewing outputs, and proceeding to the next step. There’s no automated handoff between agents. No agent talks directly to another agent.

The meta-agent makes you a better orchestrator by giving you a systematic breakdown of complex workflows. It handles the cognitive load of decomposition so you can focus on execution and quality control. But you remain the routing layer.

This is different from code-based environments. Tools like Claude Code can programmatically chain Claude calls together — one script calling Claude multiple times, passing outputs between calls automatically. That’s real automated orchestration. In Claude.ai’s chat interface, you don’t have that capability. The human stays in the loop at every handoff.

The benefits of the meta-agent pattern:

Complex tasks get broken down systematically — Claude thinks through dependencies and sequencing you might miss

Quality criteria are defined upfront for each step

You get a reusable template for similar future workflows

You still maintain full control of execution and can adapt as needed

Think of it this way: the meta-agent produces the blueprint, you act as the general contractor executing it. Not as magical as automated orchestration, but genuinely useful for complex workflows where you’d otherwise be figuring out the sequence on the fly.

Building Your Orchestration Muscle

Start with manual orchestration. Get comfortable moving information between specialized agents. Understand what makes handoffs work.

Then try the meta-agent pattern. See if Claude can help you plan complex workflows. Experience the benefits and limitations.

Only after you’ve hit real limits — scale demands you can’t meet, complexity you can’t track — should you consider frameworks. And when you do, you’ll know exactly what problems you’re solving and can evaluate frameworks against your specific needs.

The goal isn’t to avoid frameworks forever. It’s to avoid adopting complexity before you need it. Let your requirements drive your architecture, not the reverse.

Module 8 Summary

Multi-agent systems extend what’s possible with Claude. When single agents hit limits — context saturation, expertise dilution, quality degradation — splitting work across specialized agents can produce better results.

Key patterns:

• Sequential handoffs for workflows where each step feeds the next

• Parallel processing for independent analyses that combine in synthesis

• Manual orchestration for control and quality

• Meta-agent coordination for complex workflow planning

Key principles:

• Don’t go multi-agent until single-agent truly fails

• Design clean handoffs with explicit information transfer

• Build quality gates between agents

• Handle errors explicitly at each stage

• Keep orchestration as simple as your requirements allow

Multi-agent architecture is a tool for when you need it, not a default approach. Use it when it earns its complexity.

--- End of Module 8 ---

What’s Next: Module 9 moves from architecture to application. You understand single agents and multi-agent systems. Now we build real e-commerce solutions: audit systems, content pipelines, client communication automation, and competitive intelligence gathering. Theory becomes practice.

Found this content informative? Like this post, leave a comment and share with others. Help me gain wider reach.

Leave a comment

This lesson covers when parallel processing makes sense and how to design the synthesis step that combines parallel outputs.

When Agents Can Work Simultaneously

Parallel processing works when tasks are independent — when Agent A’s output doesn’t depend on Agent B’s output, and vice versa.

Good candidates for parallelization:

• Research from different sources. One agent researches competitors, another researches industry trends, another researches customer sentiment. None depends on the others.

• Analysis of different dimensions. One agent analyzes flow performance, another analyzes campaign performance, another analyzes list health. Each looks at different data.

• Processing of different inputs. One agent processes Shopify data, another processes Klaviyo data, another processes GA4 data. Different systems, different contexts.

• Creation of different components. One agent writes subject lines, another writes body copy, another writes CTAs. Independent creative tasks.

Bad candidates for parallelization:

• Dependent analysis. If Agent B needs Agent A’s findings to do its work, they must be sequential.

• Iterative refinement. If the output of one step shapes the next step, parallelization doesn’t help.

• Shared context requirements. If agents need to coordinate mid-task, parallel execution creates complexity without benefit.

  Thanks for reading Kinga | Claude AI for Ecommerce! Subscribe for free to receive new posts and support my work.

Case Study: Parallel Klaviyo Audit

Here’s a real example: a comprehensive Klaviyo audit using parallel agents.

The problem: A complete Klaviyo audit covers flows, campaigns, list health, and segmentation. Each is a substantial analysis. Putting it all in one agent means a bloated context and diluted expertise.

The architecture:

Agent A: Flow Analyst

• Input: Flow exports, benchmark data

• Task: Analyze each flow’s performance, identify issues, estimate revenue impact

• Output: Flow-by-flow assessment with prioritized recommendations

Agent B: Campaign Analyst

• Input: Campaign history export, performance data

• Task: Identify patterns, compare segment performance, analyze creative effectiveness

• Output: Campaign performance assessment with trend insights

Agent C: List Health Analyst

• Input: List metrics, deliverability data, growth/churn numbers

• Task: Assess list quality, identify hygiene issues, evaluate growth sources

• Output: List health report with cleanup recommendations

Agent D: Segmentation Analyst

• Input: Segment definitions, usage patterns, overlap analysis

• Task: Evaluate segmentation strategy, identify gaps, suggest improvements

• Output: Segmentation assessment with strategic recommendations

Agent E: Synthesis Agent

• Input: Outputs from Agents A, B, C, and D

• Task: Combine findings, identify cross-cutting themes, prioritize overall

• Output: Unified audit report with executive summary and prioritized roadmap

Agents A, B, C, and D run in parallel — you can literally run them simultaneously in different browser tabs. Agent E runs after all four complete, combining their outputs.

The Synthesis Step

The synthesis agent is the critical component in parallel architectures. It takes multiple independent analyses and produces a coherent whole.

What synthesis requires:

Cross-cutting analysis. The Flow Analyst might identify that abandoned cart flows are underperforming. The Campaign Analyst might notice that campaigns targeting cart abandoners also underperform. The Synthesis Agent connects these: “There may be a fundamental issue with how we’re approaching cart abandonment across both flows and campaigns.”

Priority reconciliation. Each specialist agent produces its own priorities. The Flow Analyst says “fix the welcome series first.” The Campaign Analyst says “improve segmentation targeting first.” The Synthesis Agent weighs these against overall business goals and produces a unified priority list.

Conflict resolution. Sometimes parallel agents produce contradictory findings. The Synthesis Agent identifies these conflicts and either reconciles them or flags them for human resolution.

Narrative construction. Four separate reports don’t make a coherent audit. The Synthesis Agent constructs the story: what’s the overall state, what are the biggest opportunities, what’s the recommended path forward.

Designing the Synthesis Agent

The Synthesis Agent needs a different kind of system prompt than the specialist agents. Here’s the key structure:

ROLE

You are a senior strategist synthesizing specialist analyses into unified recommendations. You receive detailed findings from multiple analysts and produce coherent, prioritized strategic guidance.

CONTEXT

You’re producing the final deliverable for a Klaviyo audit. You’ll receive reports from four specialists: Flow Analyst, Campaign Analyst, List Health Analyst, and Segmentation Analyst. Your job is to combine their findings into an actionable audit report.

TASK

1. Read all four specialist reports

2. Identify cross-cutting themes and connections between findings

3. Reconcile priorities across specialists into a unified prioritization

4. Flag any conflicts or contradictions that need human review

5. Produce a unified audit report with executive summary and prioritized roadmap

OUTPUT FORMAT

1. Executive Summary: 3-4 paragraphs on overall state and key findings

2. Cross-Cutting Themes: Issues that span multiple areas

3. Prioritized Recommendations: Unified list with rationale

4. Quick Wins: High-impact, low-effort items

5. Strategic Initiatives: Larger projects requiring planning

6. Appendix: Detailed specialist findings for reference

Practical Execution

How do you actually run parallel agents in Claude.ai?

Option 1: Multiple browser tabs

Open four tabs, each with a different specialist project. Start all four analyses. Work on other things while they process. Collect outputs when done.

This works. It’s manual but effective. You can literally run agents in parallel.

Option 2: Sequential with fresh context

Run each specialist sequentially but treat them as parallel logically. Each runs in a fresh conversation with its own focused context. The order doesn’t matter since they’re independent.

This is simpler to manage and achieves the same result — four independent analyses ready for synthesis.

The synthesis step

Once all specialist outputs are ready, start a fresh conversation with the Synthesis Agent. Paste all four reports (or use artifacts to reference them). Let the Synthesis Agent do its work.

The key insight: parallel architecture is about independence of analysis, not necessarily simultaneous execution. You get the benefits (specialized depth, fresh context for each) whether you literally run them at the same time or not.

When Parallel Beats Sequential

Use parallel when:

• Analyses are genuinely independent

• Each analysis benefits from specialized depth

• Combined context would exceed useful limits

• A synthesis step can meaningfully combine outputs

Use sequential when:

• Each step depends on the previous step’s output

• Shared context is necessary for coherence

• The workflow has natural progression

• Quality gates need to stop bad work from proceeding

Many real workflows combine both: parallel analysis followed by sequential implementation. The audit example uses parallel analysis but would use sequential execution for implementing the recommendations.

Next lesson: Orchestration Without Frameworks — how to coordinate multi-agent systems without external tools.

Found this content informative? Like this post, leave a comment and share with others. Help me gain wider reach.

Leave a comment

This lesson covers how to design these handoffs well — what information passes, how to format it, where to build quality gates, and how to handle failures.

The Pipeline Pattern

Sequential handoffs work like an assembly line. Each agent is a specialized station. Raw materials enter, each station does its work, finished product exits.

The key insight: each agent should do one thing well and produce clean output for the next station. If you find an agent doing too much, it probably should be two agents.

Case Study: 3-Agent Email Marketing System

Let’s make this concrete. Here’s a real workflow for producing email marketing campaigns:

Agent 1: The Copywriter

• Input: Campaign brief, brand voice guidelines, product information, target segment description

• Task: Write compelling email copy that matches brand voice and speaks to the target segment

• Output: Draft email copy including subject line, preview text, body, and CTA

The Copywriter agent is optimized for creative writing. Its system prompt establishes deep expertise in email copywriting, understanding of persuasion, and the specific brand’s voice. It doesn’t know or care about project management or technical implementation.

Agent 2: The Project Manager

• Input: Approved email copy, campaign timeline, team assignments

• Task: Create actionable tasks with clear owners, deadlines, and dependencies

• Output: Structured task list (created in Asana via MCP) with timeline

The PM agent is optimized for operational thinking. Its system prompt establishes expertise in project coordination, task decomposition, and timeline management. It doesn’t write copy — it takes approved copy and turns it into a work plan.

Agent 3: The Klaviyo Builder

• Input: Final approved copy, segment criteria, send timing

• Task: Configure the campaign in Klaviyo with correct settings

• Output: Configured campaign ready for final review and scheduling

The Builder agent is optimized for technical implementation. Its system prompt establishes deep Klaviyo expertise — segments, templates, send settings, compliance. It takes creative assets and operational decisions and turns them into a working campaign.

Designing the Handoff

The handoff is where multi-agent systems succeed or fail. Bad handoffs create confusion, lost information, and compounding errors. Good handoffs are clean, complete, and unambiguous.

What information passes

Each handoff should include exactly what the next agent needs — no more, no less.

Copywriter → Project Manager:

• Final approved copy (the actual text)

• Any notes on variations or personalization needed

• Confirmation of brand alignment

• NOT needed: creative process, rejected drafts, stylistic debates

Project Manager → Klaviyo Builder:

• Final copy (unchanged)

• Target segment criteria

• Send timing and scheduling requirements

• Any A/B test parameters

• NOT needed: task management details, timeline discussions, who approved what

How to format handoffs

Structure your handoff data consistently. The receiving agent should know exactly where to find each piece of information.

A handoff template for the email system might look like:

HANDOFF: Copywriter to Project Manager

Campaign: [Campaign name]

Status: Copy approved

Subject Line: [Subject]

Preview Text: [Preview]

Body Copy: [Full email body]

CTA: [Call to action]

Notes: [Any implementation notes]

This structure is predictable. The receiving agent’s system prompt can specify exactly how to parse it.

Quality Gates

Quality gates are checkpoints between agents where you verify the work before it moves forward. They’re one of the main advantages of multi-agent architecture.

Between Copywriter and PM:

• Is the copy on-brand?

• Does it address the target segment appropriately?

• Is the CTA clear and compelling?

• Are there any compliance concerns?

Between PM and Builder:

• Is the segment definition clear and achievable?

• Is the timing appropriate?

• Are all required elements present?

• Has final approval been granted?

Quality gates can be human (you review and approve) or automated (the next agent checks prerequisites before proceeding). For important work, human gates are safer. For routine work, automated gates are faster.

Error Handling in Pipelines

What happens when something goes wrong? Each failure mode needs a response.

Upstream failure: The Copywriter doesn’t produce usable copy. The PM agent shouldn’t try to proceed with incomplete input. Build in checks: “If copy is missing required elements, flag for human review rather than proceeding.”

Handoff failure: The handoff data is malformed or incomplete. The receiving agent should recognize this and report the specific problem rather than guessing. “Handoff missing segment criteria. Cannot proceed. Please provide segment definition.”

Tool failure: The Builder agent can’t connect to Klaviyo. The workflow should pause and alert rather than proceeding with a partial result. Build explicit checks for tool availability.

Quality gate rejection: When a quality gate catches a problem, the workflow needs to route back appropriately. Copy problems go back to the Copywriter. Segment problems might stay with the PM.

The principle: fail explicitly, fail early, fail with information. Silent failures in pipelines compound into disasters.

Implementing the 3-Agent System

In practice, you implement this as three Claude Projects, each with specialized instructions:

Project 1: Email Copywriter

System prompt establishes the copywriter role, brand voice guidelines, target segment understanding, and output format requirements. Project knowledge includes brand voice docs, previous successful emails, and segment personas.

Project 2: Campaign Project Manager

System prompt establishes the PM role, task breakdown methodology, timeline management approach, and Asana MCP integration. Project knowledge includes team capacity docs, standard timelines, and task templates.

Project 3: Klaviyo Builder

System prompt establishes the technical implementation role, Klaviyo expertise, and campaign configuration standards. Project knowledge includes Klaviyo setup guides, segment definitions, and template library.

The flow:

1. You provide the campaign brief to the Copywriter project

2. Copywriter produces draft copy, you review and approve

3. You copy the handoff template with approved copy to the PM project

4. PM creates tasks, you review the task list

5. You copy the handoff template with implementation specs to the Builder project

6. Builder configures the campaign, you do final review

You’re the orchestrator, moving information between specialized agents. Each agent does what it’s best at. You maintain quality control at each transition.

Next lesson: Parallel Processing Patterns — when agents can work simultaneously rather than sequentially.

Found this content informative? Like this post, leave a comment and share with others. Help me gain wider reach.

Leave a comment

But some work can’t fit in one agent. The context is too large. The expertise is too varied. The workflow is too complex. When you hit these walls, the answer isn’t forcing a single agent to do more — it’s splitting the work across multiple agents that coordinate.

This lesson covers when that split makes sense and when it’s overengineering.

The Single-Agent Limit

Individual agents hit limits. Understanding those limits helps you recognize when multi-agent architecture becomes necessary.

Context window saturation. Even with 200K tokens, complex analysis can exhaust available space. A comprehensive Klaviyo audit might need: account data exports (flows, campaigns, segments), benchmark references, methodology documentation, conversation history as you iterate, and space for Claude’s response. Individually manageable, but together they crowd the context window to the point where Claude starts dropping threads.

Expertise dilution. A single system prompt can only establish so much expertise before it becomes unwieldy. An agent that’s supposed to be a Klaviyo analyst AND a copywriter AND a project manager will be mediocre at all three. Specialized agents do better than generalist agents at focused tasks.

Quality degradation under load. As you add more responsibilities to a single agent, quality drops across all tasks. The agent that produces excellent email copy might produce only adequate copy when it’s also managing timelines, checking inventory, and coordinating with other systems.

No natural checkpoints. With a single agent doing everything, there’s no built-in moment to review intermediate outputs. Errors compound. A mistake in analysis flows through to recommendations flows through to copy flows through to implementation. Multi-agent systems create natural breakpoints for quality control.

Decision Criteria for Multi-Agent Systems

Don’t reach for multi-agent architecture by default. It adds complexity. Use it when specific conditions justify that complexity.

The task requires genuinely different expertise or approaches.

Analysis and creation are different cognitive modes. A brilliant analyst isn’t necessarily a brilliant copywriter. If your workflow requires both, splitting them into specialized agents often produces better results than asking one agent to switch modes.

The same applies to research vs. synthesis, strategy vs. execution, creative vs. technical work. When the expertise is fundamentally different, separate agents make sense.

A single context window can’t hold everything needed.

If your task requires more context than fits in one conversation — multiple large documents, extensive reference materials, long histories — you have two choices: summarize aggressively (losing information) or split the work across agents (preserving information in each agent’s specialized context).

When information loss is unacceptable, multi-agent is the path.

Quality degrades when one agent juggles too many responsibilities.

This is the practical test. If your single-agent output is getting worse as you add more to its plate, that’s a signal. The agent that used to produce great recommendations now produces mediocre ones because it’s also managing three other concerns simultaneously.

When you notice this pattern, consider splitting rather than optimizing. Sometimes the right answer isn’t a better prompt — it’s a different architecture.

You need clear checkpoints and handoffs.

Some workflows benefit from built-in review points. Client work often requires approval before proceeding. Complex analysis benefits from human verification at intermediate stages.

Multi-agent systems create natural checkpoints at each handoff. Agent 1 completes its work, you review, then Agent 2 proceeds. This is harder to achieve with a monolithic agent that does everything in one pass.

When NOT to Use Multi-Agent

Multi-agent systems add complexity. That complexity has costs: more prompts to maintain, more handoffs to design, more failure points to manage. Don’t pay those costs without good reason.

When a single agent can do the job well. If your single-agent approach produces good results reliably, you don’t need to complicate it. “Could be multi-agent” isn’t a reason to make it multi-agent. “Must be multi-agent” is.

When the tasks are tightly coupled. If each step depends heavily on the full context of previous steps, splitting into agents means recreating context at every handoff. The overhead of context transfer might exceed the benefit of specialization.

When you haven’t optimized the single-agent approach first. Before going multi-agent, make sure you’ve actually pushed the single-agent approach. Better prompting, cleaner context management, smarter use of tools. Multi-agent shouldn’t be an escape from doing the hard work of prompt engineering.

When you can’t clearly define the handoffs. If you can’t articulate exactly what Agent 1 produces that Agent 2 needs, you’re not ready for multi-agent. Fuzzy handoffs create failure modes. The split should be clean and obvious.

The Complexity Budget

Think of your architecture decisions as spending from a complexity budget. You have limited capacity to manage complexity — prompts, handoffs, failure modes, maintenance.

Single agent: Low complexity. One prompt to maintain. No handoffs to design. Few failure modes. Easy to iterate and improve.

Two agents: Moderate complexity. Two prompts to maintain. One handoff to design. New failure modes (handoff failures, coordination failures). Still manageable.

Three+ agents: Higher complexity. Multiple prompts, multiple handoffs, exponentially more potential failure modes. Worth it only when the task genuinely requires it.

Spend your complexity budget where it pays off. A simple task made multi-agent is overengineered. A complex task forced into single-agent is underarchitected. Match the architecture to the actual requirements.

A Framework for the Decision

When evaluating whether to go multi-agent, ask:

1. Is my single-agent approach actually failing, or just underoptimized? If underoptimized, fix the prompts first.

2. Can I clearly define what each agent would do? If not, the split isn’t ready.

3. Can I clearly define what passes between agents? The handoff must be crisp.

4. Is the added complexity justified by better results? Complexity for its own sake is waste.

5. Can I maintain this system over time? More agents means more maintenance.

If you answer yes to all five, multi-agent is likely the right call. If you’re uncertain on any, try optimizing the single-agent approach further first.

Next lesson: Sequential Handoffs — when agents work in series, passing output from one to the next.

Found this content informative? Like this post, leave a comment and share with others. Help me gain wider reach.

Leave a comment

The Testing Mindset

Most people test agents like this: run a few examples, see if the output looks good, declare it done.

That’s not testing. That’s hoping.

Real testing is adversarial. You’re trying to break your agent. You’re actively looking for the inputs that produce bad outputs. Every failure you find in testing is a failure that won’t surprise you in production.

The goal isn’t to confirm your agent works. It’s to discover how it fails.

Test Cases: The 5-10 Scenarios Your Agent Must Handle

Every agent has core scenarios — the situations it will encounter most often. Identify these first.

For the inbox triage agent:

1. Clear client request with specific ask

2. Prospect inquiry from unknown sender

3. Vendor cold outreach

4. Newsletter from subscribed source

5. Administrative notification (receipt, calendar)

6. Urgent request with deadline

7. Email thread (reply in ongoing conversation)

8. Batch of mixed email types

For the research agent:

1. Well-known brand with lots of public information

2. Smaller brand with limited public presence

3. Brand with active, visible email marketing

4. Brand with minimal email presence

5. Direct competitor in same category

6. Adjacent competitor in related category

Create actual test inputs for each scenario. Real emails, real competitor names. Test them systematically. Record results.

Edge Cases: The Weird Inputs That Break Things

Core scenarios are necessary but insufficient. You also need edge cases — the unusual inputs that reveal brittleness.

Types of edge cases to test:

Ambiguous inputs. An email that could reasonably be categorized two different ways. A competitor with multiple brands. What does the agent do when the right answer isn’t obvious?

Missing information. An email with no subject line. A competitor with almost no public information. How does the agent handle gaps?

Conflicting signals. An email that’s both urgent and from an unknown sender. A competitor making contradictory public statements. How does the agent resolve conflicts?

Extreme inputs. A very long email. A batch of 50 emails. A competitor you’ve never heard of. Does the agent scale?

Trick inputs. An email that looks like one category but is actually another. A marketing email disguised as a personal message. Does the agent see through surface patterns?

For each edge case, the question isn’t just “does the agent produce output?” It’s “does the agent handle this gracefully?” Graceful handling might mean correct categorization, or it might mean acknowledging uncertainty and flagging for human review.

Failure Modes: Understanding How and Why Agents Fail

When agents fail, they fail in predictable ways. Knowing the common failure modes helps you test for them.

Pattern matching gone wrong. The agent latches onto surface features and misses underlying meaning. It categorizes based on keywords rather than actual intent. Test: inputs where obvious keywords suggest the wrong category.

Instruction drift. Over long conversations or complex inputs, the agent forgets constraints. It stops following the output format. It loses the role. Test: long inputs, complex scenarios, multi-part tasks.

Confident errors. The agent produces wrong output with high confidence. No hedging, no uncertainty flags, just wrong. Test: inputs where the right answer is non-obvious and the agent might guess.

Scope creep. The agent tries to do more than asked, sometimes doing the extra work poorly. Test: inputs that could be interpreted broadly. Does the agent stay in scope?

Tool misuse. The agent uses tools when it shouldn’t, or doesn’t use them when it should. It searches when it should use existing knowledge. It calculates in its head when it should use code. Test: scenarios where correct tool choice matters.

The Feedback Loop: Using Failures to Improve

Every failure is a lesson. The question is how to learn from it.

Diagnose before fixing. When an agent fails, don’t immediately change the prompt. First, understand why it failed. Was the instruction unclear? Missing? Contradicted by something else? Was the failure predictable from the prompt, or surprising?

Make minimal changes. Fix the specific failure without breaking what was working. If the agent miscategorizes vendor emails, add clarification about vendor emails. Don’t rewrite the entire categorization section.

Test the fix specifically. After changing the prompt, re-run the failing case. Did it fix the problem? Then re-run some previously passing cases. Did you break anything?

Add to your test suite. Every failure that you fix becomes a test case. If the agent miscategorized a vendor email as a prospect inquiry, that email is now part of your permanent test suite. Future changes must pass it.

Versioning Your Prompts

As you iterate, prompts evolve. Keep track of what changes.

Simple versioning:

• v1.0: Initial prompt

• v1.1: Added explicit handling for [specific case]

• v1.2: Fixed output format for [issue]

• v2.0: Major restructure of [section]

What to track:

• What changed

• Why (what failure prompted the change)

• Test results after the change

This history is invaluable when something breaks. You can trace back to when it was working and understand what changed. You can revert if a “fix” made things worse.

Testing in Production

Even well-tested agents encounter new scenarios in production. Build in feedback mechanisms.

Quick feedback capture. When output is wrong, note it immediately. What was the input? What was the output? What should it have been? This takes 30 seconds and prevents the same failure from recurring.

Periodic review. Every week or two, review recent agent outputs. Look for patterns in errors. Are there new edge cases emerging? Is performance degrading in certain areas?

Continuous improvement. Use production feedback to drive iteration cycles. The agent gets better over time because you keep feeding failures back into improvements.

The Testing Checklist

Before deploying any agent:

1. Identify 5-10 core scenarios

2. Create real test inputs for each

3. Run all core scenarios, evaluate results

4. Identify 5-10 edge cases

5. Test edge cases, evaluate handling

6. Fix any failures, re-test

7. Document known limitations

8. Set up feedback capture for production use

This checklist ensures your agent is genuinely tested, not just tried. It’s the difference between “I ran it once and it seemed to work” and “I systematically verified it handles the scenarios it will encounter.”

--- End of Module 7 ---

What’s Next: Module 8 covers Multi-Agent Systems — when one agent isn’t enough. You’ll learn how to break complex work into multiple specialized agents, design handoffs between them, run parallel processes, and orchestrate systems that can tackle work too big for any single agent.

Found this content informative? Like this post, leave a comment and share with others. Help me gain wider reach.

Leave a comment

This agent does competitive intelligence — researching a competitor’s positioning, digital presence, and marketing approach. It’s a different goal, different tools, different output. But the development process is identical.

Step 1: Define the Goal

The problem: Clients ask “what are competitors doing?” Answering well requires research — checking websites, looking for press coverage, analyzing publicly available information. It takes time and the research goes stale.

The goal: An agent that researches a specified competitor and produces a structured report on their market positioning, digital presence, and marketing approach — including brand strategy, promotional patterns, notable tactics, and strategic observations.

Success criteria: Report covers the major aspects of a competitor’s public presence. Information is current (from web search). Observations are insightful, not just descriptive. Report is client-ready with minimal editing.

Step 2: Map Research Sources

What information can the agent actually access? This determines what’s possible.

Before anything else: make sure web search is toggled on. If it’s off, Claude works only from training data. For competitive intelligence, enable Research mode too — Claude will conduct multiple searches across different angles rather than one or two quick lookups. Research mode requires web search to be enabled.

Via web search and Research:

• Company website — homepage, product pages, about page (static HTML content)

• Press coverage, marketing blog analyses, and case studies

• Industry reports mentioning the competitor (summaries — full reports are often paywalled)

• Email examples on free archive sites like Really Good Emails

• Customer reviews on public platforms (Trustpilot, Google Reviews)

• The brand’s own blog or content about their approach

Not directly accessible:

• JavaScript-triggered popups, exit-intent overlays, or dynamic page elements (Claude fetches static HTML, it doesn’t browse like a human)

• Social media feeds (Claude can’t scroll Instagram or TikTok — only finds social content if it’s referenced in articles)

• Actual competitor emails (would need to subscribe and forward)

• Internal metrics — send frequency, open rates, conversion data

This scope check is critical. The agent can research publicly available and indexed information. It cannot browse dynamic content or access anything behind a login. The goal and output need to reflect what’s actually possible.

Step 3: Design Output Format

What should the report look like? Design the structure before writing prompts.

Competitive Intelligence Report

1. Company Overview: Who they are, market position, target customer.

2. Digital Presence and Website Strategy: What the site communicates — messaging, product presentation, trust signals, navigation.

3. Brand Positioning: How they position themselves — value propositions, pricing approach, key differentiators.

4. Marketing Approach: What’s discoverable about campaigns, promotional strategy, email presence (from archive sites), content marketing.

5. Notable Tactics: Anything distinctive — unique approaches, interesting techniques, partnerships.

6. Strategic Observations: Higher-level analysis — what’s working, apparent focus areas, opportunities they might be missing.

7. Information Gaps: What couldn’t be determined from public sources and how to fill those gaps.

8. Recommendations for Client: Specific takeaways — what to emulate, what to avoid, differentiation opportunities.

Step 4: Create the System Prompt

Assemble into a comprehensive system prompt.

——— SYSTEM PROMPT ———

ROLE

You are a competitive intelligence researcher specializing in e-commerce. Your job is to research competitors and produce actionable intelligence reports for DTC brands.

CONTEXT

The user is a consultant serving DTC e-commerce clients. Clients frequently want to understand what competitors are doing — their positioning, marketing, and where the opportunities are. Your research helps inform strategy and identify differentiation.

TASK

When given a competitor brand name (and optionally their website), research their public presence and produce a structured competitive intelligence report.

METHODOLOGY

1. Fetch the competitor’s homepage and key pages. Analyze messaging, product presentation, and visible trust signals.

2. Search for press coverage, marketing analyses, or case studies mentioning the brand.

3. Search email archive sites (Really Good Emails, Panoramata) for examples of their campaigns.

4. Search for customer reviews on public platforms.

5. Search for the brand’s own blog content about their approach.

6. Synthesize findings into the structured report.

OUTPUT FORMAT

Produce a report with sections: Company Overview, Digital Presence and Website Strategy, Brand Positioning, Marketing Approach, Notable Tactics, Strategic Observations, Information Gaps, Recommendations for Client. Each section should be 2-4 paragraphs with specific examples where available.

CONSTRAINTS

• Always cite sources — link to where you found information

• Distinguish between confirmed facts and inferences

• Do not claim to have seen popups, social feeds, or email inboxes unless you actually retrieved that content

• Note information gaps — what you couldn’t find

• If limited information is available, say so rather than padding the report

• Keep tone professional and objective — analysis, not opinion

• Make recommendations specific and actionable

QUALITY STANDARD

The report should be client-ready — professional formatting, clear writing, valuable insights. A consultant should be able to share this with a client with minimal editing.

——— END SYSTEM PROMPT ———

Step 5: Test with a Real Competitor

Don’t test with a fake company. Pick a real competitor from a client’s space. Run the research.

Example prompt: “Research the competitive positioning and marketing approach for [Real Competitor Brand]. Their website is [competitor.com].” Then evaluate the output.

What to evaluate:

• Did it actually search? Check for citations. No citations usually means web search was off.

• Is the information current and accurate?

• Are all sections substantive, or are some thin?

• Are observations specific to this competitor, or generic best practices with their name attached?

• Did the agent claim to have seen things it couldn’t access?

• Are recommendations specific and actionable?

• Would you actually send this to a client?

Step 6: Evaluate Completeness

Research agents have a specific failure mode: incomplete coverage. They might do great on one section and barely touch another.

Completeness checklist:

• Did it visit the competitor’s actual website?

• Did it search for external coverage and analysis?

• Did it check email archive sites?

• Are all report sections populated?

• Are there specific examples and citations?

• Does the Information Gaps section contain genuine observations?

If coverage is incomplete, strengthen the methodology section of your prompt. Make each research step more explicit. Also check whether Research mode was enabled — without it, Claude defaults to fewer searches and you’ll get thinner results.

Step 7: Iterate and Refine

Common issues with research agents and fixes:

Problem: Shallow research

Agent does one or two searches and calls it done. Fix: Add explicit instruction to “conduct at least [N] searches across different source types before synthesizing.” Confirm Research mode is enabled.

Problem: Missing citations

Claims without sources. Fix: Add “Every factual claim must include a source link. If you can’t cite it, don’t include it.”

Problem: Generic observations

“They have a strong online presence.” Useless. Fix: Add “Observations must be specific. Instead of ‘they have good branding,’ say ‘their homepage leads with heritage storytelling before showing products, positioning craftsmanship over price.’”

Problem: Fabricated claims about things Claude can’t see

The most dangerous research agent failure. The agent describes social feeds it never accessed or popups it can’t see. Fix: “Do not claim to have seen content unless you actually retrieved it.”

Problem: Padded content

When information is thin, agent fills with fluff. Fix: Add “If information is limited, say so clearly. A short, honest section is better than a long, padded one.”

The Research Agent Pattern

Research agents share common characteristics:

Explicit methodology. Research without structure produces inconsistent results. Define the research steps.

Source requirements. Mandate citations. No claims without evidence.

Completeness checks. Ensure all sources are consulted, all sections are covered.

Honesty about gaps. Better to acknowledge missing information than to fabricate or pad.

Apply this pattern to any research task: competitive analysis, industry benchmarking, trend research, market sizing.

Next lesson: Testing and Iteration — systematic approaches to making your agents better.

Found this content informative? Like this post, leave a comment and share with others. Help me gain wider reach.

Leave a comment

This lesson walks through building a complete agent from scratch. Not a toy example — a genuinely useful tool: an inbox triage agent that categorizes and prioritizes incoming emails, drafts responses where appropriate, and flags what needs your attention.

We’ll follow the development cycle: define, build, test, evaluate, iterate. By the end, you’ll have a working agent and — more importantly — a repeatable process for building your own.

Step 1: Define the Goal

Start with what you’re trying to accomplish. Be specific.

The problem: Email overload. You get dozens of messages daily — client requests, vendor inquiries, newsletters, administrative stuff, spam that made it through filters. Sorting through them, deciding what needs response, and actually responding takes hours.

The goal: An agent that processes incoming emails and produces: (1) categorization of each email by type and priority; (2) draft responses for routine emails; (3) clear flags for emails requiring your personal attention; (4) a summary that lets you quickly see what needs action.

Success criteria: Categories are accurate 90%+ of the time. Draft responses are usable with minimal editing 80%+ of the time. Nothing important is missed or miscategorized as low priority.

Step 2: Design the Classification Schema

Before writing any prompts, design your categories. This is domain knowledge — you know your inbox better than Claude does.

Categories (for an e-commerce consultant):

• Client Request: Active client asking for something — deliverable, meeting, information.

• Prospect Inquiry: Potential client expressing interest or asking questions.

• Vendor/Partner: Tool vendors, potential partners, collaboration requests.

• Administrative: Invoices, receipts, account notifications, scheduling confirmations.

• Newsletter/Content: Newsletters you’ve subscribed to, content updates, industry news.

• Marketing/Sales: Unsolicited sales pitches, cold outreach, promotional content.

• Personal: Non-work emails from friends, family, personal contacts.

Priority levels:

• Urgent: Needs response today. Time-sensitive requests, deadlines, issues.

• High: Important but not time-critical. Respond within 24-48 hours.

• Normal: Standard priority. Handle in normal workflow.

• Low: Can wait. Newsletters, FYI items, non-urgent admin.

Response actions:

• Draft Response: Agent can draft a suitable reply.

• Needs Personal Response: Requires your personal attention, can’t be templated.

• No Response Needed: Newsletters, receipts, notifications — no reply required.

• Consider Unsubscribe: Marketing you keep ignoring, newsletters you never read.

Step 3: Write Response Templates

For emails that get draft responses, you need templates. These aren’t canned responses — they’re frameworks Claude will personalize.

Meeting request acknowledgment:

“Thanks for reaching out about [topic]. I’d be happy to find time to discuss. I’m generally available [standard availability window]. Would any of these times work for you? [suggest 2-3 options based on context]”

Simple information request:

“Thanks for your question about [topic]. [Direct answer]. Let me know if you need any additional detail.”

Vendor inquiry deferral:

“Thanks for reaching out. I’m not currently looking to change [tool/service type], but I’ll keep your information on file for when I’m next evaluating options.”

These templates guide Claude toward appropriate responses while allowing customization for specific situations.

Step 4: Create the System Prompt

Now we assemble everything into a system prompt. This goes in your Project instructions.

--- SYSTEM PROMPT ---

ROLE

You are an email triage assistant for an e-commerce consultant. Your job is to process incoming emails and provide categorization, prioritization, and draft responses where appropriate.

CONTEXT

The user runs a consulting business focused on email marketing and Klaviyo for DTC e-commerce brands. They receive emails from: active clients, prospective clients, tool vendors, partners, and various newsletters and marketing. Their time is valuable — the goal is to quickly surface what needs attention and handle routine correspondence efficiently.

TASK

When given one or more emails to process, for each email provide: (1) Category, (2) Priority level, (3) Recommended action, (4) Draft response if applicable, (5) Key points summary.

CATEGORIES

Client Request, Prospect Inquiry, Vendor/Partner, Administrative, Newsletter/Content, Marketing/Sales, Personal

PRIORITY LEVELS

Urgent (respond today), High (24-48 hours), Normal (standard workflow), Low (can wait)

ACTIONS

Draft Response, Needs Personal Response, No Response Needed, Consider Unsubscribe

CONSTRAINTS

• Never auto-respond to anything involving money, contracts, or commitments

• Flag anything ambiguous for personal review rather than guessing

• Client requests are always High priority minimum, Urgent if deadline mentioned

• When drafting responses, maintain professional but warm tone

• If context suggests an ongoing client relationship (references to past work, uses familiar tone, mentions specific projects), prioritize accordingly

OUTPUT FORMAT

For each email, output in this structure: FROM: [sender], SUBJECT: [subject line], CATEGORY: [category], PRIORITY: [level], ACTION: [recommended action], SUMMARY: [2-3 sentence summary of what this email is about and what it’s asking], DRAFT RESPONSE: [if applicable, otherwise “N/A”]

After processing all emails, provide: TRIAGE SUMMARY showing counts by category and priority, and ACTION ITEMS listing emails that need the user’s personal attention, sorted by priority.

--- END SYSTEM PROMPT ---

Enhancing with client context: This base prompt works for any email. To make it smarter about your specific clients, add a client list to your Project Knowledge — names, companies, domains. Then add to the constraints: “Refer to the client list in Project Knowledge to identify active clients.”

Step 5: Test with Real Emails

Now test. Not with made-up examples — with real emails from your inbox.

Create a new conversation in your Project. Paste in 5-10 recent emails (remove any sensitive information if needed). See what the agent produces.

What to evaluate:

• Are categories correct?

• Are priorities reasonable?

• Are draft responses usable?

• Is the summary accurate?

• Did it flag the right things for personal attention?

Take notes on what worked and what didn’t. Be specific — “the categorization was wrong” isn’t helpful. “It categorized a client request as Vendor/Partner because the client mentioned a tool” is something you can fix.

Step 6: Iterate on Edge Cases

Your first test will reveal problems. Here’s how to fix them.

Problem: Miscategorization

If the agent consistently miscategorizes a certain type of email, add explicit guidance. “Emails from [domain] are client emails, not vendor emails.” Or add examples of tricky categorizations to the system prompt.

Problem: Wrong priority

If priority assessment is off, clarify your criteria. “Emails mentioning ‘urgent,’ ‘ASAP,’ or specific deadlines should be Urgent. Emails with questions but no timeline are Normal.”

Problem: Unusable draft responses

If drafts don’t match your voice or approach, add examples of good responses. Show the agent what you actually sound like when responding to different email types.

Problem: Missing important flags

If important emails are getting marked “No Response Needed,” tighten your constraints. “When in doubt about whether something needs a response, flag for personal review.”

After each round of fixes, test again. Run new emails through. See if the problems are resolved. Repeat until performance meets your success criteria.

Step 7: Document for Reuse

Once your agent works reliably, document it.

What this agent does:

Processes incoming emails, providing categorization, prioritization, and draft responses. Surfaces what needs personal attention.

How to use:

Paste emails (one or more) into a conversation. Include sender, subject, and body. Agent will process and return structured triage.

Known limitations:

• Can’t access email directly — requires copy/paste

• Doesn’t know your calendar — availability suggestions are generic

• May miscategorize emails from new senders

Version history:

• v1.0: Initial version

• v1.1: Added explicit priority for client emails

• v1.2: Improved draft response templates

This documentation helps you maintain the agent over time, and helps if you ever want to share or adapt it.

Looking Ahead: Adding Direct Inbox Access

This agent requires copying and pasting emails manually. That’s intentional for your first build — it keeps the focus on the agent pattern itself without adding integration complexity.

But remember Module 5? MCP connectors can give Claude direct access to your inbox. Gmail integration lets Claude read your emails without copy/paste. The system prompt stays almost identical; you’re just changing how emails reach the agent.

Once you’re comfortable with the agent-building pattern from this module, upgrading to MCP access is straightforward. The hard part — designing the classification schema, writing the system prompt, iterating on edge cases — you’ve already done.

The Pattern You Just Learned

This walkthrough demonstrated a repeatable pattern:

1. Define the goal precisely, including success criteria

2. Design the domain model (categories, actions, formats)

3. Create supporting elements (templates, examples)

4. Assemble into system prompt

5. Test with real data

6. Iterate based on failures

7. Document for maintenance

This pattern works for any agent. The specifics change — different goals, different categories, different outputs — but the process is the same.

Next lesson: Step-by-Step: Build a Research Agent — a different type of agent with different requirements, same development process.

Found this content informative? Like this post, leave a comment and share with others. Help me gain wider reach.

Leave a comment

Now we assemble.

This module is where theory becomes practice. You’ll build real agents that do real work. Not demos. Not toys. Operational tools that save hours every week.

But before we build, we need to understand what we’re building. What actually makes something an “agent” rather than just a conversation with Claude?

The Four Components

Every Claude agent has four essential components. Miss one, and you have something less than an agent — maybe a useful prompt, maybe a one-off workflow, but not a reliable system you can deploy and trust.

1. Goal

What the agent is trying to accomplish. Not vaguely — precisely. “Help with email marketing” isn’t a goal. “Analyze Klaviyo flow performance against benchmarks and produce a prioritized list of optimization recommendations” is a goal.

The goal defines success. Without it, you can’t know if the agent is working. You can’t improve it. You can’t trust it.

A well-defined goal answers: What output does this agent produce? What inputs does it need? What does “done” look like? How will I know if the output is good?

2. Tools

What capabilities the agent has access to. This includes Claude’s native tools (web search, code execution, artifacts) and MCP connections (Shopify, Klaviyo, Notion, etc.).

Tools define what’s possible. An agent with Shopify access can check real inventory. An agent without it can only work with data you provide. An agent with code execution can calculate precisely. An agent without it can only estimate.

Think of tools as the agent’s hands. The goal tells it what to do. Tools determine what it can do.

3. Instructions

How the agent should approach the work. This is your system prompt — the role, context, constraints, output format, error handling, and examples we covered in Module 3.

Instructions define the approach. Two agents with the same goal and tools but different instructions will produce different outputs. One might be thorough and methodical. Another might be quick and high-level. One might format for clients. Another might format for internal use.

Instructions encode your expertise. How you do the work, distilled into a form Claude can follow.

4. Memory

What context the agent carries. This includes Claude’s memory system, project knowledge, and any documents or context you provide.

Memory defines what the agent knows. An agent with your client context document knows their brand voice, their AOV, their customer segments. An agent without it gives generic advice.

Memory is what makes an agent yours. The same instructions running with different memory produce different — and more relevant — outputs.

How the Components Interact

These four components don’t operate independently. They shape each other.

Goal shapes everything. It determines what tools you need, what instructions to write, what memory to include. A goal of “audit email flows” requires different tools (Klaviyo access), different instructions (audit methodology), and different memory (benchmarks) than “write email copy” (no data access needed, creative brief format, brand voice examples).

Tools constrain possibilities. If you don’t have MCP access to a system, your agent can’t query it. Your instructions need to account for what’s possible. Your goal needs to be achievable with available tools.

Instructions encode method. They tell Claude how to use the tools to achieve the goal, given the memory available. They’re the bridge between capability and outcome.

Memory provides context. It’s the specific knowledge that makes generic instructions produce specific, relevant outputs.

Packaging Instructions as Skills

Once you’ve refined an agent’s instructions through iteration, you can package them as a skill file. A skill is essentially your Instructions component in reusable, portable form.

This makes your agent:

Reproducible. The same agent works across different conversations without rewriting the prompt each time.

Shareable. Team members or clients can use your agent with the same quality of output.

Portable. Move agents between Claude Projects or share them across your organization.

Version-controlled. Iterate on the skill file itself, tracking what changed and why.

We cover building your own knowledge layer — including skills files — in Module 6. For now, understand that the Instructions component you’re crafting isn’t throwaway work. It becomes an asset you can package and reuse.

Agent vs. Prompt vs. Workflow

Let’s clarify what makes something an agent versus just a good prompt or a workflow.

A prompt is instructions for a single interaction. “Analyze this email and suggest improvements.” It might be excellent, but it’s one-shot. No persistent identity, no accumulated capability.

A workflow is a sequence of steps you execute. Export data here, paste there, ask Claude this, then that. You’re the orchestrator. Claude is one tool among several.

An agent is a persistent, defined entity. It has an identity (the role in your system prompt). It has capabilities (tools). It has knowledge (memory). It can be deployed — you point it at work and it produces output, reliably, consistently.

The distinction matters because agents are reusable and improvable. You build them once, use them many times, refine them based on performance. A prompt is ephemeral. An agent is infrastructure.

The Minimum Viable Agent

You don’t need all four components at maximum strength to have a useful agent. Start minimal and add sophistication.

Minimum goal: A clear, specific outcome. Not comprehensive, just defined.

Minimum tools: Claude’s native capabilities. Web search, code execution, artifacts. No MCP required to start.

Minimum instructions: Role, context, output format. Enough to shape behavior.

Minimum memory: Project instructions. No extensive knowledge base needed.

A minimum viable agent might just be: a Claude Project with good instructions and a clear purpose. That’s it. That’s an agent. You can add tools, add memory, sophisticate the instructions — but the base is simple.

The Agent Development Cycle

Building agents is iterative. Here’s the cycle:

1. Define: Specify the goal, identify needed tools, draft instructions, determine required memory.

2. Build: Create the Project, write the system prompt, connect tools, add knowledge.

3. Test: Run real tasks through the agent. Start with typical cases.

4. Evaluate: Is the output good? Does it meet the goal? Where does it fall short?

5. Iterate: Refine instructions, add examples, adjust constraints. Return to step 3.

You’ll go through this cycle multiple times for any agent worth building. The first version is never the final version. That’s not failure — that’s the process.

What Makes an Agent Good

A good agent is:

Reliable. Same type of input produces same quality of output. No surprises. No wide variance.

Useful. It saves time or produces better results than manual work. If it doesn’t, why have it?

Bounded. It knows what it does and doesn’t do. It handles edge cases gracefully. It asks for help when appropriate.

Improvable. When it fails, you can see why and fix it. The instructions are clear enough to modify.

These qualities come from the development process. Reliability comes from testing and iteration. Usefulness comes from clear goal definition. Boundaries come from explicit constraints. Improvability comes from well-structured instructions.

Next lesson: Step-by-Step: Build an Inbox Triage Agent — your first complete agent build, from goal through deployment.

Found this content informative? Like this post, leave a comment and share with others. Help me gain wider reach.

Leave a comment

This lesson is about the layer you build yourself: documented assets that make Claude systematically better at your specific work. Not Claude’s features — your infrastructure.

The Four Components

Your knowledge layer has four main components:

1. Skills files — documented best practices and methodologies Claude can reference

2. Reference templates — examples of excellent output Claude can pattern-match against

3. Client context documents — everything Claude needs to know about specific clients or projects

4. Prompt libraries — reusable prompts for tasks you do repeatedly

Each component serves a different purpose. Together, they create a system that compounds in value over time.

Skills Files: Documented Best Practices

A skills file documents how to do something well. Not generic best practices from the internet — your best practices, refined through experience, specific to your work.

What makes a good skills file:

• Specific to a task type. “How to audit a Klaviyo welcome series,” not “email marketing best practices.”

• Process-oriented. Step-by-step, what to do, in what order, with what considerations.

• Decision-inclusive. Not just “analyze open rates” but “if open rates are below X, check for these issues first.”

• Experience-encoded. The things you’ve learned that aren’t in any guide.

Example structure for a skills file:

# Skill: Abandoned Cart Flow Audit

## When to use this

Reference when auditing any abandoned cart flow in Klaviyo for DTC e-commerce.

## Evaluation Framework

1. Check flow configuration: timing between emails, trigger conditions, exit conditions...

2. Analyze email 1 performance: open rate benchmark is 45%+, click rate benchmark is 5%+...

[continue with each email and metric]

## Common Issues and Fixes

- Low open rates usually indicate: [list causes and solutions]

- High unsubscribe rates usually indicate: [list causes and solutions]

## Red Flags

Issues that indicate serious problems requiring immediate attention: [list]

## Output Format

Present findings in this structure: [specify format]

When this skills file is in your Project Knowledge, Claude approaches abandoned cart audits with your methodology, not generic approaches.

Reference Templates: Examples of Excellence

We covered few-shot examples in Module 3. Reference templates are the persistent version — examples you want Claude to have access to across all conversations in a project.

Types of reference templates:

• Output templates — examples of excellent deliverables (audit reports, email copy, analysis summaries)

• Voice templates — examples that demonstrate the tone and style you want

• Format templates — examples showing structure, sections, and organization

Example: An audit report template

Take your best audit report — one where the structure, tone, and depth are exactly right. Clean it of client-specific details if needed, but keep the structure and approach intact.

Upload it to your audit project as “reference-audit-report.md” with a header:

# Reference: Exemplary Audit Report

This is an example of an excellent flow audit report. Use this as a reference for structure, depth of analysis, tone, and format when creating new audit reports.

[Full report follows]

Now when you ask Claude to create an audit report, it has a concrete example of what “good” looks like — your definition of good, not generic.

Client Context Documents: Everything Claude Needs

For client work, create comprehensive context documents that give Claude everything it needs to work effectively on that client’s business.

What to include:

• Business overview: Industry, products, positioning, target market

• Key metrics: AOV, customer lifetime value, purchase frequency, typical segments

• Brand voice: How they communicate, what language they use, what they avoid

• Strategic context: Current priorities, recent changes, upcoming plans

• Constraints: What they won’t do, limitations on resources, regulatory considerations

• Relationship context: Key contacts, decision-making process, communication preferences

Example structure:

# Client Context: Coastal Footwear

## Business Overview

Hawaii-based DTC footwear brand. Premium positioning ($85 average order). Target demographic: women 35-55 who value comfort and style. Strong local brand recognition, building mainland e-commerce.

## Current Email Program

Klaviyo since 2022. Basic flows in place but not optimized since initial setup. Campaign sends 2x/week. List size: 45,000 active profiles. Email contributes ~25% of revenue (target: 35%).

## Brand Voice

Warm and welcoming, island-inspired without being kitschy. Emphasize comfort and quality. Avoid aggressive sales language. Never use discount as primary value proposition.

[Continue with more sections...]

This document lives in your client project. Every conversation starts with Claude knowing who this client is, what they need, and how to serve them.

Prompt Libraries: Reusable Prompts

If you do a task more than twice, the prompt should be saved and refined rather than recreated each time.

Building your prompt library:

1. Capture prompts that work. When a prompt produces excellent results, save it immediately.

2. Generalize for reuse. Replace client-specific details with placeholders: [CLIENT NAME], [PRODUCT TYPE], [TARGET METRIC].

3. Document the context. Note when to use this prompt, what inputs it needs, what output to expect.

4. Version as you improve. Prompts get better with use. Update them when you discover improvements.

Example prompt library entry:

# Prompt: Welcome Series Analysis

## When to use

Initial analysis of any welcome series flow. Use after exporting flow data from Klaviyo.

## Required inputs

- Flow performance data (last 90 days minimum)

- Number of emails in series

- Client context (industry, AOV, audience)

## The prompt

“Analyze this welcome series for [CLIENT NAME], a [INDUSTRY] brand with $[AOV] average order value targeting [AUDIENCE DESCRIPTION].

Here’s the flow data: [PASTE DATA]

Provide: (1) Current State summary; (2) Performance Assessment with metrics vs. DTC benchmarks; (3) Priority Issues ranked by revenue impact; (4) Specific Recommendations with expected impact estimates.”

## Expected output

Structured analysis following the four-section format. Should be specific enough to act on immediately.

## Version history

v1.0 - Initial prompt

v1.1 - Added “revenue impact” to priority ranking requirement

v1.2 - Added audience context to improve benchmark selection

Organizing Your Knowledge Layer

As you build these assets, organization matters.

By project: Each Claude Project gets the relevant subset of your knowledge layer. The Klaviyo audit project gets audit-related skills files and templates. The content creation project gets writing templates and brand voice guides.

By type: Within your file system (outside Claude), organize by component type. A folder for skills files, a folder for templates, a folder for client contexts, a folder for prompts. This makes it easy to find and update.

With metadata: Include creation dates, last-updated dates, and version notes. Your knowledge layer is only valuable if it’s current.

The Compound Effect

Your knowledge layer compounds over time.

Every skills file you create makes that type of work faster and better, forever. Every template you save prevents reinvention. Every prompt you refine gets more reliable.

Early investment feels slow. You’re doing the work AND documenting the work. But each asset pays dividends across every future use.

A year from now, you won’t remember how you worked before you had this infrastructure. Claude with your knowledge layer will feel like a different tool entirely — because it is. It’s Claude trained on your expertise, calibrated to your standards, equipped with your methods.

Getting Started

You don’t need to build everything at once. Start with the component that will have the most immediate impact:

• If you do a specific task repeatedly: Create a skills file for it.

• If Claude’s output quality is inconsistent: Create reference templates.

• If you work with multiple clients: Create client context documents.

• If you keep rewriting similar prompts: Start your prompt library.

Each component you add makes Claude more capable. The knowledge layer isn’t extra work — it’s the foundation for working at a higher level.

--- End of Module 6 ---

What’s Next: Module 7 brings everything together: Building Your First Agent. You understand Claude, you know when to use it, you can prompt for agents, you know the tools, you’ve connected MCP, and you understand memory and context. Now you’ll build something real — from goal definition through testing and iteration.

Found this content informative? Like this post, leave a comment and share with others. Help me gain wider reach.

Leave a comment

Because real work isn’t always a quick question and answer. Sometimes you’re iterating on a document across 30 exchanges. Sometimes you’re building an analysis that requires sustained context. Sometimes the conversation needs to be long.

Here’s how to do that without losing the thread.

Recognizing When Claude Is Losing the Thread

The first skill is recognition. Claude won’t tell you it’s getting confused. You have to notice.

Signs Claude is losing context:

• Contradicting earlier decisions. You established X in message 10, and now Claude is recommending the opposite.

• Forgetting constraints. “Remember, no discount-focused messaging” — but Claude just suggested a 20% off subject line.

• Asking questions you’ve already answered. “What industry is this client in?” when you said footwear fifteen messages ago.

• Inconsistent tone or style. The voice drifts from what you established earlier.

• Repetitive suggestions. Claude keeps recommending the same thing you already discussed and decided against.

• Superficial responses. Answers become more generic, less connected to the specific context you’ve built up.

When you see these signs, the conversation has gotten too long or the important information has drifted to the forgotten middle. Time to intervene.

The Checkpoint Pattern

Don’t wait for problems. Build checkpoints into long conversations proactively.

Every 10-15 exchanges, pause and checkpoint:

“Before we continue, let’s verify we’re aligned. Summarize: (1) The key decisions we’ve made so far. (2) The constraints we’re working within. (3) What we’re trying to accomplish in this next phase.”

This does several things:

• Forces Claude to articulate the important context (refreshing its grip on it)

• Surfaces any drift or confusion before it causes problems

• Puts the critical information at the end of the context (the high-attention zone)

• Gives you a chance to correct any misunderstandings

Checkpoints feel like interruptions. They’re actually efficiency. Catching drift early is much cheaper than discovering it after Claude has built something on a flawed foundation.

Summarization Strategies Mid-Conversation

When a conversation has covered a lot of ground, summarization can reset the context.

The recapping prompt:

“Let’s recap where we are. Summarize in a structured format: (1) Starting context and goal. (2) Analysis completed so far. (3) Key findings. (4) Decisions made. (5) Open questions. (6) Next steps.”

Claude’s summary becomes a fresh anchor point. The conversation can continue with this summary as the recent, high-attention context.

The compression prompt:

“We’ve covered a lot. Give me a compressed summary of everything we’ve established — the kind of summary I could use to brief someone who’s joining this work now.”

This produces a dense, information-rich summary you can save externally or use to start a fresh conversation

.

When to Start Fresh with a Summary

Sometimes the best move is to start a new conversation entirely, carrying forward only what matters.

The fresh start workflow:

1. In your current conversation, ask for a comprehensive summary of the work so far.

2. Copy that summary (and any artifacts/documents you’ve created).

3. Start a new conversation.

4. Paste the summary as your opening message: “I’m continuing work from a previous conversation. Here’s where we left off: [paste summary]. Now let’s continue with [next task].”

You’ve now got a fresh context window with the distilled essence of your previous work, none of the noise, and Claude’s full attention.

When to use this:

• Conversation has exceeded 25-30 exchanges

• Claude is showing signs of context loss

• You’re transitioning to a different phase of work

• The conversation has accumulated a lot of exploratory discussion that’s no longer relevant

The Sprint Pattern

For complex, multi-session work, think in sprints rather than marathon conversations.

Each sprint:

• Starts with clear context (previous sprint summary + current sprint goal)

• Covers 15-20 exchanges maximum

• Ends with a summary and artifact checkpoint

• Produces tangible output (a document section, a completed analysis, a decision)

Between sprints:

• Start fresh or checkpoint and continue

• Carry forward summaries, not full history

• Save artifacts externally so they don’t depend on conversation context

This sprint pattern keeps each working session within Claude’s effective attention span while allowing extended projects to develop over time.

Using Artifacts as External Memory

Artifacts (Module 4, Lesson 4.1) aren’t just outputs — they’re memory aids.

When you create an artifact, it persists in the conversation panel. Even as the context window gets crowded, the artifact remains visible and referenceable.

Use this strategically:

• Put key decisions in an artifact: “Create a markdown artifact called ‘Project Decisions’ and add each major decision we make.”

• Build living documents: Instead of decisions scattered across 30 messages, accumulate them in an artifact that gets updated.

• Reference artifacts explicitly: “Check the ‘Project Decisions’ artifact — does this new recommendation align with what we decided earlier?”

Artifacts don’t disappear into the middle of the context. They stay present, anchoring important information.

Repetition Isn’t Redundant

In long conversations, repeating important information isn’t wasteful — it’s necessary.

The middle-gets-lost problem means that a constraint mentioned once, 20 messages ago, may be functionally forgotten even though it’s technically in context.

Repeat strategically:

• When constraints matter for the current task: “Remember, we’re avoiding discount messaging — with that in mind, draft subject lines for...”

• When asking for final output: “Before you finalize, verify alignment with: [list key constraints and decisions].”

• When Claude seems to be drifting: “To reset: we established X, decided Y, and are constrained by Z. Given that, let’s continue.”

You’re not telling Claude things it doesn’t know. You’re putting important things at the end of context, where attention is highest.

The Briefing Document Pattern

For recurring long-form work, create a briefing document that starts every conversation.

Example: You’re writing a 10-module course. Each module requires multiple sessions. Create a course briefing document:

Course: Claude Mastery for E-commerce Operators

Audience: E-commerce operators, particularly Klaviyo specialists

Voice: Direct, practical, no-fluff. Examples from real e-commerce work.

Completed: Modules 1-5

Current: Module 6 — Memory and Context

Key decisions: [list major decisions about structure, tone, content]

Paste this at the start of each working session. Claude immediately has the context it needs, even in a fresh conversation.

Long Conversation Checklist

For any conversation that will extend beyond 15-20 exchanges:

• Start with clear context (briefing document or summary from previous session)

• Build artifacts for important outputs and decisions

• Checkpoint every 10-15 exchanges

• Repeat critical constraints when they’re relevant

• Watch for signs of context loss

• Summarize before continuing when things get dense

• Consider fresh-starting with a summary at natural breakpoints

• End with a summary you can carry to the next session

Long conversations are manageable. They just require active management rather than passive accumulation.

Next lesson: Building Your Own Knowledge Layer — skills files, reference templates, client context documents, and prompt libraries that make your Claude work systematically better.

Found this content informative? Like this post, leave a comment and share with others. Help me gain wider reach.

Leave a comment

This is where Claude Projects become powerful. A Project isn’t just a collection of conversations — it’s a workspace with persistent knowledge that every conversation in that project can access.

What Project Knowledge Is

When you create a Project in Claude, you can upload documents to it. These documents become part of the project’s knowledge base — available to Claude in every conversation within that project.

This is different from uploading a file in a single conversation. A file uploaded to a conversation is only available in that conversation. A file uploaded to Project Knowledge is available in every conversation in the project.

Think of it as Claude’s reference library for that specific work. Your Klaviyo audit project might have benchmark documents, your methodology guide, and client brief templates. Every audit conversation can reference these materials without you re-uploading them.

File Types That Work Well

Not all file types are equally useful for Project Knowledge. Here’s what works:

Excellent:

• Markdown (.md) — Claude’s native format. Clean, structured, easy to parse. Best choice for methodology documents, guidelines, and structured reference material.

• Plain text (.txt) — Simple and reliable. Good for lists, quick references, and unformatted content.

• PDF — Works well for documents with important formatting, reports, and materials you’ve received from others.

Good:

• Word documents (.docx) — Claude can read these, though markdown is cleaner for reference material you’re creating yourself.

• CSV/Excel — Useful for data references, but large datasets are better handled through code execution in specific conversations.

Less Ideal:

• Images — Claude can see images, but text-based reference material is more reliably retrievable.

• Very large files — They consume context window space. Better to excerpt the relevant portions.

The practical recommendation: For materials you’re creating specifically for Claude, use markdown. For materials from external sources, PDF usually works fine.

What to Upload as Project Knowledge

Different types of projects benefit from different knowledge bases. Here’s what to consider:

For client work projects:

• Client brief or onboarding document

• Brand guidelines or voice documentation

• Previous work or reports for context

• Relevant benchmarks or performance targets

For methodology projects:

• Your documented process or framework

• Checklists or quality criteria

• Examples of good output

• Industry benchmarks or standards

For analysis projects:

• Reference frameworks for the analysis type

• Benchmark data

• Output templates

• Previous analyses for consistency reference

Organizing Knowledge for Retrieval

How you organize and name your knowledge files affects how well Claude can use them.

Use descriptive file names: “klaviyo-flow-benchmarks-2026.md” is better than “benchmarks.md”. Claude sees file names and uses them to understand what’s in each file.

Add context at the top of documents: Start each document with a brief description of what it contains and when to use it. This helps Claude know when to reference the document.

Example document header:

“# Klaviyo Flow Benchmarks

Use this document when analyzing email flow performance. These benchmarks are specific to DTC e-commerce brands doing $1M-$10M annually. Last updated: January 2026.”

Structure documents clearly: Use headers, sections, and consistent formatting. Claude parses structured documents more reliably than wall-of-text documents.

Keep documents focused: One document per topic is better than one massive document with everything. “flow-benchmarks.md” and “campaign-benchmarks.md” are easier to work with than “all-benchmarks.md”.

Keeping Project Knowledge Current

Project Knowledge isn’t set-and-forget. It needs maintenance.

Regular review: Every quarter, review your project knowledge. Are benchmarks still current? Has your methodology evolved? Are there documents you’re no longer using?

Version awareness: When you update a methodology or benchmark document, note the update date in the document. This helps you track currency and helps Claude know how recent the information is.

Pruning: Remove outdated documents rather than letting them accumulate. Old benchmarks or deprecated methodologies can confuse Claude — and you.

Addition triggers: When you find yourself repeatedly explaining something to Claude within a project, that’s a signal to create a knowledge document. The explanation you’re making verbally should probably be written down and uploaded.

Project Knowledge vs. Conversation Uploads

When should you upload to Project Knowledge vs. uploading in a specific conversation?

Upload to Project Knowledge when:

• The document is reference material you’ll use across multiple conversations

• It’s methodology, benchmarks, or guidelines that should inform all work in this project

• It’s relatively stable — won’t change conversation to conversation

Upload in conversation when:

• The document is specific to this task (a data export to analyze, an email to review)

• It’s one-time use material

• It’s large and would unnecessarily consume context in other conversations

The test: “Will I want Claude to know about this in my next conversation in this project?” If yes, Project Knowledge. If no, conversation upload.

Building Effective Knowledge Documents

The best Project Knowledge documents share certain characteristics:

Clear purpose statement: What is this document for? When should Claude reference it?

Structured content: Headers, sections, lists. Easy to scan, easy to parse.

Specific information: Actual benchmarks, not “good open rates.” Real examples, not vague descriptions.

Currency indicators: When was this written? When was it last updated? What time period does it cover?

Actionable guidance: Not just what, but how. Not just benchmarks, but what to do when performance is above or below.

Example: A Methodology Knowledge Document

Here’s the structure of an effective methodology document for a Klaviyo audit project:

# Klaviyo Flow Audit Methodology

Purpose: This document defines how to conduct flow audits for DTC e-commerce clients. Reference this when analyzing any flow performance data.

## Flow Priority Order

Analyze flows in this order: 1. Welcome Series, 2. Abandoned Cart, 3. Browse Abandonment, 4. Post-Purchase, 5. Win-Back...

## Metrics to Evaluate

For each flow: Open rate, Click rate, Conversion rate, Revenue per recipient, Unsubscribe rate...

## Benchmark Thresholds

[Specific numbers for each metric by flow type]

## Red Flags

Issues that indicate serious problems: [list with explanations]

## Output Format

Structure audit findings as: Current State, Performance Assessment, Priority Issues, Recommendations...

This document turns every audit conversation into a consistent, methodology-driven analysis. Claude knows how to approach the work because you’ve documented how you approach it.

Next lesson: Managing Long Conversations — strategies for maintaining coherence when conversations extend beyond Claude’s natural attention span.

Found this content informative? Like this post, leave a comment and share with others. Help me gain wider reach.

Leave a comment

Memory is what transforms Claude from a tool you use repeatedly into a partner that knows your context. It’s the difference between explaining your business every conversation versus picking up where you left off.

What Memory Actually Is

Claude’s memory feature allows information from past conversations to persist and inform future ones. When you tell Claude something important — your business context, your preferences, your ongoing projects — that information can be retained and referenced later.

This isn’t the same as conversation history within a single chat. That’s context window — information Claude can see because it’s in the current conversation. Memory is different: it’s information that carries across conversations, available even when you start fresh.

Think of it like the difference between short-term and long-term memory. The context window is short-term — what’s immediately present. Memory is long-term — what persists over time.

How Memories Are Generated

Claude doesn’t remember everything. Memories are generated selectively, typically capturing:

• Facts about you and your business — your role, your company, your industry, your clients

• Your preferences — communication style, formatting preferences, how you like information presented

• Ongoing context — projects you’re working on, decisions you’ve made, strategies you’re pursuing

• Important relationships — key clients, team members, stakeholders you reference frequently

The generation happens in the background. As you converse with Claude, it identifies information that seems worth retaining and creates memories. You don’t have to explicitly say “remember this” — though you can.

What Gets Remembered vs. What’s Ignored

Not everything becomes a memory. Understanding the distinction helps you work with the system rather than against it.

Likely to become memories:

• Stable facts about your identity and business

• Explicit preferences you’ve stated

• Context you’ve provided about ongoing work

• Information you’ve referenced multiple times

Unlikely to become memories:

• One-off details from a specific task

• Temporary information that will change

• Granular data points (specific metrics, exact figures)

• Content of documents you’ve shared (the document itself, not facts about it)

The practical implication: If something is important for Claude to know long-term, make it explicit and frame it as persistent context, not task-specific detail.

“For this email, the client’s AOV is $85” — probably not remembered.

“My client Coastal Footwear has an AOV of $85 and focuses on the 35-55 female demographic” — more likely to be remembered.

Viewing Your Memories

You can see what Claude remembers about you. In Claude.ai, look for Memory in your settings or profile area. You’ll see a list of stored memories — facts, preferences, and context that Claude has retained.

This is worth reviewing periodically. You might find:

• Memories that are outdated (you’ve changed roles, a project has ended)

• Memories that are incorrect (Claude misunderstood something)

• Memories that are surprisingly useful (context you forgot you’d shared)

• Gaps where important context is missing

  Thanks for reading Kinga | Claude AI for Ecommerce! This post is public so feel free to share it.

  Share

Editing and Deleting Memories

Memories aren’t permanent. You can edit or delete them as needed.

Delete when:

• Information is no longer accurate

• Context is no longer relevant

• You want a fresh start on a topic

Edit when:

• Details have changed but the core is still relevant

• The memory is almost right but needs correction

• You want to add nuance to existing context

Think of memory management as hygiene. A quick review every month or two keeps Claude’s understanding of you current and accurate.

Memory Scope: Global vs. Project-Level

Here’s something important: memories can have different scopes.

Global memories apply everywhere. Your name, your business, your general preferences — these should inform every conversation regardless of context.

Project-level memories apply within a specific Project. When you’re using Claude Projects (covered in Lesson 6.2), memories generated within that project stay within that project.

This separation is useful. Your Klaviyo audit project doesn’t need memories from your personal recipe experiments. Your client work doesn’t need context from conversations with your team about internal operations.

The practical implication: Be thoughtful about where you have conversations. Context shared in a Project stays in that Project. Context shared in general conversations becomes global.

User Edits: Telling Claude What to Remember

You don’t have to wait for Claude to decide what’s worth remembering. You can explicitly tell Claude to remember things — or to forget them.

To add a memory:

“Remember that my primary client is Coastal Footwear, a Hawaii-based DTC brand with $2M annual revenue.”

“Please remember that I prefer concise responses without excessive caveats.”

“Remember that I’m building a course on Claude for e-commerce operators.”

To remove a memory:

“Forget that I work at [old company] — I’ve changed jobs.”

“Please don’t remember details about my divorce — I’d prefer not to discuss that.”

“Remove the memory about the Project X deadline — that project is complete.”

These explicit instructions give you control. You’re curating Claude’s understanding of you rather than leaving it entirely to inference.

Memory Best Practices for E-commerce Work

For e-commerce operators specifically, consider establishing memories for:

Your expertise and role: “I’m a Klaviyo specialist who works with DTC brands doing $1M-$10M annually. I focus on email marketing strategy, flow optimization, and campaign management.”

Your client roster: “My current clients include [Client A] (footwear), [Client B] (supplements), and [Client C] (home goods).” This lets Claude understand context when you mention client names.

Your methodology: “When I audit email programs, I use a specific framework: flow analysis first, then campaign review, then list health, then strategic recommendations.”

Your standards: “I consider 40%+ open rates strong for welcome series, 25%+ for campaigns. I benchmark against DTC e-commerce specifically, not general email marketing.”

Your preferences: “I prefer specific, actionable recommendations over general best practices. I want revenue impact estimates when possible. I don’t need excessive caveats — I understand these are estimates.”

This context transforms every conversation. Claude starts with understanding rather than requiring explanation.

The Memory Mindset

Think of memory as an investment. The context you establish now pays dividends in every future conversation.

Without memory, every conversation starts cold. You explain who you are, what you do, what you need. Over and over.

With well-curated memory, conversations start warm. Claude knows your context. You can get straight to work.

The difference compounds. A few minutes spent establishing good memories saves hours of re-explanation over time.

Next lesson: Project Knowledge — how to give Claude access to reference documents, methodology guides, and other materials that inform your work.

Found this content informative? Like this post, leave a comment and share with others. Help me gain wider reach.

Leave a comment