Claude Skills are reusable folders of instructions that Claude loads when a request matches what the skill is for. Each folder holds a SKILL.md file and, optionally, the scripts, reference documents, and templates the task needs. Anthropic describes them as reusable, filesystem-based resources that turn a general-purpose agent into a specialist.
The format is not Claude-only. Anthropic developed it and released it as an open standard, the specification lives at agentskills.io, and a client showcase there lists the agent products that read the same SKILL.md file.
This page covers the format, how a skill loads, where skills run today, how to install one, how to write one, where to find skills worth using, and what changes the moment more than one person on a team depends on them.
Create your team library · Read the source on GitHub
Publisher: Skills Board. Published August 12, 2026. Last checked August 15, 2026.
What is a Claude Skill?
A Claude Skill is a folder containing a SKILL.md file: YAML frontmatter with a name and a description, followed by Markdown instructions. Claude keeps only the name and description in context, then reads the full file when a request matches the description. Bundled scripts, references, and assets load only when they are needed.
Sources for this section
01 / Format
What is inside a Claude Skill?
A skill is a directory whose entry point is a SKILL.md file. The file opens with YAML frontmatter, and the Markdown that follows is what Claude reads once the skill is triggered. Two frontmatter fields are required, name and description. The specification defines four more, all optional.
SKILL.md frontmatter fields defined by the Agent Skills specification.
| Field | Required | What it does |
|---|---|---|
| name | Yes | Up to 64 characters, lowercase letters, numbers, and hyphens only. It must match the parent directory name, cannot start or end with a hyphen, and cannot contain consecutive hyphens. |
| description | Yes | Up to 1024 characters. This is the field the agent matches a request against, so it has to say both what the skill does and when to use it, in the words someone would actually type. |
| license | No | The license that applies to the skill, either a license name or the name of a bundled license file. |
| compatibility | No | Up to 500 characters for environment requirements: the intended product, required system packages, or network access. Most skills do not need it. |
| metadata | No | A map of string keys to string values for properties the spec does not define, such as an author or a version. |
| allowed-tools | No | A space-separated list of pre-approved tools. The spec marks this field experimental, and support varies between agent implementations. |
Skill directory
my-skill/
SKILL.md # required: frontmatter and instructions
scripts/ # optional: code the agent can run
references/ # optional: documentation loaded on demand
assets/ # optional: templates and other static files
Everything beyond SKILL.md is optional. The specification suggests scripts for executable code, references for documentation the agent reads only when it needs it, and assets for templates and other static files. There is no restriction on the Markdown body itself.
Claude Code accepts extra frontmatter fields of its own, such as disable-model-invocation and argument declarations. Outside Claude Code, the claude.ai upload path, the Skills API, and Anthropic's packaging script accept only the six fields in the spec, and an unexpected key fails with a hard error rather than being ignored. Frontmatter that stays inside the spec loads everywhere, including Claude Code.
Sources for this section
02 / Loading
How does Claude decide to use a skill?
Through progressive disclosure. The agent loads a skill in stages, so a large collection of installed skills costs very little until one of them is actually relevant.
The three stages of progressive disclosure and what each one costs.
| Stage | When it loads | Context cost | What loads |
|---|---|---|---|
| Metadata | At startup, for every installed skill | About 100 tokens per skill | The name and description from the frontmatter |
| Instructions | When a request matches the description | Under 5,000 tokens recommended | The Markdown body of SKILL.md |
| Resources | Only when referenced | Nothing until accessed | Bundled files. Reference files enter context when read, and scripts run through bash so only their output costs tokens |
This is why the description carries more weight than any other line in the file. It is the only part of most skills that Claude sees before deciding whether to read the rest, so a description that says what the skill does without saying when to use it will sit unused.
The same mechanism explains the length guidance. The specification recommends keeping SKILL.md under 500 lines and moving detail into referenced files. In Claude Code the loaded body then stays in the conversation for the rest of the session, so every line you leave in the main file is a recurring cost rather than a one-time one.
Sources for this section
03 / Surfaces
Where do Claude Skills work?
Skills run in Claude Code, on claude.ai, and through the Claude API, and the same SKILL.md folder is read by a growing list of other agents. What changes between them is how a skill gets installed, who else can use it, and what the runtime allows.
How skills are installed, shared, and sandboxed on each surface.
| Surface | How a skill gets there | Who can use it | Runtime |
|---|---|---|---|
| Claude Code | Filesystem directories: ~/.claude/skills//SKILL.md for personal skills, .claude/skills//SKILL.md for a project, a skills directory inside a plugin, or enterprise managed settings. | You, one repository, or everyone the plugin or managed settings reach. | The same network access as any other program on your computer. |
| claude.ai | Upload the skill as a zip file under Settings, then Features. Available on Pro, Max, Team, and Enterprise plans with code execution enabled. | The individual user. Custom skills are not shared organization-wide and cannot be centrally managed by admins. | Network access varies with user and admin settings. |
| Claude API | Reference a skill_id in the container parameter alongside the code execution tool and the skills-2025-10-02 beta header, or upload your own through the /v1/skills endpoints. | Workspace-wide. All workspace members can access uploaded skills. | A sandboxed container with no network access and no runtime package installation. |
| Other agents | Each product documents its own install path for the same SKILL.md folder. The client showcase on agentskills.io links to the instructions for each one. | Depends on the product. | Depends on the product. |
Custom skills do not sync across surfaces. Anthropic documents this plainly: a skill uploaded to claude.ai is not available through the API, a skill uploaded through the API is not available on claude.ai, and Claude Code skills are filesystem-based and separate from both. Each surface is managed on its own.
Anthropic also ships pre-built skills for PowerPoint, Excel, Word, and PDF. Those are available on claude.ai and the Claude API, and they are not available in Claude Code.
Sources for this section
- Anthropic: Agent Skills overview
- Claude Code: skills documentation
- Agent Skills: overview and client showcase
04 / Install
How do you install and run a Claude Skill?
Installing a skill means putting the folder where the agent looks for it. There is no package manager in the format itself, which is why each surface has its own path.
In Claude Code, drop the folder in a skills directory
Use ~/.claude/skills// to make a skill available in all your projects, or .claude/skills// to scope it to one repository and commit it with the code. Claude Code watches those directories and picks up an added or edited SKILL.md during the session, without a restart.Invoke it yourself, or let Claude choose
A skill is available as a slash command named after its directory, and Claude can also load it on its own when a request matches the description. Add disable-model-invocation: true when only you should be able to trigger it, which is the sensible default for anything that deploys, commits, or sends a message.On claude.ai, upload a zip
Custom skills are uploaded under Settings, then Features, on Pro, Max, Team, and Enterprise plans with code execution enabled. Each teammate does this for their own account, since claude.ai custom skills are per user.Through the API, pass a skill_id
Skills run inside the code execution tool's container. Reference the skill by id in the container parameter and send the skills-2025-10-02 beta header. Add the files-api-2025-04-14 header when the container needs uploaded input files or produces files you want to download.From a catalog, use that catalog's installer
npx skills add owner/repo installs from the skills.sh directory. /plugin marketplace add anthropics/skills registers Anthropic's repository as a plugin marketplace in Claude Code, and the document and example skill plugins install from there.
Sources for this section
- Claude Code: skills documentation
- Anthropic: Agent Skills overview
- skills.sh documentation
- anthropics/skills on GitHub
05 / Authoring
How do you write your own Claude Skill?
Write the skill the same way you would brief a new teammate: say when the procedure applies, then give the steps, then link to the detail rather than pasting it.
Pick something you already repeat
Anthropic's own trigger for Claude Code is direct: create a skill when you keep pasting the same instructions, checklist, or multi-step procedure into chat, or when a section of CLAUDE.md has grown into a procedure rather than a fact.Create the directory and the file
The directory name becomes the command you type in Claude Code, and it has to match the name in the frontmatter. SKILL.md is the entry point and the only required file.Write the description for matching, not for reading
State what the skill does and when to use it, and include the words a person would type when they need it. A description that only names the skill gives the agent nothing to match against.Keep the body short
The specification recommends staying under 500 lines and roughly 5,000 tokens, and moving longer material into files under references that load only when the task calls for them.Move deterministic work into scripts
A script's code never enters the context window. Only its output does, which makes a bundled script cheaper and more reliable than asking the agent to regenerate the same logic each time.Validate before you share it
The skills-ref reference library checks that the frontmatter is valid and that the naming rules hold: skills-ref validate ./my-skill. This catches the fields that fail on upload or packaging rather than at authoring time.Decide the distribution scope
Commit .claude/skills/ for a project, ship a skills directory inside a plugin for a wider audience, or deploy organization-wide through managed settings. Each scope answers a different question about who should get the skill by default.
SKILL.md starting point
---
name: release-notes
description: Draft release notes from merged pull requests. Use when preparing a release, writing a changelog, or summarizing what shipped.
---
# Release notes
## Steps
1. List the pull requests merged since the last tag.
2. Group them into Added, Changed, and Fixed.
3. Write one line per change, in plain language, from the reader's point of view.
4. Link every entry to its pull request.
## Output
A Markdown section ready to paste into the release description.
Sources for this section
06 / Ecosystem
Where do you find Claude Skills worth using?
Start with sources that publish the files, so you can read a skill before you install it. These four cover most of what the ecosystem currently offers.
anthropics/skills
Anthropic's public repository for Agent Skills. It holds example skills across creative, technical, and enterprise tasks, the specification, and a skill template. Many of the skills are Apache 2.0. The document skills that power file creation in Claude are source-available rather than open source, and Anthropic publishes them as a reference for more complex skills. Register the repository as a Claude Code plugin marketplace with /plugin marketplace add anthropics/skills.
obra/superpowers
An MIT-licensed community project that packages a full software development methodology as composable skills, with a spec-first, plan-then-build workflow. It documents install paths for Claude Code and several other agents, and it is installable from the official Claude plugin marketplace.
skills.sh
Vercel's public directory of agent skills. It has a leaderboard ranked from anonymous telemetry collected by its CLI, topics, an official set, routine security audits, and packs that bundle several skills behind one install command. Skills install with npx skills add owner/repo, and the CLI is open source.
agentskills.io
The standard's own site: the specification, a quickstart, and a client showcase that links to the skill instructions for each agent product that supports the format. Useful when you need to check whether a skill will load in something other than Claude.
Read before you install. Anthropic's guidance is to use skills only from sources you trust, because a skill gives an agent new instructions and executable code, and a malicious one can direct the agent to call tools in ways the stated purpose does not suggest. If a skill comes from somewhere unfamiliar, audit every file in it, including scripts and anything it fetches from an external URL, and treat the decision the way you would treat installing software.
Sources for this section
- anthropics/skills on GitHub
- obra/superpowers on GitHub
- skills.sh documentation
- Agent Skills: overview and client showcase
- Anthropic: Agent Skills overview
07 / Teams
How does a team share the skills it recommends?
Nothing in the format does it for you. The SKILL.md folder is portable, but distribution is per surface, and the recommendation itself usually is not stored anywhere at all.
Look at what the surfaces actually offer a team. On claude.ai, custom skills belong to the individual user, are not shared organization-wide, and cannot be centrally managed by admins. Through the API, uploaded skills are workspace-wide. In Claude Code, a skill lives in a personal folder, in one repository, or in a plugin. None of those places holds the part teammates keep asking about: which skill to use for this, and why this one.
That part ends up in a chat thread, a bookmark, or one person's memory. Skills Board is a shared library for exactly that layer: the smaller set of skills your team recommends, in one searchable place, with the original source visible on every entry.
Open the original source
Every saved skill records the repository and path it came from, so a teammate can read the SKILL.md before using it.
Copy an install command
For the teammates whose setup the command fits.
Download a ZIP
The latest skill files available from the source at download time, for anyone who would rather place the folder themselves.
Connect an agent over MCP
An authenticated MCP endpoint lets a compatible agent search the same team library, retrieve install commands, and, with the granted scopes, save skills and organize collections. Sign-in happens in the browser, with no API key to copy.
- A saved skill is a team recommendation, not a security review, an approval, or a compatibility certification.
- Skills Board follows the latest version available from the saved source. It does not pin or preserve historical versions.
- It does not install or run skills inside your agent, and it does not claim a skill works in every agent your team uses.
- The hosted product is free forever, the code is MIT licensed, and you can read or self-host all of it.
Sources for this section
08 / Questions
Frequently asked questions
What is a Claude Skill?
A folder containing a SKILL.md file with YAML frontmatter and Markdown instructions. The frontmatter needs a name and a description; the description is what Claude matches a request against. The folder can also bundle scripts, reference documents, and assets that load only when the task needs them.
What is the difference between a skill and a prompt?
A prompt is a conversation-level instruction for one task. A skill is a reusable folder that loads on demand, so the same guidance does not have to be repeated across conversations. Anthropic draws that distinction directly in the Agent Skills overview.
Do Claude Skills work outside Claude?
Yes. Agent Skills is an open standard published at agentskills.io, and its client showcase lists agent products that read the same SKILL.md file. Frontmatter fields beyond the six in the spec, and Claude Code-only body features such as dynamic context injection, do not carry over.
Do custom skills sync between Claude Code, claude.ai, and the API?
No. Anthropic documents that custom skills do not sync across surfaces. A skill uploaded to claude.ai is not available through the API, an API skill is not available on claude.ai, and Claude Code skills are filesystem-based and separate from both. You manage each surface yourself.
How many skills can you install before context suffers?
Only the name and description of each installed skill load at startup, about 100 tokens per skill, so a large collection costs little until something triggers it. In Claude Code the body of a triggered skill stays in the conversation for the rest of the session, so the number that matters is how many you use at once, not how many you have.
Are Claude Skills safe to install?
Treat a skill like software you are about to run. Anthropic's guidance is to use skills only from sources you trust, and to audit every bundled file before using one from an unknown source, because a skill can direct an agent to execute code and call tools. Skills that fetch content from external URLs deserve extra scrutiny.
What is the difference between a skill and an MCP server?
A skill is a folder of instructions and resources the agent reads. MCP is a protocol for connecting an agent to external tools and data through a server. They answer different questions and are often used together: Skills Board publishes a team library over an authenticated MCP endpoint, while the skills themselves stay in SKILL.md folders at their original sources.
Where should a team keep the skills it recommends?
Wherever teammates will actually look. If every skill belongs to one repository the whole team works in, commit them to .claude/skills/ and stop there. If the recommendations come from other people's repositories and teammates run different agents, a shared library that keeps the source visible on every entry is easier to keep current. Skills Board is one option, and it is free and open source.
Sources
Editorial method: every claim about the format and the products that run it comes from the first-party documentation below. Product behavior changes, so check the linked pages before you rely on a detail.
- Anthropic: Agent Skills overview: Progressive disclosure stages and token costs, required frontmatter fields, the surfaces skills run on, sharing scope, runtime constraints, the pre-built document skills, and the security guidance.
- Claude Code: skills documentation: Where Claude Code loads skills from, slash-command invocation, disable-model-invocation, live change detection, which frontmatter fields survive outside Claude Code, and the distribution scopes.
- Agent Skills specification: The six frontmatter fields and their constraints, the optional scripts, references, and assets directories, the progressive disclosure budgets, and skills-ref validation.
- Agent Skills: overview and client showcase: The format as an open standard originally developed by Anthropic, and the list of agent products that support it.
- anthropics/skills on GitHub: Anthropic's public skills repository: example skills, the spec, a template, the licensing note for the document skills, and the plugin marketplace command.
- obra/superpowers on GitHub: An MIT-licensed skills framework and development methodology, with documented install paths for Claude Code and other agents.
- skills.sh documentation: The npx skills add command, the telemetry-based leaderboard, routine security audits, packs, and the open-source CLI behind them.
Keep reading
- Codex skills: what they are and how to use them: The same standard read by OpenAI's agent, the directories it scans, and what a skill keeps when it moves.
- Cursor skills: what they are and how to use them: Every directory Cursor scans, including the Claude ones, and the two frontmatter fields it adds.
- Manage skills across Claude Code, Codex, and Cursor: One canonical SKILL.md, and a tested install path for each agent your teammates run.
- How to share AI agent skills with your team: Turning a skill that worked once into a recommendation the next teammate can find.
- A shared MCP skill library for teams: What a connected agent can and cannot do with a shared library over MCP.
- Skills Board vs skills.sh: A public directory next to a team library, and which question each one answers.
Put the skills your team recommends somewhere everyone can find them.
Free forever, MIT licensed, and open source. Create a library, save the first skill, and invite the people who keep asking which one to use.
Create your team library · View the code on GitHub
Originally published at skillsboard.sh/claude-skills.
Top comments (0)