SKILL.md is an open standard for packaging reusable AI agent capabilities as portable, filesystem-based skills — a folder with a SKILL.md file that any compliant agent can load on demand.
What It Is
Published by Anthropic at agentskills.io in December 2025 and contributed as an open standard, SKILL.md defines how to bundle procedural knowledge into a portable, shareable unit:
my-skill/
└── SKILL.md ← YAML frontmatter + markdown instructions
A minimal SKILL.md:
---
name: write-conventional-commits
description: >
Write git commit messages following the Conventional Commits spec.
Use when committing code changes.
---
## Instructions
1. Prefix with type: feat, fix, docs, chore, refactor, test, ci
2. Keep subject line under 72 characters
3. Use imperative mood: "add feature" not "added feature"
4. If breaking change, append `!` after type and add `BREAKING CHANGE:` footer
AGENTS.md vs SKILL.md
These two conventions are complementary, not competing:
AGENTS.md |
SKILL.md |
|
|---|---|---|
| Scope | Per-repository context | Reusable across repos |
| Purpose | Teach agent your codebase | Give agent a capability |
| Lifetime | Lives in your repo | Shareable as a package |
| Loaded when | Always, at agent start | On demand when relevant |
| Written by | Your team | Anyone; publishable |
Use AGENTS.md to teach the agent your project's conventions. Use SKILL.md to give it reusable capabilities (commit writing, PR description templates, framework-specific patterns).
How Progressive Disclosure Works
The agent skills spec breaks knowledge loading into three levels to control token cost:
- L1 Metadata (~100 tokens/skill) — name + description only; loaded at startup so the agent can decide relevance
- L2 Summary (~500 tokens/skill) — loaded when the agent decides the skill applies
- L3 Full instructions — loaded only when actively executing the skill
This means you can have dozens of skills installed without bloating every prompt.
Adoption
As of Q1 2026, 30+ agent tools consume the SKILL.md format natively, including:
- Claude Code, OpenAI Codex, GitHub Copilot
- Cursor, Windsurf, Gemini CLI, JetBrains Junie
- Goose, OpenHands, Aider
Over 2,600 community skills are available, growing at roughly 2x per quarter. Major skills repositories include:
- github.com/anthropics/skills — the canonical reference implementation
- github.com/addyosmani/agent-skills — production-grade engineering skills
- SkillsMP — cross-vendor marketplace
Security Considerations
SKILL.md's simplicity is a double-edged sword. Because skills are just markdown, there is:
- No sandboxing — a malicious skill can instruct an agent to do anything the agent is capable of
- No schema validation — broken skills fail silently at runtime
- No dependency resolution — skill conflicts must be managed manually
- Prompt injection risk — Cisco researchers identified community skills being used for silent data exfiltration
Practical guidance: treat community skills like third-party dependencies. Review before installing. Use skills from trusted maintainers (Anthropic, named engineers) for production workflows; treat anonymous marketplace skills with the same scrutiny you'd give an unknown npm package.
gh skill CLI (April 2026)
GitHub shipped gh skill in GitHub CLI v2.90.0, bringing first-class package management to agent skills. The command discovers, installs, manages, and publishes skills from GitHub repositories. gh skill publish validates skills against the agentskills.io spec and checks repository security settings (tag protection, secret scanning, code scanning). Skills are installed at the user's discretion and are not verified by GitHub — inspect content before installation.
Key Characteristics
| Property | Value |
|---|---|
| Spec governed by | agentskills.io |
| Origin | Anthropic, December 2025 |
| Format | Folder + YAML-frontmatter markdown |
| Tool adoption | 30+ agents (Claude Code, Codex, Copilot, Cursor, Gemini CLI…) |
| Related convention | AGENTS.md — per-repo context file |