What is a Claude skill?
By the Kitbay editorial team ·
A Claude skill is a folder of instructions built around a file called SKILL.md that teaches Claude how to carry out a particular kind of task. Claude keeps only each skill's name and description in view, and opens the full instructions, scripts and reference files when a request calls for them.
What a skill is for
Think of a skill as a written procedure you would otherwise repeat in every chat: your team's report format, a release checklist, the steps for filling in a PDF form, or the rules for querying an internal database. Anthropic's documentation compares a skill to an onboarding guide for a new colleague: it holds the know-how, and Claude applies it when the job comes up.
The Claude Code documentation gives a practical trigger. If you keep pasting the same instructions into a conversation, that text is a candidate for a skill. Unlike always-on project notes, a skill's main body only enters the conversation when it is used.
Skills follow the open Agent Skills format published at agentskills.io, which Anthropic released as an open standard in December 2025. Because of that, the same folder can work outside Claude. Codex reads skills from .agents/skills folders, and Gemini CLI reads them from .gemini/skills or .agents/skills, according to each tool's own documentation.
What's inside a skill
A skill is a directory. Only SKILL.md is required; everything else is optional.
pdf-forms/
├── SKILL.md required: front matter + instructions
├── scripts/ code the agent can run
├── references/ extra documents read on demand
└── assets/ templates, images, data files
SKILL.md and its front matter
SKILL.md starts with YAML front matter between two --- lines, followed by Markdown instructions. The Agent Skills specification defines these fields:
| Field | Required | What the specification says |
|---|---|---|
name |
Yes | Up to 64 characters; lowercase letters, digits and hyphens; no hyphen at the start or end, no double hyphens; must match the folder name |
description |
Yes | Up to 1,024 characters; should say what the skill does and when to use it |
license |
No | A licence name or a pointer to a bundled licence file |
compatibility |
No | Up to 500 characters on environment needs, such as required packages or network access |
metadata |
No | Free-form string keys and values |
allowed-tools |
No | Pre-approved tools; marked experimental, and support varies by agent |
Anthropic's API adds two limits of its own: the name cannot contain the reserved words "anthropic" or "claude", and neither field may contain XML tags.
The description matters most. It is the text Claude compares your request against when deciding whether to open the skill, so it needs to name both the job and the situations that should trigger it.
Claude Code accepts extra front matter fields, such as disable-model-invocation (only you can start the skill) and context: fork (run it in a subagent). Its documentation warns that outside Claude Code, for example when uploading to claude.ai, only the standard fields are accepted and unknown keys cause an error.
The instructions
The Markdown body has no fixed format. Step-by-step instructions, examples of input and output, and notes on edge cases are the usual content. Both Anthropic and the specification suggest keeping the main file under 500 lines and moving longer material into separate files.
Scripts
Files in scripts/ are programs the agent runs, commonly Python, Bash or JavaScript. When Claude runs one, the code itself stays out of the conversation; only the output is added. Anthropic presents this as a way to make fixed operations, such as validating a form, repeatable instead of having the model rewrite the code each time.
Reference files and assets
references/ holds documentation the agent reads only when a step needs it, such as an API reference or a database schema. assets/ holds templates, images and data files. The specification recommends linking these files directly from SKILL.md and avoiding chains of files that point to further files.
How Claude loads a skill
Skills load in stages, a design Anthropic calls progressive disclosure:
| Stage | When | Approximate cost |
|---|---|---|
| Name and description | At the start of every session | About 100 tokens per skill |
SKILL.md body |
When a request matches the description | Under 5,000 tokens recommended |
| Scripts, references, assets | Only when the instructions point to them | Nothing until read; scripts add only their output |
Here is a typical sequence. You ask Claude to pull the text out of a PDF. Claude sees that a PDF skill's description fits, reads its SKILL.md, follows the instructions, and skips the form-filling reference because the task does not need it.
In Claude Code you can also start a skill yourself by typing / followed by its name, for example /summarize-changes. Once loaded, the instructions stay in the conversation for later turns.
Where Claude skills work
- Claude Code: personal skills live in
~/.claude/skills/<name>/SKILL.md, project skills in.claude/skills/inside a repository, and plugins can bundle more. - claude.ai: you upload a skill as a zip file. Anthropic lists custom skills for Pro, Max, Ultra, Team and Enterprise plans with code execution turned on.
- Claude API: skills run inside the code execution container. Anthropic offers pre-built skills for PowerPoint, Excel, Word and PDF files, and you can upload your own. API skills have no network access.
Custom skills do not sync between these places. A skill added in claude.ai is not available through the API, and Claude Code skills are separate from both.
Skills and MCP servers
A skill teaches a procedure; an MCP server gives the agent a live connection to another system. They are often used together: a server reads your project tracker, and a skill describes how your team writes tickets. Our guide to MCP servers versus agent skills covers the difference in detail, and what an MCP server is explains the other half.
A short safety note
A skill can tell the agent to run code and use its tools on your files and accounts. Anthropic advises using skills only from sources you trust and reading every bundled file first, looking for network calls or file access that do not fit the skill's stated purpose. In Claude Code, skills have the same network access as any other program on your computer. Our security questions for servers and skills give a fuller checklist.
Find and build skills
Browse agent skills listed on Kitbay, or start from a job, such as skills for working with documents or writing and editing. Each listing shows whether the skill includes scripts and links to its source. To write your own, see how to create a skill.
Questions
- What is a skill in Claude?
- A skill is a folder containing a SKILL.md file with a name, a description and instructions. Claude sees the name and description at all times and reads the full instructions only when your request matches.
- Do skills only work with Claude?
- No. Skills follow the open Agent Skills format, and other agents such as Codex and Gemini CLI document support for SKILL.md folders. Fields specific to one product may be ignored or rejected elsewhere.
- Can a skill run code?
- Yes. A skill can include scripts that the agent runs, and only the script's output enters the conversation. That is why you should read a skill's files before installing it.
- Do my skills sync between Claude Code, claude.ai and the API?
- No. Anthropic's documentation says custom skills do not sync across surfaces, so you add them separately in each place you use them.
Sources
- Agent Skills (Claude Platform docs)checked Nov 14, 2026
- Extend Claude with skills (Claude Code docs)checked Nov 14, 2026
- Agent Skills specificationchecked Nov 14, 2026
- anthropics/skills repositorychecked Nov 14, 2026
- Equipping agents for the real world with Agent Skills (Anthropic Engineering)checked Nov 14, 2026
- Build skills (Codex docs)checked Nov 14, 2026
- Agent Skills (Gemini CLI docs)checked Nov 14, 2026
More guides
- How to connect MCP servers to Claude, ChatGPT and Cursor
- How to build an MCP server
- How to create custom skills for Claude Code
- MCP security: questions to ask before installing a server or skill
- MCP vs API: what's the difference?
- MCP vs skills: how MCP servers and agent skills differ
- What is an MCP server?