--- title: "15 — Agent Skills — From Bloated Prompts to Just-in-Time Knowledge" uid: agent-skills tags: ["llm", "tools", "ai", "prompting", "roadmap:frontend", "agent-skills"] excerpt: "A skill moves knowledge from 'always in the prompt' to 'loaded only when a task needs it' — shrinking the context window and sharpening accuracy." date: 2026-08-12T18:35:10+0000 source: https://www.aveshina.my.id/en/blog/agent-skills --- "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: ```figure ``` 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](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/](https://www.deeplearning.ai/short-courses/agent-skills-with-anthropic/) [3] roadmap.sh, "Frontend Roadmap — Skills," 2025. [Online]. Available: [https://roadmap.sh/frontend/skills](https://roadmap.sh/frontend/skills) [4] Anthropic, "Engineering Blog — Agent Skills," 2025. [Online]. Available: [https://www.anthropic.com/engineering](https://www.anthropic.com/engineering) ```quiz Q: What is a skill, in its simplest form? - A new capability the model invents at runtime - A packaged folder of instructions, optional scripts, and optional resources the model reads on demand correct: 1 explain: A skill is a packaged capability — the author did the thinking once into instructions and scripts. The model loads and follows them, it doesn't invent them. Q: Under progressive disclosure, what part of every skill stays in context all the time? - The full instructions body - The short description only - The bundled scripts correct: 1 explain: Only the one- or two-line description is always present, so the model knows the skill exists. The full body loads only when a task matches that description. Q: Why does a giant system prompt make an assistant *less* reliable, not more? - It doesn't — more instructions always help - Attention is finite; unrelated instructions dilute the signal relevant to the current task correct: 1 explain: Every extra token competes for attention. Stuffing the prompt "to be safe" dilutes the model's focus on the task in front of it, on top of being paid for on every turn. Q: A skill's instructions + scripts get sent on… - every turn, regardless of task - only the turn where a task matches the skill's description correct: 1 explain: The expensive body is loaded just-in-time. The always-on cost is just the short description; the full skill appears only when the task needs it. Q: Which reframing best captures when to prefer a skill over adding to the system prompt? - "Is this relevant to every single task, or just some?" - "Is this important enough to document?" correct: 0 explain: Knowledge relevant to every task belongs in the prompt; knowledge relevant to only some tasks belongs in a skill, loaded only when those tasks appear. ```