Skills: reusable procedures for agents
A folder with instructions, and optionally scripts and references, that teaches the agent one specific kind of task. It is only loaded when needed.
Before you start
- AGENTS.md: persistent project instructionsTechnique
A Markdown file at the root of the repository that tells the agent how your project works: commands, conventions, and how to check changes. It is a guide, not a control mechanism.
Published
Key idea: if
AGENTS.mdis what the whole team needs to know, a Skill is the manual for one specific job. The agent only sees its name and description until it needs it; then it loads the full manual.
The problem
Over time you find procedures the agent should always follow the same way: preparing release notes, adding an endpoint, reviewing a migration. If you put all of them in AGENTS.md, the file grows out of control and the agent loads the release procedure even when it is only fixing a typo.
How it works
A Skill is a folder with a SKILL.md file. According to the open Agent Skills specification, that file starts with two required fields, name and description, followed by the instructions in Markdown. Optionally, the folder can include scripts/ (code the agent can run), references/ (supporting documentation), and assets/ (templates or data).
The key is progressive loading:
- At the start, the agent only sees the name and description of each available Skill. They take up very little space.
- When a task matches the description —or when you invoke the Skill by name— it loads the full
SKILL.md. - If the procedure calls for it, it reads the references or runs the scripts in the folder.
That way you can have many Skills without filling the context: you only pay for the one you use.
That is why the description matters most. It is the only thing the agent sees when deciding whether the Skill applies, so it must say what the Skill does and when to use it, using the words that would appear in a real request.
Practical example
The location depends on the client. Claude Code, for example, looks for project Skills in .claude/skills/:
.claude/
└── skills/
└── release-notes/
└── SKILL.md
Contents of SKILL.md:
---
name: release-notes
description: Writes release notes from Git commits. Use it when someone asks for release notes, a changelog, or a summary of changes for a release.
---
# Release notes
1. Read the commits since the last tag (`git log <tag>..HEAD`).
2. Group the changes into: breaking changes, new features, and fixes.
3. Write each item for the people who use the project, not the people who build it.
4. Don't invent changes: each item must match a commit.
5. If there is no previous tag, ask where to start.
The folder name matches name, as the specification requires. And the description includes the words someone would use when asking for it: “release notes”, “changelog”.
Skill, AGENTS.md, or tool?
| If it is… | Use… |
|---|---|
| A rule that applies to almost every task | AGENTS.md |
| A procedure for one kind of task | A Skill |
| A new capability (querying an API, a database) | A tool or an MCP server |
A Skill can explain how to use a tool, but it does not install it or grant it permissions.
Common mistakes
- Vague descriptions. “Helps with releases” doesn’t tell the agent when to use it. Be specific about what it does and when it applies.
- Overly broad descriptions. A Skill that “helps with code” will trigger where it shouldn’t.
- One-line Skills. If it fits in one sentence and always applies, it belongs in
AGENTS.md. - Scripts with too much power. A Skill’s scripts run with the agent’s permissions. Review them like any other code.
- Installing third-party Skills without reading them. They are instructions and code the agent will follow. Read them first, as you would a dependency.
When to use it
When you repeat the same procedure several times, or when AGENTS.md starts filling up with steps that only apply to one kind of task. Start without scripts or references: a clear SKILL.md is usually enough.
Next step
Everything so far gives the agent information. The next block is about what the agent can do: Tools and permissions.
Sources
Accessed on 2026-10-05.
- Agent Skills: Specification.
- Extend Claude with skills, Claude Code documentation.
Related content
- Tools and permissionsTechnique
What a tool is, how an agent uses one, and how to decide what it can do without asking, what needs your approval, and what is off limits.
Published - Subagents and delegationTechnique
When it makes sense to split a task among several agents with their own context, how to give them clear assignments, and how to bring their results together without losing control.
Published