Agent Skills: the SKILL.md folder format for giving AI agents procedural knowledge

What problem Agent Skills solves, and for whom

A general-purpose agent knows how to write code and answer questions, but it does not know how your team reviews a contract, how your pipeline names its output files, or which template your slide decks must follow. The README frames this as a context problem: agents "often don't have the context they need to do real work reliably." Agent Skills is the packaging answer. A skill is a folder with a SKILL.md file at its root, holding metadata and instructions, plus optional scripts, references and assets. The folder is portable and version-controlled, so the same procedure can be checked into a repository, reviewed in a pull request, and reused across clients. The audience is anyone who has written the same set of instructions into a chat window more than twice: platform teams, data teams, legal operations, and individual developers who want their agent to follow a house style. It is not aimed at people who want a single prompt saved somewhere. It is aimed at people who want a procedure to travel.

Progressive disclosure: how a skill reaches the model's context

The README describes loading in three stages. Discovery happens at startup, when the agent reads only the name and description of each available skill. Activation happens when a task matches a description, at which point the agent reads the full SKILL.md into context. Execution follows, with the agent optionally running bundled code or loading referenced files. The design point is context economy. Because only names and descriptions sit in the window by default, an agent can hold many skills without paying for their full text. The cost is that activation depends entirely on the description field. A vague description means the skill never fires; an over-broad one means it fires on tasks it was not written for. That is a real authoring burden, and the README does not offer guidance on how to test whether a description triggers correctly. The repository does ship a skills-ref directory, which the layout suggests is the reference implementation for working with skills, though the README itself does not document its command line.

Installing and using your first Agent Skills folder

The README does not give a package-manager install command for the specification itself. What it gives is the folder shape, and the getting-started section points to the documentation site, the specification page, and an examples repository. The package.json in the repository defines one script, dev, which runs the documentation site locally with Mintlify. If you want to read the docs offline, that is the entry point:

npm run dev

That command changes into docs and runs npx mint dev, so you need Node and network access for npx to fetch Mintlify. For the skill itself, create the directory and the required file by hand. The README shows the layout with SKILL.md as required and scripts, references and assets as optional:

my-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/

The minimum content of SKILL.md is metadata (name and description) plus instructions. The README states the metadata requirement (name and description, at minimum) and leaves format details to the specification page. Once the folder exists, the client that supports the format discovers it and reads the name and description at startup. To check that your description is doing its job, start a session and give the agent a task that should match it, then watch whether the full instructions get pulled in.

What the format does not guarantee

Agent Skills standardizes packaging, not behaviour. Nothing in the README promises that an agent will follow a skill's instructions, that activation is deterministic, or that two clients will interpret the same SKILL.md identically. The specification page is where format details live, and the README does not reproduce them. There is also no versioning scheme described for skills themselves, no dependency mechanism between skills, and no documented rollback if a skill change makes an agent behave worse. If your procedure must run the same way every time with an auditable result, a skill folder is a weaker guarantee than a script with a test suite; the skill can point at that script, but the agent still decides whether to run it. The format is also the wrong tool when the knowledge is a one-off. Writing a folder, a description and a metadata block to encode a single prompt costs more than pasting the prompt. Finally, the README notes that support comes from compatible clients and links to a client showcase, which means adoption is a property of the ecosystem, not of this repository.

How Agent Skills differs from MCP and from plain system prompts

The closest comparison in the agent tooling space is the Model Context Protocol. MCP connects an agent to a live system: a server exposes tools and resources, and the agent calls them at runtime. Agent Skills does not connect anything. It is a folder of text and files that gets read into context, and any code it runs is code you bundled yourself. The practical difference shows up in what you maintain. An MCP server is a process you deploy, monitor and version; a skill is a directory you commit. Conversely, MCP gives you typed tool calls with defined inputs and outputs, while a skill gives you prose instructions the model interprets. The other comparison is the system prompt. A system prompt applies to every turn of a session and is usually written by the client's operator. A skill loads only when its description matches, and it is written by whoever owns the procedure. If your need is a live connection to an internal API, MCP is the right layer. If your need is to hand an agent a documented procedure, Agent Skills is the lighter one.

Maintenance cost, licence split and upgrade path

The repository was last pushed on 2026-08-09, so it is not archived and has recent activity. The repository publishes no releases, which means there is no tagged version to pin against; consumers track the main branch or the published specification page. That raises the cost of staying current: a format change arrives as a commit rather than a version bump, and the README does not describe a deprecation or migration policy. The licence is split, and this matters for anyone repackaging the material. Code in the repository is Apache-2.0, while documentation is CC-BY-4.0, and the README says to see individual directories for details. So copying the reference tooling into your product and copying the prose specification into your own docs are two different acts with two different sets of obligations. Attribution is the obvious one for the documentation side. This is not legal advice; read LICENSE and the CC-BY-4.0 text before you redistribute either.

Editorial conclusion

Adopt Agent Skills if you maintain repeatable procedures that several people or several agent clients need to run the same way, and if you are willing to keep those procedures in version control. Do not adopt it if your task is a one-off prompt, if your agent client does not implement the format, or if you need a guarantee that the agent will follow the instructions exactly. Before committing, verify three things: that your client loads SKILL.md files at all, that the name and description fields you write are specific enough to trigger activation on the right tasks, and that any scripts you bundle run under the permissions your agent has.

Frequently asked questions

Official sources

1. agentskills/agentskills on GitHub
2. Issues
3. License: Apache-2.0
4. Project website
5. README