at its core, a skill is a folder containing a skill.md file. this file includes metadata (name and description, at minimum) and instructions that tell an agent how to perform a specific task. skills can also bundle scripts, templates, and reference materials.
skills use progressive disclosure to manage context efficiently:
- discovery: at startup, agents load only the name and description of each available skill, just enough to know when it might be relevant.
- activation: when a task matches a skill’s description, the agent reads the full
skill.mdinstructions into context. - execution: the agent follows the instructions, optionally loading referenced files or executing bundled code as needed. this approach keeps agents fast while giving them access to more context on demand.
every skill starts with a skill.md file containing yaml frontmatter and markdown instructions:the following frontmatter is required at the top of skill.md:
name: a short identifierdescription: when to use this skill the markdown body contains the actual instructions and has no specific restrictions on structure or content.this simple format has some key advantages:- self-documenting: a skill author or user can read a
skill.mdand understand what it does, making skills easy to audit and improve. - extensible: skills can range in complexity from just text instructions to executable code, assets, and templates.
- portable: skills are just files, so they’re easy to edit, version, and share.
- view the specification to understand the full format.
- add skills support to your agent to build a compatible client.
- see example skills on github.
- read authoring best practices for writing effective skills.
- use the reference library to validate skills and generate prompt xml.