AI & ML
What Are Agent Skills? SKILL.md Explained, With Install Commands and a 10-Line Example
Agent skills are folders with a SKILL.md that an AI agent loads on demand. Which agents support them, how to install vendor skills, and how to write your own.
Your tool hereOn tool pages, blog posts and the feeds, next to what people came to read.$19 / 3 months →An agent skill is a folder with a SKILL.md file: a few lines of YAML (a name and a
description) plus Markdown instructions that a coding agent loads only when the task matches.
The format began at Anthropic, is now an open standard at agentskills.io,
and is read by Claude Code, Codex and Cursor, among others. To use one, run
npx skills add <owner>/<repo>; to write one, create a folder and a SKILL.md.
This guide covers what a skill contains, which agents read it, how to install skills from Anthropic, Vercel, Supabase and Neon, and how to write a small one. Every command and rule below was checked against the official docs or repositories on 13 November 2026. Our own list of 73 skills from 18 publishers is on the skills hub.
Skills at a glance
| What it is | A directory with a required SKILL.md, plus optional scripts/, references/ and assets/ |
| Required fields | name and description (the open spec) |
| Loaded how | Name and description at startup; the full body only when the task matches |
| Origin | Developed by Anthropic, released as an open standard |
| Read by | Claude Code, Codex, Cursor, Copilot, Cline and more |
| Common installer | npx skills add (MIT-licensed CLI from Vercel Labs) |
What a skill actually is
A skill packages instructions you would otherwise paste into every chat: how your team writes migrations, how to run a PDF extraction, what a good code review looks like. The open specification defines the layout:
skill-name/
├── SKILL.md # required: metadata + instructions
├── scripts/ # optional: executable code
├── references/ # optional: documentation
└── assets/ # optional: templates, resourcesThe frontmatter has two required fields. name is 1-64 characters, lowercase letters,
numbers and hyphens, no leading or trailing hyphen, and it must match the directory name.
description is 1-1024 characters and should say both what the skill does and when to use
it. Optional fields are license, compatibility, metadata and an experimental
allowed-tools.
The point is progressive disclosure. At startup an agent loads only each skill's name and
description (about 100 tokens, per the spec). The full SKILL.md body loads when the task
matches, and bundled files load only when the instructions reference them. The spec recommends
keeping SKILL.md under 500 lines. That is why you can install dozens of skills without
filling the context window, unlike a long rules file that loads every time.
Which agents support skills
| Agent | Where it looks | Source |
|---|---|---|
| Claude Code | ~/.claude/skills/<name>/SKILL.md (personal), .claude/skills/<name>/SKILL.md (project), or a plugin | Claude Code docs |
| Codex | .agents/skills in the repo and parent folders, $HOME/.agents/skills, /etc/codex/skills | Codex docs |
| Cursor | .agents/skills/ and .cursor/skills/ (plus ~/ versions); also reads .claude/skills/ and .codex/skills/ | Cursor docs |
Claude Code's docs say its skills follow the Agent Skills open standard and add extras such
as disable-model-invocation, context: fork for running a skill in a subagent, and
shell-command injection into the prompt. Codex says its skills build on the same standard
and adds an optional agents/openai.yaml. Cursor's name and description rules match
the spec.
The skills CLI lists OpenCode, Claude Code, Codex and Cursor among its targets, "and 75
more". Supabase's repository says its skills work with 18+ agents, naming Claude Code,
GitHub Copilot, Cursor and Cline. Because Cursor reads Claude's and Codex's folders, one
skill often works in all three.
How to install official vendor skills
The simplest route is the skills CLI from vercel-labs/skills
(MIT, needs Node.js 22.20 or later). It installs into the current project; add -g to make a
skill available across projects.
# pick skills and agents interactively
npx skills add vercel-labs/agent-skills
# one skill, one agent
npx skills add vercel-labs/agent-skills --skill web-design-guidelines -a claude-codeOther commands: npx skills find, list, check, update, remove and init [name]
(creates a template). Here is what the main vendors publish and how each documents installing it.
| Publisher | Repo | What is in it | Install (from the repo's README) |
|---|---|---|---|
| Anthropic | anthropics/skills | Example skills plus the docx, pdf, pptx and xlsx document skills | /plugin marketplace add anthropics/skills |
| Vercel | vercel-labs/agent-skills | 8 skills: React and Next.js performance rules, web design guidelines, React Native, View Transitions, deploy to Vercel | npx skills add vercel-labs/agent-skills |
| Supabase | supabase/agent-skills | supabase and supabase-postgres-best-practices | npx skills add supabase/agent-skills |
| Neon | neondatabase/agent-skills | 8 skills including neon, neon-postgres and neon-auth | npx skills add neondatabase/agent-skills |
Licenses: Vercel's and Supabase's repositories are MIT, Neon's is Apache-2.0. Anthropic's README says many skills are Apache 2.0 and the four document skills are too; check each skill's folder for its own terms. The same README calls the examples demonstration material, so test them before you rely on them.
Claude Code also has a plugin route. For Anthropic's repo, after the marketplace line above,
run /plugin install document-skills@anthropic-agent-skills or
/plugin install example-skills@anthropic-agent-skills. Supabase documents
claude plugin marketplace add supabase/agent-skills followed by
claude plugin install supabase@supabase-agent-skills. Neon documents
/plugin marketplace add neondatabase/agent-skills then /plugin install neon-postgres@neon.
Plugin skills are namespaced as /plugin-name:skill-name.
To browse before you install, the Skills registry lists what people actually install. For design systems written as agent-readable files, see DESIGN.md.
Write your own in ten lines
Create .claude/skills/summarize-changes/SKILL.md in a repo (or ~/.claude/skills/ for all
projects). This is the example from Claude Code's docs:
---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---
## Current changes
!`git diff HEAD`
## Instructions
Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.In Claude Code the name defaults to the directory, so /summarize-changes works, and Claude
can also load it when you ask what changed. The !`git diff HEAD` line is Claude Code's
own extension: the command runs and its output is inlined before the model sees the skill.
For a skill that should run in other agents, use the portable subset (name, description,
body, optional folders), and include name because the open spec requires it.
Rules that make skills fire reliably:
- Put the trigger in the description. The spec's good example names the task and the cues ("Use when working with PDF documents or when the user mentions PDFs"); its poor example is "Helps with PDFs."
- Keep the body short and move detail to files. Reference
references/REFERENCE.mdorscripts/extract.pywith relative paths, one level deep. - Validate it. The spec's
skills-ref validate ./my-skillchecks the frontmatter. - Test it. Anthropic's example repo includes a
skill-creatorskill for writing and evaluating skills.
Skills, MCP servers and rules files
A skill teaches an agent how to do something; an MCP server gives it a way
to reach something, such as a database or a browser. The two combine well: Supabase ships
both a skill and an MCP server, and the Supabase skill's description covers the CLI and the
MCP server. A rules file such as AGENTS.md loads on every task, so keep it for facts that
always apply, and move task-specific procedures into skills. A pasted prompt pack such as
VibePrompt works on one agent for one session; a skill is versioned
in your repo and loads on demand.
How to choose
- Start with one skill for your stack, such as Vercel's React rules, Supabase's Postgres guidance or Neon's, and see whether the agent's output changes before adding more.
- Prefer first-party repos from the vendor whose product you use; they track API changes.
- Read the
SKILL.mdbefore installing. A skill is instructions plus optional scripts the agent can run, so treat it like a dependency. - Write your own for anything your team repeats: release steps, review checklists, migration conventions.
Sources
Checked 13 November 2026: Agent Skills overview and specification; Claude Code skills; Codex skills; Cursor skills; vercel-labs/skills; anthropics/skills; vercel-labs/agent-skills; supabase/agent-skills; neondatabase/agent-skills.
Browse all 73 skills we track on the skills hub. Related: best MCP servers for web developers and AI tools for developers.