📐 Agent Skills Specification
The open standard for reusable AI agent instruction packages. Any tool implementing this spec can read agent skills written by anyone.
Overview
An agent skill is a self-contained directory that extends an AI coding agent's capabilities.
The skill directory contains a mandatory
SKILL.md
file and optional supporting files. Agent tools scan well-known directories at startup,
discover available skills from their metadata, and load skill instructions on demand.
The standard is intentionally minimal — a single Markdown file with a YAML header is all that's required to create a valid, portable agent skill.
Skill Folder Structure
├── SKILL.md # REQUIRED
├── scripts/
│ └── *.sh / *.py # Optional executable scripts
├── references/
│ └── *.md / *.txt # Optional reference documents
└── assets/
└── *.png / *.svg # Optional images, diagrams
Only SKILL.md is required.
All other directories are optional and loaded on demand by the agent when needed.
SKILL.md Format
A SKILL.md
file consists of two parts separated by a YAML frontmatter block:
YAML Frontmatter Fields
| Field | Required | Type | Description |
|---|---|---|---|
| name | ✅ Yes | string | Human-readable skill name. Keep under 50 chars. |
| description | ✅ Yes | string | One-line summary loaded at startup (~100 tokens budget). Be specific. |
| version | ⚠️ Rec. | semver | Semantic version. Allows tools to check for updates. |
| authors | ⚠️ Rec. | string[] | GitHub usernames or org names of skill authors. |
| tags | ⚠️ Rec. | string[] | Searchable keywords for skill discovery. |
| platforms | ❌ Opt. | string[] | List of compatible platform slugs. Omit = all platforms. |
| license | ❌ Opt. | string | SPDX license identifier (e.g., MIT, Apache-2.0). |
| repository | ❌ Opt. | url | Source repository URL. |
| docs | ❌ Opt. | url | Link to extended documentation. |
Progressive Loading Model
Compliant implementations MUST follow the three-tier loading model to keep context window usage minimal:
Discovery (Startup)
MUSTAt agent startup, scan the skills directory. Load ONLY YAML frontmatter from each SKILL.md. Budget: ~100 tokens per skill. The agent now knows all available skills by name and description.
Activation (On demand)
MUSTWhen the user references a skill by name, or when the agent determines a skill is relevant to the current task, load the full SKILL.md instruction body into context.
Resources (Lazy)
SHOULDLoad contents of scripts/, references/, and assets/ only when the agent explicitly needs them to complete a step. Never eagerly load all resources.
Directory Conventions
Skills are discovered from two scopes. Project-level skills take precedence over global skills when names conflict.
| Platform | Project Scope | Global Scope |
|---|---|---|
| 🤖 Claude Code | .claude/skills/ | ~/.claude/skills/ |
| 🐙 GitHub Copilot | .github/skills/ | ~/.copilot/skills/ |
| ⚡ Cursor | .cursor/skills/ | ~/.cursor/skills/ |
| ✨ Gemini CLI | .gemini/skills/ | ~/.gemini/skills/ |
| 🌊 Windsurf | .windsurf/skills/ | ~/.codeium/windsurf/skills/ |
| 🧠 OpenAI Codex | .codex/skills/ | ~/.codex/skills/ |
| ☁️ Kiro | .kiro/skills/ | ~/.kiro/skills/ |
| 🔓 OpenCode | .opencode/skills/ | ~/.config/opencode/skills/ |
💡 Cross-platform tip: To share one skill across multiple tools, symlink the folder or use a monorepo setup where you copy the skill directory into each platform's skills path during setup.
Platform Compatibility
Platforms that fully or partially implement the agent skills open standard:
🤖 Claude Code
✅ FullReference implementation by Anthropic
🐙 Copilot
✅ FullSupported in agent mode since 2025
⚡ Cursor
✅ FullSupported via .cursor/skills/
✨ Gemini CLI
✅ FullGoogle implementation, open source
🌊 Windsurf
⚠️ PartialCascade agent; some fields ignored
🧠 Codex
✅ FullOpenAI implementation
☁️ Kiro
⚠️ PartialIntegrates with spec/hook system
🔓 OpenCode
✅ FullSST open source CLI