# Agent Skills: packaging know-how for AI assistants
Table of Contents
AI assistants are good at answering questions and writing text. But when they have to follow a precise procedure - the way a given company prepares a report, applies a file-naming convention, or fills in a form - they need to be guided every time. Usually you end up re-pasting the same instructions into every conversation, or building a custom assistant for each task. On 16 October 2025 Anthropic, the company behind the Claude assistant, introduced Agent Skills: a way to package those instructions, and any scripts, into reusable folders that the assistant loads only when they’re needed.
Behind the technical name there’s a simple idea, and it matters to anyone who uses AI for recurring work. It’s worth understanding.
First, a note on terms
Here agent means an AI assistant that doesn’t just reply, but can use tools and take several steps to complete a task: read a file, run a small program, produce a document. Another useful term is context: everything the assistant “has in front of it” while working, meaning the user’s request plus the instructions and information loaded at that moment. Context has limited room - the more you cram in, the more scattered and expensive it gets. Keeping that limit in mind helps explain why Skills are built the way they are.
The problem: every procedure rewritten from scratch
Over time an organization builds up a store of “how we do things here”: the standard format for an invoice, the steps to produce a monthly report, the style rules for a piece of writing, the exact sequence to package a piece of software. This is procedural knowledge, often not written down anywhere in an orderly way.
To get an AI assistant to follow one of these procedures there are two options, both awkward. The first is pasting the instructions into the conversation every time: it works, but it’s repetitive and easy to get wrong, and it eats up precious room in the context. The second is building a dedicated assistant for each single task: precise, but it takes technical work and has to be redone for each of the many procedures. Either way, the know-how stays hard to reuse and hard to share.
Agent Skills exist to remove exactly this friction: write a procedure once, in an orderly format, then call it up when needed without pasting it again.
What a Skill is: a folder with instructions inside
In practice a Skill is simply a folder. Inside there’s one required file called SKILL.md and, if needed, other files: reference documents, examples, or small ready-made scripts.
The SKILL.md file is written in a format a person can read too. At the top it has a few lines of metadata in YAML - a plain way to note “label: value” pairs - with at least a name and a description of what the Skill does. Below that, in Markdown (the same plain text used in many note files), come the actual instructions: the steps to follow, the conventions to respect, the examples. In short, it’s a tidy instruction sheet. Anthropic uses a neat analogy: building a Skill is like putting together an onboarding guide for a new hire.
A minimal structure looks like this:
monthly-report/ SKILL.md # what it does and how, step by step example.md # a worked case, for reference generate.py # an optional script for the repetitive stepsThe fact that it’s a folder of text files has a real practical upside: a Skill can be saved, version-controlled the way code is, and handed to a colleague by simply sharing the folder.
The trick: loading information in layers
If every Skill were loaded in full and always, you’d be back to the problem of a cluttered context. Agent Skills avoid this with progressive loading - in layers - so the assistant only has in front of it what it needs at that moment.
It works in three levels:
- At startup the assistant only knows the name and description of each available Skill. A few lines each: just enough to know that the Skill exists and what it’s for.
- When the user’s request matches a Skill, the assistant opens and reads the full contents of that
SKILL.md, with all the instructions. - If the
SKILL.mdpoints to other files - a detailed document, a long example - those are opened only when actually needed.
The result is that you can keep many Skills on hand, even sizeable ones, without weighing down every conversation. The assistant “scans the index” and reads the right chapter only when it needs to, instead of keeping every manual open on the desk.
There’s a second useful element: a Skill can include ready-written scripts, for example in Python. For repetitive, mechanical steps, the assistant can run that code instead of improvising the procedure every time, much like relying on an automated timer for a task that would otherwise have to be kicked off by hand. For certain tasks it’s more reliable and cheaper to run a tested script than to ask the model to redo everything by hand.
Where they can be used
Agent Skills work in the same format across several places: the Claude app (on the Pro, Max, Team and Enterprise plans), the developer tool Claude Code, the developer-facing API, and the Agent SDK, the kit for building your own agents. The same package, then, moves from one environment to another without being rewritten.
At launch Anthropic made available a few ready-made Skills for very common office tasks: creating Excel spreadsheets with formulas, PowerPoint presentations, Word documents, and fillable PDF forms. There’s also a special Skill, the skill-creator, that helps build new ones in a guided way: it asks about your workflow, prepares the folder structure, and sets up the SKILL.md file. A way to start without facing a blank page.
On availability, to be fair, not everything is identical everywhere: use via the API, for instance, relies on the code-execution feature, still in beta, and in enterprise accounts an administrator has to enable the feature for the organization. Small details, but useful ones so you’re not caught off guard.
Why it helps anyone with recurring procedures
The real value isn’t in a single feature, but in the shift in work it makes possible. A procedure written well once stops being an instruction to repeat out loud and becomes a reusable piece: you call it up when needed, you can improve it over time by editing a file, you hand it to a colleague by sharing a folder. In practice it’s a way to capitalize on the know-how that today lives in people’s heads or scattered across different notes.
For anyone running systems and infrastructure the comparison is immediate: it’s the same logic by which a repetitive procedure is better put in a script or a playbook than run from memory every time. Here the “playbook” is written so an AI assistant can follow it, with the option to include the code for the mechanical steps too.
Mind where they come from
A word of caution, one Anthropic itself highlights. A Skill can contain instructions and code that get executed, and it can tell the assistant to access external resources. So they should only be installed from sources you trust, and ones of uncertain origin are worth inspecting first: what the files contain, whether the code connects to external services, whether there are instructions that might send data somewhere it shouldn’t go. It’s the same caution you’d use before running a script downloaded from the internet. Convenience doesn’t remove the responsibility to check.
In short
Agent Skills, introduced by Anthropic on 16 October 2025, are folders that gather reusable instructions and scripts for AI assistants, built around a plain-text SKILL.md file. They solve a concrete, everyday problem: not having to rewrite the same procedures every time. Layered loading lets you keep many of them on hand without cluttering the context, and the option to include scripts makes repetitive steps more reliable. They work in the app, in Claude Code, via the API, and with the Agent SDK. How widely used they’ll become is for the coming months to tell; the underlying idea, though, is clear and sensible: put know-how in an orderly, reusable format, instead of repeating it out loud every time.
