Agent Skills: A Portable Format for Extending AI Agent Capabilities

The Problem Agent Skills Addresses

AI agents are capable of general reasoning but frequently lack the specific procedural knowledge to handle real tasks consistently. A coding agent may not know a team's internal review process. A data analysis agent may not understand which pipeline to follow for a particular dataset. Embedding that knowledge directly into system prompts is wasteful and does not scale when many contexts share the same agent.

Agent Skills treats this as a packaging problem rather than a model problem. Specialized knowledge, workflows, scripts, and reference materials are bundled into a folder called a skill, and agents load those folders on demand rather than holding all context in memory at once. The README describes this as packaging "procedural knowledge and company-, team-, and user-specific context into portable, version-controlled folders."

The SKILL.md Format and Folder Structure

Every skill is a folder. The only required file is `SKILL.md`, which must contain at least a `name` and a `description`. Those two fields are what an agent reads at startup to decide whether a skill is relevant. The full instructions in `SKILL.md` are loaded into the agent's context only when a task matches.

Optional subdirectories extend the skill beyond text instructions:

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

The `scripts/` directory holds executable code the agent may run as part of completing the task. The `references/` directory holds documentation the agent can read. The `assets/` directory stores templates and other resources. This structure is deliberately open: any additional files or directories are permitted.

The specification itself is published at agentskills.io/specification. Example skills are in the anthropics/skills repository on GitHub.

How Agents Load Skills: Progressive Disclosure

The loading mechanism is called progressive disclosure and operates in three stages. At startup, the agent reads only the `name` and `description` from each available skill. This keeps the context footprint small regardless of how many skills are installed.

When a user task arrives that matches a skill's description, the agent reads the full `SKILL.md` instructions into context. The README calls this the activation stage. Finally, the agent executes the instructions, running bundled scripts or loading referenced files as the task requires.

This design means an agent can have many skills registered without the total context cost of all of them. Full instructions load only when work calls for them. The trade-off is that the quality of the `description` field determines whether the agent activates the right skill at the right moment. A vague description causes the agent to miss relevant skills or activate the wrong one.

Installing and Using Agent Skills in Claude Code

The repository's `package.json` shows a single script:

npm run dev

This runs `mint dev` inside the `docs/` directory, which is the local preview for the agentskills.io documentation site. The repository itself is the specification and documentation host rather than a runtime package you install.

To use Agent Skills in Claude Code specifically, create a folder containing a `SKILL.md` file inside your project's `.claude/` directory or wherever your client's documentation says to place skills. The `SKILL.md` must include at minimum a `name` and `description`. Claude Code reads those fields to decide when to activate the skill, then loads the full file when a matching task appears.

The agentskills.io site documents how to create and register skills for each supported client. The specification page at agentskills.io/specification gives the complete field definitions.

Cross-Client Portability and the Open Standard

The format was originally developed by Anthropic and released as an open standard. It is not exclusive to Claude or Claude Code. The client directory at agentskills.io/clients lists the agent products and tools that have adopted the format.

This portability is the main practical argument for the format over writing agent instructions directly into a system prompt or a client-specific configuration file. A skill folder built for one agent tool can be reused with another tool that implements the same specification without rewriting the instructions.

The specification accepts community contributions. The `CONTRIBUTING.md` file in the repository describes how to get involved. The repository also contains a `.claude/` directory and a `CLAUDE.md` file, which indicates the repository itself uses Claude Code for development tooling.

Limitations and Cases Where It Does Not Apply

Agent Skills is a specification, not a runtime library. It does nothing on its own. An agent platform must implement the discovery and activation protocol for skills to work at all. If your agent client is not on the supported list, the format provides no benefit until that client ships support.

The format also makes no guarantees about execution fidelity. Nothing in the specification enforces that an agent follows the instructions in `SKILL.md` correctly. The quality of execution depends entirely on the underlying model and the agent implementation. A skill that works well with one model may produce different results with another.

Version control is a responsibility the skill author takes on manually. The format treats a skill as a folder in a repository, so tracking changes and releasing updates requires the same discipline as any other code. There is no built-in versioning or dependency resolution.

Maintenance, License, and Development Activity

The last push to the repository was on 2026-08-09. The repository is not archived. There are no GitHub releases; the specification is published directly to the agentskills.io documentation site rather than through versioned release tags.

Code in the repository is licensed under Apache 2.0. Documentation is licensed under CC-BY-4.0. Individual directories may carry different terms, so checking subdirectory-level LICENSE files before distributing skill content is worthwhile.

The repository is primarily a documentation and specification host. The `package.json` shows no dependencies other than the Mintlify documentation tool. Contributors interact through GitHub pull requests and the Discord server at discord.gg/MKPE9g8aUy.

Editorial conclusion

Agent Skills suits any team running a skills-compatible AI agent that needs repeatable, auditable workflows without baking procedural knowledge directly into the model prompt. It is the wrong choice if your agent platform does not yet support the format, since the specification only benefits users of clients that implement the discovery and activation protocol. Before adopting it, check the client listing at agentskills.io/clients to confirm your agent tool supports the format. The format is licensed Apache 2.0 for code and CC-BY-4.0 for documentation, so there are no distribution barriers for building or publishing skills.

Frequently asked questions

Official sources

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