15 — Agent Skills — From Bloated Prompts to Just-in-Time Knowledge

"Plugins" and "tools" were how I lumped Agent Skills in with everything else and never thought about them clearly. The idea everything else hangs off: a skill moves knowledge from "always in the prompt" to "loaded only when a task needs it" [1].

Before that sentence means anything, I have to define two words I kept tripping over. When you use an AI coding assistant, there are two things you hand it over and over. The first is the system prompt — the standing instructions you give it up front ("you're a coding assistant, follow these rules, this repo's conventions are…"). The assistant re-reads that whole block on every turn, for every request. The second is the context window — the assistant's working memory, the finite scratch space it can "see" at once. Everything you send — the system prompt, your question, the files it read — has to fit inside that window, and space in it is limited.

A skill is a way to stop spending that limited space on knowledge you rarely use. Instead of leaving every how-to in the prompt forever, you park each how-to in its own little folder, and the assistant pulls in only the folder it needs, at the moment it needs it. Load it when the task shows up, not before. That single shift — from crammed-in-context to just-in-time — is the whole point.

Here's the contrast, drawn out — the same assistant, two strategies for delivering the same know-how:

That figure is the same idea in two pictures. On the left, my old habit: cram every convention into the system prompt so the assistant "knows" it on every turn — deploy steps, test commands, lint rules, forty more pages. On the right, the same knowledge lives in small folders, asleep, and only the one matching the current task ("run the test suite") wakes up and unfolds into context. Same assistant, same knowledge — different storage.

What a skill actually is

Now we can look at the folder itself. Strip a skill down and it's a packaged capability [1][2] — a folder holding three things:

• Instructions — the how-to, written as prose a model can follow ("to run the e2e suite, first build the fixtures, then…").
• Optional scripts — runnable files the instructions can call (scripts/run-tests.sh), so the model doesn't have to reinvent the steps each time.
• Optional resources — supporting files: a code snippet, a config template, a schema, a reference doc.

The important word is packaged. A skill is not a new ability the model invents on the spot. It's the model reading instructions and running scripts that somebody wrote down ahead of time. The model gets good at the task because the author already did the thinking once and stored it in the folder. It's the same move as writing good documentation for a human — except the reader is an LLM, and the docs can actually run.

This is the layer the roadmap.sh summary points at: skills let an assistant "call upon these capabilities when needed, instead of relying solely on internal knowledge" [3]. That phrasing mattered to me — instead of. It's not the model getting smarter; it's the model deferring to a loaded expertise it didn't have to carry around.

How a skill gets loaded — progressive disclosure

The design idea that makes skills cheap has a name: progressive disclosure. The name is just a fancy way of saying "reveal a little bit always, and the rest only when it's needed." It happens in two stages, in this order:

1. The description, always. Every skill ships with a short one- or two-line summary of what it's for. That description is the only part the assistant keeps in view permanently. It's how the assistant knows the skill exists and when to reach for it. The rest of the body isn't loaded.
2. The body, on demand. Only when the assistant decides a task matches the description does it load the full skill — the instructions, the scripts, the resources — into the context window for that turn.

Now do the cost math. Say I have twenty skills. The always-on cost is twenty short descriptions — a few hundred tokens. A token is roughly a chunk of text the model is billed by; think of it as a coin you spend for every bit of the window you fill. Twenty descriptions cost a few hundred coins, not twenty full how-to documents. The expensive knowledge only shows up on the turn it's used, and when that turn ends it's gone, so it doesn't sit in the window and bloat the next task. Each task pays only for what it pulls in.

Why this beats one giant prompt

I used to think the "right" way to make an assistant reliable was to write the world's most exhaustive system prompt — every convention, every gotcha, every deploy step, all crammed in so nothing could go wrong. The model that clicked is why that backfires:

• Context isn't free. Every token in the system prompt is sent on every turn. A 30-page prompt costs the same on a "fix this typo" turn as on a "deploy the service" turn. Skills let me pay for the deploy expertise only when I'm deploying.
• Attention is finite. A model buried under unrelated instructions genuinely gets worse at the task in front of it — the relevant signal is diluted by everything else [2]. Stuffing the prompt "to be safe" makes the assistant less reliable, not more.
• Updates get harder. One giant prompt is one giant file everyone edits. Skills are independent folders — I can fix the test skill without touching the deploy skill, and the two don't fight for attention.

So the giant prompt is the wrong data structure. It treats all knowledge as equally important on every turn, which is almost never true. Skills encode the right priority: most knowledge is irrelevant to most tasks, so it shouldn't be in context most of the time.

Where I see this in the wild

This isn't abstract — the pattern shows up concretely in the tooling I already use. Claude Code and Agent skills are the canonical instance: a skill is a directory with a SKILL.md (the instructions, front-matter description, optional scripts), and Claude loads it only when a task matches [1][4]. The deeplearning.ai course frames the same idea as the universal design — capabilities packaged as instructions-plus-scripts that any compliant agent can invoke, not something tied to one vendor [2]. Even on the frontend specifically, roadmap.sh lists skills alongside MCP as the two layers that let an assistant do things in a repo instead of just talk about them [3].

The unifying thread: every one of these treats the skill as a deferred capability. The assistant isn't smarter in the abstract — it's smarter at the specific task, because it just pulled in the right instructions.

How I use this

The habit these notes left me with is a small reframing. When I catch myself drafting another paragraph into the system prompt "just in case," I stop and ask: is this relevant to every single task, or just some? If it's just some — and it almost always is — it doesn't belong in the prompt. It belongs in a skill, with a one-line description that's always present and a body that loads only when the task shows up.

That one question is why skills ever felt like a separate concept instead of "more prompt engineering." They're a different storage strategy for the same knowledge — and the storage strategy is the whole reason it works.

References

[1] Anthropic, "Agent Skills," Anthropic Docs, 2025. [Online]. Available: https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills

[2] DeepLearning.AI, "Agent Skills with Anthropic," Short Courses, 2025. [Online]. Available: https://www.deeplearning.ai/short-courses/agent-skills-with-anthropic/

[3] roadmap.sh, "Frontend Roadmap — Skills," 2025. [Online]. Available: https://roadmap.sh/frontend/skills

[4] Anthropic, "Engineering Blog — Agent Skills," 2025. [Online]. Available: https://www.anthropic.com/engineering