🧠 The problem: working memory is limited
New here? Context (or context window) is the agent’s working memory — everything it can “see” at once while it thinks and decides: your conversation, open files, and any text loaded into the session. It’s finite. Not infinite, not elastic — a limited space that needs to be used carefully, just as a worktable can only hold so many papers at once.
If every installed skill were read entire, from the first character to the last, every time the agent thought about anything, the problem would be obvious: with 20 skills installed, a lot of the context would already be gone before you even finished typing your request. The agent would be slower, more expensive, and more confused—full of skill instructions that weren’t even relevant to the current task.
⚠️ Attention
This scenario — loading everything all the time — is exactly what the skill format avoids. The solution isn’t to "have only a few skills." It’s to load each one in the right amount, at the right time. That’s what this entire module is about.
🔍 Inside
Think of a huge library. If the entire library were placed on your desk every time you needed a specific book, you’d never find anything. Here’s how it really works: a compact catalog (the card index at the entrance) helps you find the right book, and only this book comes off the shelf.
1️⃣ Level 1 — the index, always loaded
O Level 1 is just the name e
a description from the front matter
(which you saw in module 3.1) — around 100 tokens per skill. That's very cheap, and it's exactly
what the agent scans to decide, with each new request, whether an installed skill is useful for the current task.
It's like a book's index: one line per chapter, enough to tell whether that chapter is what
you're looking for, without reading the whole chapter to find out.
Caption: the cost grows from the inside out — the center (Level 1) is tiny and always present; each outer ring comes into play only if the previous one decided it was necessary.
💡 Practical Tip
This is why the cost of have an installed skill costs almost nothing — even with 20 installed, the agent only scans 20 short index cards. The real cost only appears when one is actually used.
2️⃣ Level 2 — the chapter, only when triggered
O Level 2 comes into play only when the skill is actually triggered
— that is, when the Level 1 description matches your request. That's when the agent loads the
skill.md whole: the body
with the complete step-by-step instructions, around 1,000 to 2,000 tokens. It’s the chapter of the book you actually
chose to read — after looking at the table of contents and deciding that was the one.
Session start
All Level 1 descriptions are already available for the agent to compare with any request.
You make a request that matches one of them
At that exact moment — not before, not “just in case” — Level 2 of that specific skill enters the context.
The other 19 skills remain at Level 1 only
They didn’t cost anything extra—they remain as cards, ready in case a request comes up that fits them.
🔍 Inside
It’s the same on-demand reading principle that appeared in module 2.4 with the cheat sheet pattern: a short instruction that pulls in more detail only when needed. Skills apply this principle in a standardized way built into their format.
3️⃣ Level 3 — the appendix, on demand
O Level 3 is what stays in the folders references/ e
scripts/ from module 3.1 — and is only read if
the Level 2 step-by-step instructions explicitly say so ("if you need detail X, read file Y"). It's the technical
appendix of the book: most readers never get there, but when someone needs it, it's exactly where
it should be.
The size of Level 3 varies — it could be a 200-token file or a 5,000-token reference. But that doesn’t matter for day-to-day costs, because in the vast majority of runs, it’s never opened.
✓ concise skill.md
- ✓Body with the essential steps, fits on one screen
- ✓Move the code table, extensive examples, and rare cases to
references/ - ✓Level 2 cost always stays close to 1-2 thousand tokens
✗ Huge skill.md
- ✗Pastes everything into the body—table, examples, edge cases, all together
- ✗Every run loads all the material, even when 90% of it isn’t used
- ✗Level 2 effectively becomes a disguised Level 3 — losing the advantage of layered loading
🚀 Why having 20 installed skills doesn't slow the agent down
Bring the three levels together and the answer to the question that opened this module becomes clear: the cost of have an installed skill costs almost nothing (just Level 1, ~100 tokens each). The cost of use a skill’s cost is proportional only to what was actually triggered — Level 2 every time, Level 3 rarely. Having 20 skills installed and using just one ends up costing almost the same as having only that one installed, plus a handful of index cards for the other 19.
🎯 Main Concept
- •Having a skill installed ≠ always paying its cost. Level 1 already handles that.
- •Using a skill costs in proportion to what it actually loads — Level 2 almost always, Level 3 rarely.
- •It’s safe to install many focused skills instead of a few huge, generic ones.
💡 Practical Tip
Don’t hesitate to have a separate skill for each small process in your routine instead of one “do-it-all” skill. Specific skills with precise descriptions trigger more reliably and keep Level 2 short—the cost of installing one more is negligible.
✍️ Writing a description that triggers Level 1 correctly
Because Level 1 is the only filter that decides whether Level 2 gets loaded, the description needs to do two jobs at once: say what the skill does and when use it, with words close to how you’d actually ask for the task. Module 3.4 covers this in more depth — here’s the minimum working example.
---
name: <nome-da-sua-skill>
description: <o que ela faz>, use quando o usuário pedir
"<frase 1 que você diria>", "<frase 2>" ou "<frase 3>".
---⚠️ Attention
A vague description (“helps with reports”) doesn't compete well with similar skills and adds unnecessary complexity to the Level 1 decision. An overly specific description (“generates an October 2026 sales report”) only triggers in that exact month. Module 3.4 covers how to find the right balance.
Mental exercise: if you have 20 skills installed and none of them is used in this session, approximately how many tokens does that cost?