🫥 Skill context cost

In module 3.1, you learned what a skill and that it has a frontmatter with a description. Now here’s the part almost nobody notices: in Matt Pocock’s words, "every skill leaks your" description in the context window". In other words: as soon as you install a skill, the phrase that describes it starts taking up space in the context window of the model—every turn, whether you’re using that skill or not.

Why does it leak? Because that’s how the model discovers that the skill exists. For it to decide “oh, I could use skill X for this task,” it needs to have read X’s description first. So the system injects all the descriptions at the very beginning. The why it matters: the context window is finite and measured in tokens; every leaked description means less room for what really matters (your code, your request). The common mistake is installing a skill “because it’s nice to have”—each one charges a silent toll, even when idle.

A skill leaks very little — maybe one or two sentences. “So what’s the problem?” you ask. The problem is the multiplication. As Pocock puts it plainly: "100 skills = 100 descriptions in context". Add that to your CLAUDE.md, open files, and conversation history — and suddenly a good part of the window has already been used up even before before the model starts thinking about your task.

This ties directly to the concept of context bloat. When the window fills up, two bad effects show up: it gets more expensive (you pay for tokens) and it becomes more dumb — with too many things competing for attention, the model “gets lost” and reasons worse about what actually matters. The common mistake here is the collector mindset: “I installed 80 skills from the repository, so now I’m productive.” In practice, you’ve just filled your desk with rulers. Fewer skills visible usually pays off more.

Here's the button that solves the problem from topics 1 and 2. The skill's frontmatter has the key disable-model-invocation: true. When you turn it on, two things happen, in Pocock’s words: "only the user invokes [the skill], and the description DOESN'T leak". In plain English: (1) the model can no longer call that skill on its own—it becomes a procedure pure, triggered only by you; and (2) because the model no longer needs to "know" about the skill to decide to use it, the description stops leaking in context. You get that space back.

The example Pocock gives is the skill "engineering zoom out": it’s one of its procedures, which it invokes whenever it wants; it doesn’t make sense for the model to decide to use it on its own, so it hides it with disable-model-invocation: true. O reason is straightforward: you trade the “convenience” of letting the model choose the skill automatically for cleaner context — and, for procedures, you were going to trigger the skill manually anyway. The common mistake is connecting this to a ability (a skill whose value lies in the model pulling it in on its own, like "coding standards"): then you break exactly what made it useful.

---
name: engineering-zoom-out
description: Sai do detalhe e reavalia a arquitetura geral antes de continuar.
# Esconde a skill do modelo: SO o humano invoca (/engineering-zoom-out).
# Efeito colateral bom: a description acima NAO vaza na janela de contexto.
disable-model-invocation: true
---

# Engineering zoom out

Quando eu te chamar, pare de mexer no codigo linha a linha e:
1. Resuma em 3 bullets o que o sistema faz hoje.
2. Aponte a decisao de arquitetura mais arriscada em aberto.
3. Liste 2 caminhos possiveis (trade-offs) e recomende um.
So depois que eu aprovar, volte a escrever codigo.

Hiding descriptions isn’t just a technical cost-saving measure — it’s a control philosophy. Pocock says explicitly: he "hides most of the AI's descriptions and keeps the knowledge with the human". His sentence that sums it all up: "I know my skills, I don't want to delegate my thinking" — I know my skills; I don't want to delegate my thinking. He's the one who decides which procedure to run, not the model.

That’s why Pocock prefers procedures over abilities (you saw both types in 3.1): you want to be in the driver's seat. Here's an interesting difference in approach—the project Superpowers ("Work") prefers the opposite: let the model in control, choosing skills on its own. Neither is "wrong"; they’re different bets. The common mistake for beginners is to blindly copy someone else’s setup without realizing it embodies a philosophy. Ask yourself: Do I want AI to choose for me, or do I want to choose? The answer changes which skills you hide.

If the description leaks and every word costs, the practical conclusion is: write lean skills. This has two sides. First, the short description: it only needs to be detailed enough for the model (or you) to know when the skill applies—long sentences just add to the leakage. The grill-me that you’ll see later is praised as “unreasonably effective” in just 4–5 sentences: power isn’t size.

Second face: avoid instruction bloat inside the skill body. Here’s Pocock’s central warning about context— "everyone bloats their context window with too much stuff". A lean skill makes a very; if it’s turning into a monster with ten responsibilities, break it into smaller, chainable skills (like grill-me → two-PRD → to-issues, which you see in 3.6). The common mistake is treating the skill as a "dumping ground for everything I know about the subject." A skill isn’t a wiki; it’s a sharp procedure.

Wrapping up the module: turn all this into a habit. From time to time, do a context audit of your skills. The rule of thumb is the one from engineering zoom out: if it’s a procedure (you always invoke manually), hide it with disable-model-invocation: true and recover the context; if it’s a ability real value (the model needs to find it on its own), make it visible—but then write a concise description. The common mistake is never reviewing: you install, forget, and six months later have 60 descriptions leaking without remembering half of them.

Use the checklist below to clean up your skills. It applies, in order, everything we’ve covered: identify what leaks, decide what should become a skill, and measure the result. Copy it into your project.

FAXINA DE SKILLS - toda skill instalada vaza sua description.
Para CADA skill, decida:
[ ] EU USO? Se nao uso ha semanas -> desinstale (para de vazar de vez).
[ ] PROCEDURE (eu sempre invoco na mao)? -> disable-model-invocation: true
    (esconde do modelo + a description deixa de vazar)
[ ] ABILITY (o modelo precisa achar sozinho, ex.: coding standards)?
    -> deixe visivel, MAS encurte a description ao minimo necessario.
[ ] DESCRIPTION enxuta? Corte tudo que nao ajuda a decidir "quando usar".
[ ] CORPO enxuto? 1 skill = 1 coisa. Monstro de 10 responsabilidades? quebre.
Meta: menos descriptions vazadas = mais janela pro raciocinio (e mais barato).