SKILL.md: The Open Standard for Reusable AI Agent Skills
AI coding agents are becoming more capable, but they still need reliable instructions for project-specific workflows. Repeating the same prompt in every session is inefficient, difficult to maintain, and easy to apply inconsistently.
Agent Skills solve this by packaging reusable expertise into a directory whose entry point is a SKILL.md file. A skill can contain instructions, executable scripts, reference material, templates, and other assets. The agent initially sees only a small amount of metadata and loads the detailed instructions only when the current task matches the skill.
The supplied infographic calls SKILL.md a “universal standard.” The official specification describes Agent Skills as an open standard. The format is portable, but exact discovery paths and product-specific extensions still vary by tool.
TL;DR
- A skill is a folder containing a required
SKILL.mdfile. SKILL.mdstarts with YAML frontmatter and continues with Markdown instructions.- Only
nameanddescriptionare required by the base specification. - Scripts, references, and assets are optional and loaded when required.
- Progressive disclosure reduces unnecessary context usage.
- Claude Code, OpenAI Codex, and Gemini CLI support the open Agent Skills format, although their preferred storage paths differ.
What is a SKILL.md file?
A SKILL.md file defines a reusable capability for an AI agent. Typical examples include:
- reviewing pull requests against a company checklist;
- validating database migrations;
- preparing releases;
- creating project documentation;
- processing PDFs or datasets;
- deploying an application with an organization-specific workflow.
Unlike a persistent project instruction file, a skill is intended for on-demand expertise. The agent selects it when the user request matches the skill description, or the user invokes it explicitly when the host tool supports manual invocation.
Anatomy of a skill
The smallest valid skill contains a directory and one file:
review-pr/ └── SKILL.md
A more complete skill can bundle supporting resources:
review-pr/
├── SKILL.md
├── scripts/
│ ├── lint.sh
│ └── scan.py
├── references/
│ ├── review-checklist.md
│ └── api-policy.md
└── assets/
└── review-report-template.md
The official specification requires YAML frontmatter followed by Markdown content:
--- name: review-pr description: Reviews pull requests for bugs, security risks, API compatibility, test coverage, and maintainability. Use when reviewing a PR or code change. license: Apache-2.0 metadata: author: example-team version: "1.0.0" --- # Pull Request Review 1. Inspect the changed files and identify the intended behavior. 2. Check for security vulnerabilities and exposed secrets. 3. Identify breaking API or schema changes. 4. Verify tests cover the changed behavior. 5. Report findings by severity and include precise file references.
Core frontmatter fields
| Field | Required | Purpose |
|---|---|---|
name | Yes | Stable skill identifier; must match the parent directory name in the base specification. |
description | Yes | Explains what the skill does and when the agent should activate it. |
license | No | Declares the license or points to a bundled license file. |
compatibility | No | Documents environment requirements such as tools, packages, network access, or target products. |
metadata | No | Stores implementation-specific string key/value data. |
allowed-tools | No | Pre-approves selected tools; experimental and not uniformly supported. |
Some products add their own frontmatter fields. Those extensions may be useful, but they are not automatically portable to every Agent Skills implementation.
Progressive disclosure: why skills scale
Loading hundreds of full instruction files into every prompt would waste context and reduce the space available for the actual task. Agent Skills avoid that through progressive disclosure:
- Discovery: the agent receives the skill name and description.
- Activation: the full
SKILL.mdbody is loaded only when the task matches. - Resource access: scripts, references, and assets are accessed only when the workflow needs them.
The base specification recommends keeping the main SKILL.md below 500 lines and its instructions below roughly 5,000 tokens. Longer explanations should be moved into focused reference files.
SKILL.md versus project instructions and MCP
These mechanisms solve different problems:
| Mechanism | Main purpose | Typical loading model |
|---|---|---|
Agent Skill (SKILL.md) | Reusable workflow or domain expertise | Loaded when selected or invoked |
| Project instruction file | Persistent rules, conventions, and repository context | Loaded for each applicable session |
| MCP server | Connection to external tools, APIs, databases, or services | Connected according to host configuration |
They complement each other. A skill can explain how to perform a deployment, while an MCP server provides the external deployment tool. A project instruction file can define the repository-wide constraints that apply to both.
Where tools discover skills
The file format is portable, but the default path depends on the product:
| Tool | Common project path |
|---|---|
| Claude Code | .claude/skills/<skill-name>/SKILL.md |
| OpenAI Codex | .agents/skills/<skill-name>/SKILL.md |
| Gemini CLI | .gemini/skills/<skill-name>/SKILL.md or .agents/skills/<skill-name>/SKILL.md |
| Vendor-neutral repository convention | .agents/skills/<skill-name>/SKILL.md |
For cross-tool projects, .agents/skills/ is increasingly useful as an interoperable location. Always check the current documentation for the specific host because precedence, personal-scope paths, invocation syntax, and extension fields can differ.
Best practices for production skills
Write the description as a trigger
The description should state both the capability and the circumstances in which it applies. “Helps with reviews” is vague. “Reviews pull requests for security, API compatibility, tests, and maintainability; use when reviewing a PR or code change” is actionable.
Keep one skill focused on one job
A narrowly scoped skill is easier to select, test, version, and reuse. Split unrelated workflows such as release preparation, incident analysis, and documentation generation into separate skills.
Prefer instructions unless deterministic logic is necessary
Use Markdown instructions for reasoning and flexible procedures. Add scripts when the result must be deterministic, when complex data processing is required, or when an external command must be executed consistently.
Make inputs, outputs, and failure behavior explicit
Specify expected input files, required tools, output locations, acceptance criteria, and what the agent should do when prerequisites are missing. Add a “Gotchas” or “Failure handling” section for recurring problems.
Version and review skills like source code
Store project skills in Git, review changes through pull requests, and test representative prompts. A skill is executable operational knowledge; an incorrect instruction can be as disruptive as incorrect code.
Treat third-party skills as executable dependencies
Review all instructions and bundled scripts before installation. Check network access, shell commands, file permissions, data handling, and external dependencies. Do not assume that a portable format makes an untrusted skill safe.
Create your first skill
Create a vendor-neutral project skill:
mkdir -p .agents/skills/review-pr $EDITOR .agents/skills/review-pr/SKILL.md
Add the minimal structure:
--- name: review-pr description: Reviews pull requests for correctness, security, compatibility, and test coverage. Use when examining a pull request or a set of code changes. --- # Review procedure 1. Summarize the intended change. 2. Inspect correctness and edge cases. 3. Check security and secret exposure. 4. Identify compatibility risks. 5. Evaluate tests and missing coverage. 6. Return findings ordered by severity.
Start a new agent session or reload skills according to the host tool, then test with a request that clearly matches the description. Refine the description if the skill activates too often or not often enough.