Skill
Skill
A teachable capability, loaded on demand into an existing session
✓ Building BlocksWhat is a Skill
A Skill is a teachable capability bundled as a folder: instructions, scripts, and reference files, kept completely out of the agent's context window until the task at hand actually calls for it. Instead of every capability being loaded up front, a Skill is pulled in only when relevant, through a short description the harness always keeps visible so it can decide when to reach for the rest.
This is the core idea behind progressive disclosure. The agent's context budget is finite, so Skills let a harness like Claude Code carry dozens of specialized capabilities without paying the context cost of all of them at once. Only the description is always resident. Everything else, the full instructions, the scripts, the reference material, loads in layers, and only the layer the task actually needs.
Skills work best for known, repeatable workflows: a deploy process, a review checklist, a specific API's conventions. Cases where the same expertise gets reused across many sessions instead of being re-explained every time. A Skill does not spawn a new process or a new agent. It changes what the current agent knows, in the current session, nothing more.
of a real skill on this machine never enters context unless the task actually calls for it. Measured, not estimated, from .claude/skills/image-editor/SKILL.md as it sits on disk right now.
Multiply this across a real install with dozens of skills. The purple bar is what every session pays for, every single time, whether that skill gets used or not. The gold bar only gets paid once, and only by the one task that actually opens the folder.
Source: ~/.claude/skills/image-editor/SKILL.md, 5,527 characters, read on this machine 2026-08-18. Token counts are the standard ~4 chars/token estimate (name + description field vs. full file).
--- name: image-editor description: | Local image editing, convert format (PNG/JPG/WEBP), resize, compress, crop, composite onto a solid background (fixes transparent-PNG upload bugs), and extract frames from an animated GIF/WEBP. Pillow-based, no external service, no API key. Use whenever an image needs to be turned INTO webp (or any other format), shrunk, cropped, or pulled apart from an animation, as opposed to generated from scratch (that's nano-banana or generate-image) or captured from a live screen (record-video). TRIGGERS, use this skill when: - "convert this to webp" / "turn these into webp" / "make this a png" - "resize this image" / "shrink this" / "compress this image" - "crop this image" / "crop to just the logo" ... 2 more trigger lines ... allowed-tools: Bash ---
Everything above the line is what the model reads at session start. Everything below allowed-tools, the actual instructions and workflow, is the rest of the file that only loads once a real task matches the description.
The step most people miss: every installed skill's description is injected into the system prompt at session start, before any user message. That is the only part of an unopened skill the model ever sees. The full SKILL.md body only enters context the moment the model actually calls the tool.
Only the description column stays in context by default. Purple marks what the session always carries. Gold marks the moment a folder actually opens. Everything past SKILL.md loads on a second, even more selective pass, only if the instructions themselves point at it.
SKILL.md is the only file the harness reads by default. scripts/ only gets opened when the instructions inside SKILL.md point at it, on a second, even more selective pass.
Build your own agent skills, not just prompts.
We design, build, and ship the Claude Code skill libraries production teams actually run on.
Talk to AY Automate ↗