Guides

AI agent skills: what they are and how to write one

AI agent skills just became an open standard. Learn what a skill is, how it differs from a tool, and how to write one your agents will actually use.

S

SelfAgentic Team

7 min read
Black-and-white close-up of drill bits, a drill chuck and other metal tools spread across a workbench.

On October 22, the Agentic AI Foundation announced that Anthropic had contributed Agent Skills to the foundation, alongside new projects from OpenAI, Hugging Face and Alibaba. That puts AI agent skills under shared, open governance, so if you're deciding how to teach agents your team's way of doing things, this is a good week to learn what a skill is and how to write a useful one.

In short, a skill is a folder with a text file called SKILL.md that tells an agent how to do one specific job your way. The agent keeps a short description of every skill it has and opens the full instructions only when a task matches. You write the procedure once, and every run that needs it follows the same steps.

What are AI agent skills?

The Agent Skills overview calls them "a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows." The only required file is SKILL.md, which opens with a short header holding a name and a description, followed by plain-language instructions. The folder can also hold scripts the agent can run, reference documents and templates.

Anthropic's original engineering post on Agent Skills, published in October 2025, compares writing a skill to putting together an onboarding guide for a new hire. A model already knows how to write a polite email. It doesn't know that your refund replies quote the order number in the first line, never promise a date, and go to a person when the amount is large.

Skills load in stages, which the Agent Skills specification calls progressive disclosure. Tokens, in the list below, are the chunks of text a model reads and is billed by.

  1. At startup, the agent reads only the name and description of each installed skill, roughly 100 tokens per skill.
  2. When a task matches a description, the agent loads the full SKILL.md. The spec recommends keeping it under 5,000 tokens and 500 lines.
  3. Scripts, reference files and templates load only when the instructions call for them.

So a team can keep many skills installed without paying for all of them on every run. The catch is that the description carries most of the weight.

The October announcement matters mainly for portability. A skill is a folder of text and scripts, and the foundation now holds the format next to projects like MCP and AGENTS.md. A procedure written for one skills-compatible agent has a fair chance of working in another, though you should still test it.

Agent skills vs tools: what's the difference?

People mix these up. A tool is access: the ability to act in an outside app, such as posting in Slack or editing a Google Doc. A skill is know-how: the steps, rules and checks for one particular job.


Skill

Tool

What it gives the agent

Know-how for one job

Access to an outside app

Example

How to write your weekly investor update

Permission to edit Google Docs

What a bad one causes

Wrong or inconsistent work

A wrong action in the real world

How you control it

Review and test the instructions

Permissions and approvals

An agent with a Slack tool and no skill can post, but doesn't know what a good status update looks like. Give it the skill without the access and it knows what to write but has nowhere to send it. SelfAgentic treats these as two decisions: skills are capabilities you teach an agent, and connecting a tool is separate from authorising a particular agent to use it.

How to write an agent skill: a worked example

Say a three-person team runs support for a small online store, and refund emails eat the founder's mornings. Each reply needs the order looked up, the policy applied and a tone that fits the brand. Here's how they could turn that into a skill.

  1. Do the task once with the agent and correct it as you go. The Agent Skills best-practices guide recommends exactly this: finish a real task in conversation, then pull the reusable pattern out of it. Your corrections are the most useful raw material.
  2. Name it and describe it. The name might be refund-reply (lowercase letters, numbers and hyphens, up to 64 characters). The description could read: "Drafts replies to refund requests using the store's 30-day policy. Use when a customer asks for a refund, a return or a chargeback." It says what the skill does and when to use it, which is what the spec asks for.
  3. Write down the steps the agent would otherwise get wrong. Look up the order, check whether it falls inside 30 days, put the order number in the first line, never promise a refund date, and above a set amount, draft the reply and flag it for a person instead of sending it.
  4. Add a gotchas list. The guide calls this the highest-value content in many skills: facts that defy reasonable assumptions. For this team, that might be that orders from their old storefront use a different ID format.
  5. Add a short reply template. Agents copy a concrete structure more reliably than they follow a paragraph describing tone.
  6. Run it on ten past refund requests and compare the drafts with what the founder sent. Each correction becomes a new gotcha.

The policy and thresholds are made up for the example. What carries over is the guide's test for every line: "Would the agent get this wrong without this instruction?" If the answer is no, cut the line.

Where agent skills fall short

The most common failure is a vague description. The spec's own example of a poor one is "Helps with PDFs." An agent reading that can't tell when the skill applies, so it either ignores it or loads it for the wrong job.

Skills that try to cover everything cause a different problem. The best-practices guide warns that overly comprehensive skills "can hurt more than they help," because the agent can end up following instructions that don't fit the task in front of it.

Generic content is the third trap. Ask a model to write a skill from general knowledge and you get lines like "handle errors appropriately" instead of your real edge cases. A skill built from your own runbooks and past tickets will do better.

Trust is the fourth issue. A skill can include scripts the agent runs, and Anthropic's post warns that malicious skills "may introduce vulnerabilities in the environment where they're used or direct Claude to exfiltrate data and take unintended actions." Its advice is to install skills only from trusted sources and to audit anything else, scripts included, before use. That's the same family of risk as prompt injection in AI agents, where text the agent reads changes what it does. Treat a downloaded skill like code from a stranger.

Finally, a skill doesn't limit what an agent can do. It makes the agent more consistent, and it won't stop the agent from sending something it shouldn't. Permissions and approvals do that job. In SelfAgentic, outward-facing actions such as publishing a post or changing an ad campaign need your approval by default, whatever skill the agent is following. Portability also has limits: the spec marks one field, allowed-tools, as experimental, with support varying between agents.

FAQ

Do I need to code to write an AI agent skill?

No. The only required file is SKILL.md, a short header followed by instructions in plain language. Scripts are optional, and the guide suggests adding one when you notice the agent rebuilding the same logic on every run.

How long should a SKILL.md file be?

The specification recommends keeping it under 500 lines and about 5,000 tokens. Move longer reference material into separate files and tell the agent when to open each one, for example "read the API errors file if the request fails."

What's the difference between a skill and a prompt?

You type a prompt into one conversation. A skill is saved, loads automatically when a task matches its description, and can bundle scripts, reference files and templates, so the same procedure applies on every run.

Who maintains the Agent Skills standard now?

Anthropic created the format and contributed it to the Agentic AI Foundation in the October 22, 2026 announcement. The standard is open to contributions, and development happens in public.

Where to start

Pick the job you correct your agents on most often. Do it once with an agent, write every correction into a skill with a sharp description, a gotchas list and a template, and test it on real past cases before you trust it. Decide tool access and approvals separately from the skill itself.

If you'd like to teach skills to a team of agents that still asks before it posts anything, you can try SelfAgentic.

Keep reading

Ready to build your AI team?

See how a team of agents handles real work, and checks with you before anything goes out.

Free to start. No credit card required.