Agent Skills: What They Are and How They Load

An agent skill is a folder with a SKILL.md file that teaches an AI agent how to do one kind of task. The file holds a name, a description and instructions, and the folder can add scripts, reference notes and templates. The agent reads only the short description at first and loads the full instructions when the task calls for it. Checked 31 October 2026.

At a glance

What a skill is

The Agent Skills site calls it "a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows." At its core, a skill is a folder with a SKILL.md file. The file has metadata (a name and a description, at minimum) and instructions for how to perform a task. A skill can also bundle scripts, reference materials and templates.

Claude Code's glossary describes it from the user's side: a SKILL.md file containing instructions, knowledge or a workflow that Claude adds to its toolkit. Claude loads a skill automatically when relevant, or you call it directly with /skill-name.

A tiny skill looks like this:

---
name: release-notes
description: Draft release notes from merged pull requests. Use when asked for a changelog or release summary.
---

1. List merged pull requests since the last tag.
2. Group them as New, Improve, Fix.
3. Write one plain sentence per item.
4. Do not mention ticket numbers.

The folder might also contain scripts/collect-prs.sh and references/style.md, which the instructions point to when needed.

Progressive disclosure: why skills are cheap

The specification says agents load skills progressively, pulling in more detail only as a task requires.

This is the point of the design. Claude Code's docs put it plainly: a skill's body loads only when it is used, so long reference material costs almost nothing until you need it. That sets skills apart from CLAUDE.md, which loads in full every session. Claude Code's guidance is to keep SKILL.md under 500 lines and move detail into separate files. A multi-step procedure or something that matters for only part of the work belongs in a skill, not in CLAUDE.md.

The fields

The open spec defines six frontmatter fields. Claude Code accepts more.

Claude Code adds options such as when_to_use (which counts toward a 1,536-character cap on the combined listing text) and controls over who can invoke a skill. If you plan to use a skill outside Claude Code, stick to the six spec fields, because other tools may reject unknown keys.

The description is the most important sentence in the folder. The agent decides whether to load the skill by reading it. Put the key use case first, say what the skill does, and say when to use it. A vague description means the skill never fires or fires at the wrong time.

Skills in Claude Code

Claude Code ships bundled skills that you invoke the same way as your own. The docs list examples such as /doctor, /code-review, /batch, /debug, /loop and /claude-api. They are prompt-based: they give Claude detailed instructions and let it use its tools. Most built-in commands, by contrast, run fixed logic.

Places a skill can live:

Custom commands have merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and work the same way. Existing command files keep working. Skills add a folder for supporting files, frontmatter that controls whether you or Claude invokes them, and the option to run in a subagent.

After a long session is compacted, Claude Code re-attaches the most recent invocation of each skill within a token budget: the docs say invoked skill bodies are re-injected, capped at 5,000 tokens per skill and 25,000 tokens in total, with the oldest dropped first.

Skills compared with its neighbours

Skills and servers are often confused. A server gives an agent a new ability, such as posting to a tracker. A skill gives it a method, such as how your team writes release notes. They work well together: a skill can tell the agent to use a certain server's tools in a certain order. See skills vs MCP and subagents vs skills.

What skills are good for

• Team procedures. Release notes, pull request descriptions, incident write-ups.
• Document handling. The skill pattern is used for office-file jobs; see document skills.
• Design and code style. Rules that matter only when you work on the front end; see frontend design skill.
• Audits. A repeatable SEO or accessibility check; see our SEO page audit skill.
• Support drafting. A fixed way to read a ticket and write a reply; see the support reply drafting skill.

Browse the catalogue at skills, and see how to write a Claude Code skill for a build walkthrough. The skill creator skill helps you scaffold one.

Risks and habits

A skill can include scripts, and a script runs with your permissions. Read any skill you did not write before you use it, especially its scripts/ folder, and remember that instructions in a skill steer the model. Prefer skills from a source you trust, pin them in version control and review changes. Keep descriptions honest: a skill that claims to handle everything will load when it should not and waste context.

Quality habits: keep SKILL.md short, give the agent concrete steps, link to reference files instead of pasting them, and test the skill on a real task before sharing. Update it when the process changes, so it does not teach an old method.

Our take

Skills solve a real problem: instructions that are too long or too specialised to carry in every session. The three-stage loading is a sound design, and an open format means the folder you write for one agent can work for another. Their risk is the one every installable has: someone else's instructions and scripts, running in your project. We describe the format from agentskills.io and Claude Code's docs and have not tested individual skills here.