What are agent skills?

An agent skill is a folder of instructions, with a SKILL.md file, that an AI agent loads only when a task needs it. Each skill teaches one kind of task. The file starts with a name and a description. The agent sees those at the start of every session, and reads the rest when a task matches.

A skill is not a tool. A tool is a function the model calls to do something: search, read, write. A skill is instructions the model reads to know how something is done. Nor is it a system prompt, which is loaded in full on every turn whether it is needed or not. How tools and agents differ is in MCP, AI tools and agents.

The format is open. The Agent Skills specification defines a skill as a directory with a SKILL.md file at its root: YAML front matter, then Markdown. Two fields are required:

• name: up to 64 characters of lowercase letters, numbers and hyphens, the same as the folder’s name.
• description: up to 1,024 characters, saying what the skill does and when to use it.

Four more are optional: license, compatibility, metadata, and an experimental allowed-tools. The body has no required shape. Beside it, a skill may carry scripts/ the agent can run, references/ it can read, and assets/ such as templates.

Anthropic introduced Agent Skills in October 2025, and in December 2025 published the format as an open standard, now at agentskills.io. Its engineers put the idea in one line: “Building a skill for an agent is like putting together an onboarding guide for a new hire.”

A skill loads in three levels. The specification says it plainly: “Agents load skills progressively, pulling in more detail only as a task calls for it.”

• Metadata. The name and description of every installed skill, about 100 tokens each, loaded at startup.
• Instructions. The body of SKILL.md, read when the agent decides the skill applies. The specification recommends under 5,000 tokens and under 500 lines.
• Resources. Reference files, read only when the instructions point to them. A script runs, and only its output enters the context, not its code.

The first level still costs something, so agents budget it. OpenAI’s documentation says Codex keeps the initial list to at most 2% of the model’s context window by default. With many skills installed, it shortens their descriptions first.

That is why the description carries the weight. It is the only part the agent sees before it decides. A description that names an area but not when to use it is the specification’s example of a poor one.

All three shape what a model does. They differ in what they are, and in when they take up the context window:

• A system prompt is text loaded on every turn. It suits what has to hold for the whole conversation, and it costs its whole length each time.
• A tool is a function with a name, a description and parameters. Its definition is sent while the tool is enabled, and the model calls it to act or to fetch something.
• A skill is instructions, and sometimes scripts and reference files. It costs a line until a task needs it, then its body.

Use a skill for how a task is done here, such as how a supplier is scored or the steps of a release. Use a tool for what the model has to do. Keep in the system prompt only what must hold on every turn.

A rule with no exceptions belongs in neither a prompt nor a skill. Put it in the permissions or the platform, where the model cannot decide it does not apply.

The folder format is shared, so one skill works in several agents. Where each one looks differs:

• Claude Code reads .claude/skills in a project and ~/.claude/skills for a user, per Anthropic’s documentation.
• OpenAI Codex scans .agents/skills in every folder from where it starts up to the repository root, per its documentation.
• GitHub Copilot reads .github/skills, and .claude/skills and .agents/skills too. Google Antigravity, Mistral Vibe and Devin read .agents/skills, as curio’s guide to coding agents lists them.

Some agents add fields of their own on top of the standard ones. A team that commits its skills to a repository gives every agent that works there the same instructions, reviewed like code.

• A vague description. The agent never loads the skill, or loads it for everything.
• A body that tries to hold everything. It costs its full length on every use. Move the detail into reference files, one level down.
• A skill that describes last year’s system. The agent follows it with confidence. A skill needs an owner and a review, like code.
• A rule that must always hold. A skill loads when the agent decides it applies, so it guides and does not enforce.
• A skill from someone you do not know. A skill can carry scripts and instructions to call tools. Anthropic warns that “a malicious Skill can direct Claude to call tools or run code in ways that don’t match the Skill’s stated purpose.” Read every file before you install one, as you would with software.
• Instructions fetched at run time. A skill that pulls text from an outside address can pull in instructions an attacker wrote. That is prompt injection by another route.

• Does the description say what the skill does and when to use it, in the words a request would use?
• Is the body short enough to read whole, with the detail in reference files?
• Who owns it, and when was it last checked against the system it describes?
• What can its scripts reach: files, the network, credentials?
• Does it come from a source you trust, and did someone read all of it?
• Is anything in it a rule that should be enforced somewhere else?

In Curiosity Studio a skill is a Markdown document stored in the graph: a name, a one line description, a category and a body. It is one document rather than a folder, with no scripts of its own, and any assistant can carry skills.

The documentation describes what a chat sees. An Available skills section lists each skill’s name and description, sorted by name, so the prompt stays the same from turn to turn. The bodies stay out until the model reads one with read-skill. A skill a chat has used stays in that conversation.

Sudo, the admin assistant, reads a built-in skill such as add-code-endpoint or create-ai-tool before he writes anything. Editing a skill is how you teach him a house convention, and your skills export with the rest of your configuration. The paper Working with Sudo has a chapter on it.

Coding agents get the same skills through curio. curio skills install writes one skill into the agent’s skills folder. It explains how to work on the workspace through curio, and lists Sudo’s skills, which stay on the workspace. The agent reads each one with curio skills show, so it follows the version your workspace runs.