Why AI Agent Skills Beat Giant Prompts

One email, twelve procedures▶ 0:00Copy link

Your AI agent's instructions file keeps growing, and every request the agent makes carries all of it, even when the job needs one page. Kettle & Bean, a small coffee roaster, gave its support agent the whole handbook: 12 procedures, 3,221 words. A customer writes about a torn bag. The agent needs one procedure, and reads all 12. By the end of this video, you'll know what an agent skill is, how it loads only what a job needs, what that saves, and when one big prompt is still fine.

Everything here is a real run. The agent is Claude Code, Anthropic's coding agent, run with nothing else loaded. Here's the handbook: an always-on part, then twelve procedures, from late orders to press requests. From those same words, we built two agents: one with the whole handbook in a single prompt, and one with skills.

skills-lab$ lsagent		giant		handbook	scripts
build		grow		mail		skills

skills-lab$ ls handbook00-always.md		05-wholesale.md		10-loyalty.md
01-late-orders.md	06-subscriptions.md	11-data-requests.md
02-damaged-parcel.md	07-gift-cards.md	12-press.md
03-refunds.md		08-address-changes.md
04-allergens.md		09-grinder-warranty.md

What the model reads▶ 0:55Copy link

First, what does the model actually read? Each time an agent thinks, it sends the model one request, and that request carries everything the model knows at that moment: the agent's own instructions and tools, your project's instructions file, CLAUDE.md, and the job itself. That's the context window. It's measured in tokens: small pieces of words.

We gave each agent the smallest job there is: reply with just ok. No handbook at all: 7,215 tokens. The giant prompt: 13,402. Skills: 8,089.

skills-lab$ ./agent --none "Reply with just: ok"ok
(model requests: 1 · context each: 7,215 tokens · read in total: 7,215)

skills-lab$ ./agent --giant "Reply with just: ok"ok
(model requests: 1 · context each: 13,402 tokens · read in total: 13,402)

skills-lab$ ./agent --skills "Reply with just: ok"ok
(model requests: 1 · context each: 8,089 tokens · read in total: 8,089)

Without a handbook, the 7,215 tokens are the agent's own instructions and tools. The giant prompt added 6,187 tokens to that one request, for a job that needed none of it. The skills added 874.

The giant prompt▶ 1:52Copy link

Here's the giant prompt: 3,221 words in one CLAUDE.md file, twelve procedures, one after another. Claude Code reads this file at the start of every session, and from then on it's part of every request.

skills-lab$ wc -w giant/CLAUDE.md    3221 giant/CLAUDE.md

skills-lab$ grep '^## ' giant/CLAUDE.md## Late orders
## Damaged on arrival
## Refunds
## Allergens and ingredients
## Wholesale quotes
## Subscriptions
## Gift cards
## Address changes
## Equipment warranty
## Loyalty points ("Beans")
## Personal data requests
## Press, partners and sponsorship

Now a real email. Lena's bag arrived torn, and beans spilled all over the box. The giant-prompt agent writes a good reply: it asks for two photos, sends a new bag by express, and says there's nothing to send back. That's the damaged-parcel procedure, followed exactly. One request: 13,467 tokens.

skills-lab$ cat mail/torn-bag.txtOrder 2207, Ethiopia Yirgacheffe 1 kg, delivered yesterday. The customer, Lena, writes: the bag arrived torn and beans spilled all over the box. Write the reply.

skills-lab$ ./agent --giant mail/torn-bag.txtSubject: Your torn bag of Ethiopia Yirgacheffe

Hi Lena,

Thank you for letting us know. I'm so sorry your bag arrived torn. That's not how we want your beans to reach you.

Could you send one photo of the bag and one of the box? As soon as we have them, a new 1 kg bag of Ethiopia Yirgacheffe goes out by express, at no cost to you.

If the spilled beans are clean, feel free to keep them or compost them. There's nothing to send back to us.

Sam, Kettle & Bean

---
Note for you (not part of the reply): add the label DAMAGE to the ticket for order 2207. I held the replacement until the photos arrive, because I don't have Lena's order history. If they've ordered from us 3 or more times before, you can send the replacement straight away and ask for the photos afterwards. In that case, change the second paragraph.
(model requests: 1 · context each: 13,467 tokens · read in total: 13,467)

But look at what it read to get there. One procedure was useful. The other eleven, refunds, allergens, wholesale prices, gift cards and the rest, came along for nothing, and they come along on every email.

