Instructions an agent can find
A skill packages instructions for a particular task in a Markdown file. Its description tells an agent when to use it; the body explains how to do the work. Developers can share those instructions with a project or distribute them in a plugin.
Model-Invoked Capabilities
An agent can match a request to a skill description and load the instructions. The user can describe the task without having to remember which skill handles it.
The SKILL.md Format
A SKILL.md file starts with YAML frontmatter describing the skill:
yaml--- name: my-skill description: What this skill does and when to invoke it ---
The instructions follow the frontmatter. Because the file is plain text, developers can review and version it alongside their code.
Progressive Disclosure
With progressive disclosure, the agent initially sees the skill description and metadata. It loads the detailed instructions when it invokes the skill. A task that never uses the skill does not need those instructions in its context.
Three Skill Scopes
Skills can be installed at three scopes:
- Personal skills reside in the user's local configuration, allowing individual developers to create shortcuts for their specific preferences.
- Project skills are stored within a specific repository, ensuring that any agent working on that codebase shares the same domain knowledge.
- Plugin skills are distributed packages, installable from a marketplace, allowing the community to share standardized capabilities.
Skills vs MCP
MCP connects an agent to tools and data, such as a database or an API. Skills provide instructions for doing a task. A skill can describe a workflow that uses MCP tools.