What is SKILL.md? The open standard for Claude AI skills explained
SKILL.md is the lightweight file that tells an AI coding agent what a skill does and when to use it. Here's everything you need to know.
By CB Patel
SKILL.md is an open plain-text standard — a single Markdown file that lives in the skill's own folder and tells an AI coding agent (Claude Code, Cursor, and others) exactly what a skill does, when to use it, and what rules it should follow.
Think of it as a package.json for AI behaviour. Instead of re-explaining your preferred coding style, your review checklist, or your deployment workflow in every new conversation, you write it once in SKILL.md and install it globally.
What goes inside a SKILL.md file?
A minimal SKILL.md has two parts: YAML frontmatter with a name and a description, and Markdown instructions below it:
---
name: frontend-shadcn-builder
description: Builds React components using shadcn/ui, Tailwind, and TypeScript, following the project's component library conventions. Use when asked to build a component, create a UI, or add a shadcn component.
---
# Frontend shadcn Builder
Build every component from shadcn/ui primitives and the project's existing tokens.
The description does two jobs: it says what the skill does and when to use it. Claude reads only the name and description up front and loads the full instructions when a request matches the description, so there is no separate list of trigger phrases.
A complete skill also includes, in the Markdown body:
- Rules (what the skill should always or never do)
- Examples (sample inputs and expected outputs)
The frontmatter can also carry optional fields such as license (MIT, Apache-2.0, etc.) and allowed-tools.
The full specification is documented at claudeskil.com/docs.
Why does the standard matter?
Before SKILL.md, sharing AI "prompts" meant copy-pasting walls of text into a Discord channel. The quality degraded instantly. There was no versioning, no review, no way to know if a prompt had been tested or just thrown together.
SKILL.md changes that. Because it's a plain file you can keep in a Git repo, a skill can have:
- A commit history (you can see when it changed and why)
- Issues (users can report bugs)
- Stars (popularity signal)
- Releases (versioned, stable snapshots)
It turns a prompt into software.
How do agents read it?
Claude Code looks for the skills you add yourself in two places: ~/.claude/skills/<name>/SKILL.md for personal skills available in every project, and .claude/skills/<name>/SKILL.md for skills that belong to one project (commit that folder to share it with your team). Plugins can bundle skills too. Claude reads each skill's name and description up front and loads the full instructions only when a request matches the description. You can also run a skill directly by typing /<name>. The skill stays available until you delete its folder — no re-pasting required.
Other agents that support the open format, including Cursor, GitHub Copilot and OpenAI's Codex, can use the same file; each tool's documentation says where it looks for skills.
How to create your own SKILL.md
- Create a new GitHub repo (e.g.
my-skill) - Add a
SKILL.mdfile to the root - Fill in the
nameanddescriptionfrontmatter, then write the rules and instructions in Markdown below it - Push and open-source it
- Submit to ClaudeSkill at claudeskil.com/submit
Submissions are reviewed before they're listed on the marketplace.
The SKILL.md ecosystem today
ClaudeSkill lists about 200 open-source skills — from frontend engineering and data science to SEO, video editing, and SQL. Every one follows the SKILL.md standard, which means they all work the same way in any agent that supports it.
The format was originally developed by Anthropic and released as an open standard that other tool makers can contribute to.