And size costs more than tokens. Anthropic's own Claude Code guide says to aim for under two hundred lines per CLAUDE.md file, because longer files consume more context and reduce adherence: the model follows them less reliably. Researchers at Chroma measured a wider version of this, called context rot: as the input grows, models get less reliable, even on simple tasks.

What a skill is▶ 3:11Copy link

The second agent has the same twelve procedures, as skills. A skill is a folder with one required file, SKILL.md: here are twelve folders, one per procedure. Its CLAUDE.md keeps only the three rules that matter on every email: who we are, how to sign, and never share one customer's details with another.

skills-lab$ ls skills/.claude/skillsaddress-changes		gift-cards		press-and-partners
allergens		grinder-warranty	refunds
damaged-parcel		late-orders		subscriptions
data-requests		loyalty-points		wholesale-quotes

skills-lab$ cat skills/CLAUDE.mdYou answer customer emails for Kettle & Bean, a small online coffee roaster.
Write warm, short replies in plain text. Sign every reply "Sam, Kettle & Bean".
Never share one customer's details with another customer.

At the top of each SKILL.md, between two lines of dashes, are a short name and a description: what the skill does, and when to use it. Below that comes the procedure itself, the same words as in the giant prompt.

skills-lab$ head -4 skills/.claude/skills/damaged-parcel/SKILL.md---
name: damaged-parcel
description: How to handle a parcel or product that arrived damaged, torn, crushed, leaking or with a broken seal. Use for any email about damage on arrival.
---

How a skill loads▶ 3:51Copy link

Here's how a skill loads. At the start, the agent gives the model only each skill's name and description. Lena's email arrives. The model sees that damaged-parcel matches it, and asks the agent for that skill, because a model can't open files by itself. The agent reads the full SKILL.md and adds it to the context. Only then does the model write the reply. Anthropic calls this progressive disclosure.

The same email, with skills. Loaded skill: damaged-parcel, chosen by the model itself. The reply asks for the same two photos and sends the same new bag. Two requests this time: 8,155 tokens, then 8,930 with the procedure added. Each one is smaller than the giant prompt's 13,467.

skills-lab$ ./agent --skills mail/torn-bag.txt[loaded skill: damaged-parcel]
Here's the reply for Lena:

Subject: Your Yirgacheffe order 2207

Hi Lena,

I'm so sorry your bag arrived torn. That's not how we want your beans to reach you. Thank you for letting us know.

Could you send one photo of the bag and one of the box? We need both for the carrier claim. As soon as we have them, a new 1 kg bag of Ethiopia Yirgacheffe goes out by express, at no cost to you.

If the beans that spilled in the box are clean, you're welcome to enjoy them or compost them. There's nothing to send back.

Thanks again, and sorry for the trouble.

Sam, Kettle & Bean

Two notes for you:
- I didn't see Lena's order history. If they've ordered from us 3 or more times before, the policy says to send the replacement straight away and ask for the photos afterwards. In that case, change the second paragraph.
- The skill says to add the DAMAGE label to the ticket. I can't reach your ticket system from here, so please add it yourself.
(model requests: 2 · context each: 8,155, 8,930 tokens · read in total: 17,085)

Side by side. The same reply. The giant prompt read all twelve procedures in one request; the skills agent read one, over two smaller requests. But notice the total: the skills agent read more, 17,085 tokens against 13,467, because loading the skill took an extra step. We'll come back to that.

Scripts inside skills▶ 5:08Copy link

A skill can carry files too. The refunds skill has a script next to it: the refund rules, written as code. Tom wants a refund on an opened bag, delivered nine days ago. The agent loads the refunds skill, then runs the script with his numbers. The script decides: fifteen dollars back, or thirty in store credit.

skills-lab$ find skills/.claude/skills/refunds -type fskills/.claude/skills/refunds/scripts/refund.py
skills/.claude/skills/refunds/SKILL.md

skills-lab$ ./agent --skills mail/refund.txt[loaded skill: refunds]
[ran: python3 .claude/skills/refunds/scripts/refund.py --price 30.00 --days 9 --opened yes]
Hi Tom,

Thanks for letting us know, and I'm sorry the Colombia Sugarcane decaf wasn't to your taste. Since the bag was opened and arrived 9 days ago, you have two options. You can have $15.00 (50%) back to your original payment method. The money should reach your bank in 3–5 working days. Or you can take the full $30.00 as store credit, which is added to your account right away, so you could try a different roast.

