AI
Claude Code Skills: Author On-Demand Procedures
August 20269 min read
A Claude Code skill is a folder containing a SKILL.md file whose frontmatter has a name and a description and whose body holds instructions. The description tells the model when the skill applies, so Claude can invoke it automatically. A skill can also bundle helper scripts and reference files, giving the agent a packaged, reusable procedure it reaches for on its own.
Progressive disclosure loads skills in layers so many can be installed cheaply. At rest, only each skill's name and description occupy context. When the description matches the current task, Claude loads that skill's full SKILL.md body. Any extra files or scripts the skill references are read only when the steps actually call for them, keeping even large skills light.
The description is the only text Claude sees when deciding whether a skill applies, so write it in trigger terms: state both what the skill does and when to use it, using the words a user would actually say. A specific description like generate release notes when the user asks for a changelog fires reliably, while a vague label leaves the skill idle.
A skill is model-invoked and runs inline in your main context, so it suits know-how the agent should apply on its own. A subagent runs in a separate context window and returns only a summary, so it suits heavy work you want isolated from the main conversation. They compose: a skill can describe a procedure that delegates a bulky part to a subagent.
A skill runs its instructions and any bundled scripts inside your session, so an untrusted skill is code you are choosing to execute. Read the SKILL.md and inspect any scripts before installing a third-party skill, the same way you would vet a dependency, because a malicious description can lure the model into running something you did not intend.
Key Takeaway
Claude Code skills are folders containing a SKILL.md file whose description tells the model when to use them. Unlike slash commands, skills are invoked automatically: Claude reads the short descriptions, loads a skill's full instructions only when relevant, and can pull in bundled scripts and reference files, giving the agent reusable know-how without permanently filling its context window.
There is a limit to how much you can cram into a CLAUDE.md before it becomes noise the model skims past. Some knowledge is only relevant occasionally, such as how your team cuts a release, how to run a specific migration, or the exact steps for a gnarly deploy, and paying context for it on every turn is wasteful. Skills solve this by packaging that knowledge so it loads only when it is actually needed.
This guide explains what a Claude Code skill is, how progressive disclosure keeps it cheap, how to author a good SKILL.md, and how skills differ from slash commands and subagents. The result is an agent that reaches for the right procedure on its own, without you re-explaining it every time.
A skill is a directory with a SKILL.md file at its root. The frontmatter carries a name and a description; the body holds the instructions, and the folder can also bundle helper scripts and reference documents. Skills live in a project's .claude/skills/ folder, under your home directory for personal use, or arrive packaged inside a plugin.
The mechanism that makes skills scale is progressive disclosure. Claude does not load every skill in full; it works in layers:
The description field is the most important line in the whole skill, because it is the only thing Claude sees when deciding whether the skill applies. Write it to describe both what the skill does and when to use it, using the words a user would actually say, or the skill will sit unused while the model improvises.
A compact skill that generates release notes might look like this:
---
name: release-notes
description: Generate release notes from merged PRs since the last tag. Use when the user asks for a changelog or a release summary.
---
# Release notes
1. Run: git log $(git describe --tags --abbrev=0)..HEAD
2. Group commits by type (feat, fix, chore).
3. Write one short summary per group, in past tense.
4. Link each PR number. Omit any empty groups.Write the description in trigger terms, not marketing terms. A description like generate release notes from merged PRs since the last tag, use when the user asks for a changelog, will fire at the right moment, whereas a vague release helper leaves Claude guessing and the skill idle.
Skills are one of three ways to package reusable behavior, and they overlap enough to confuse. The distinction is who triggers the behavior and where it runs.
Because a skill is just a folder, skills travel well. Bundle several into a plugin and a whole workflow becomes installable in one step, which is how community skill collections are distributed. Anthropic's Superpowers plugin, for example, packages a brainstorm, plan, implement, and review pipeline as a set of skills the agent invokes in sequence.
For a team, this means a shared skill library encodes how you actually work, including your review standard, your deploy steps, and your testing discipline, so every engineer's agent behaves consistently instead of each person re-teaching the same procedure to their own session.
A skill you install runs its instructions and any bundled scripts inside your session, so a skill from an untrusted source is code you are choosing to execute. Read the SKILL.md and inspect any scripts before installing a third-party skill, the same way you would vet a dependency, because a malicious description can lure the model into running something you did not intend.
Skills degrade the same way documentation does, silently, as the code they describe moves on. A little discipline keeps them trustworthy.
Skills are how you give an agent lasting, on-demand expertise without drowning it in context. Start by turning your most-repeated procedure, the one you explain to every new session, into a single well-described SKILL.md, confirm it fires when you expect, and grow the library from there. Done well, your agent stops needing to be taught and starts already knowing.