Tell me which you'd prefer and I'll set it up.

Sam, Kettle & Bean
(model requests: 3 · context each: 8,158, 8,818, 8,978 tokens · read in total: 25,954)

That's the third level. Anthropic describes skills in three levels: the name and description, always there, about a hundred tokens each; the instructions, loaded when a job matches; and files and scripts, opened only when needed. A script runs, and only its output enters the context, never its code. A giant prompt can point to a script too, but a skill keeps the code right next to the steps that use it.

As the handbook grows▶ 5:58Copy link

Now the real reason this matters. We rebuilt both agents with zero, four, eight and all twelve procedures, and sent the same tiny request each time. Each procedure in the giant prompt added about 498 tokens to every request. As a skill, about 56: just its name and description.

Twelve procedures is small, and real handbooks keep growing. At the rates we measured, a hundred procedures would put about 57 thousand tokens into every request with a giant prompt, and about 13 thousand with skills, before the job even starts.

A busy morning▶ 6:37Copy link

One more test: a busy morning. Five emails in one go: a late parcel, a café asking for wholesale prices, a nut allergy question, a refund, and a subscription pause. The skills agent loaded five skills, one per email. The giant-prompt agent loaded nothing: it already had everything.

skills-lab$ cat mail/inbox.txtHere are this morning's 5 customer emails. Write a reply to each, one after another.
1) Order 2213, shipped by domestic standard 9 working days ago, still not here. Customer: Ravi.
2) Café Lumen asks for a wholesale price for about 25 kg a month of the house blend.
3) Mia asks: is your coffee safe for my son, who has a nut allergy?
4) Order 2215, Kenya AA 500 g, $30.00, delivered 3 days ago, unopened. Customer Jo wants a refund.
5) Dan asks to pause his subscription for 2 months.

skills-lab$ ./agent --skills mail/inbox.txt --no-reply[loaded skill: late-orders]
[loaded skill: wholesale-quotes]
[loaded skill: allergens]
[loaded skill: refunds]
[loaded skill: subscriptions]
[ran: python3 .claude/skills/refunds/scripts/refund.py --price 30.00 --days 3 --opened no]
(model requests: 3 · context each: 8,282, 11,960, 12,251 tokens · read in total: 32,493)

skills-lab$ ./agent --giant mail/inbox.txt --no-reply[ran: python3 scripts/refund.py --price 30.00 --days 3 --opened no]
(model requests: 2 · context each: 13,596, 14,292 tokens · read in total: 27,888)

Five of the twelve procedures were needed. The other seven, like gift cards and warranties, were never opened. The skills agent's requests grew a little as each skill was added, but every one stayed smaller than the giant prompt's, which carried the whole handbook both times.

What skills cost▶ 7:16Copy link

Skills aren't free, though. On this morning's five emails, the skills agent read more in total: 32,493 tokens against 27,888. That's because loading a skill is an extra step: the model has to ask for it, and every extra request reads the whole context again.

Two more limits. The model picks a skill from its description alone, so the description must say what the skill does and when to use it, as Anthropic's guide puts it. And a skill is advice, like any prompt: nothing forces the model to follow it. Rules that must always hold belong in code, like the refund script.

With a handbook this small, one prompt still reads fewer tokens in total for a short job. Skills pull ahead as it grows, because every request reads the whole prompt again. So here's how to split a growing prompt. A few short rules every job needs stay in CLAUDE.md. Procedures that only some jobs need become skills, each with a clear description. Exact math and checks go into scripts inside those skills.

Recap▶ 8:26Copy link

Let's recap. A giant prompt is read on every request: every procedure, whether the job needs it or not, and the longer it gets, the less reliably the model follows it. A skill shows the model only its name and description, until a job needs it. In our lab, each procedure cost 498 tokens per request in the prompt, and 56 as a skill. Keep the always-on rules short, and turn the rest of the handbook into skills.

If seeing what your agent really reads was useful, subscribing helps a small channel bring you the next lab.

Every reply and every token count in this video came from a real run in our lab. Thanks for watching Cloud Explainers.

Sources

• Agent Skills overview (Anthropic)
• Skill authoring best practices (Anthropic)
• Claude Code memory and CLAUDE.md
• Agent Skills specification
• Chroma, Context Rot (2025)