What are Claude skills?
A Claude skill is a folder with a SKILL.md file that tells Claude how to do one kind of task. Anthropic’s help center describes skills as “folders of instructions, scripts, and resources that Claude loads dynamically”. Claude reads only the short description at first and loads the rest when your request matches it.
A skill is plain text you can read, diff, commit and share. It can also ship scripts, which is where the questions about trust begin and why this site reviews them. The catalog tracks 195 skill repositories and 88 individually reviewed skills. This guide covers what the format is, how it works, and what a skill is allowed to do on your machine.
What is inside a skill
At minimum, a skill is a directory with one file:
my-skill/
├── SKILL.md required: frontmatter plus instructions
├── scripts/ optional: code the agent can run
├── references/ optional: documents loaded when needed
└── assets/ optional: templates, images, data filesSKILL.md starts with YAML frontmatter, at least a name and a description, followed by Markdown instructions. The Agent Skills specification defines the format. We cover each field in the SKILL.md format guide.
The body can be anything that helps an agent do the job: steps, checklists, examples of good output, pointers to other files. Anthropic’s PDF example puts a quick start in SKILL.md and sends form-filling details to a separate FORMS.md that Claude opens only for form tasks.
Think of a skill as the onboarding document you would write for a new colleague, plus the helper scripts you would hand them. The agent already knows how to code and write. A skill adds your team’s conventions, a vendor’s gotchas and the order of steps that works.
How Claude skills work
Skills use progressive disclosure: the agent loads information in stages instead of reading everything up front. Anthropic’s overview describes three levels.
| Level | When it loads | Cost | What loads |
|---|---|---|---|
| Metadata | At startup, always | About 100 tokens per skill | name and description |
| Instructions | When the skill is triggered | Under 5k tokens | The body of SKILL.md |
| Resources | As needed | Nothing until read | Reference files and script output |
So ten installed skills cost you roughly a thousand tokens of descriptions, not ten full manuals. When you ask for something that matches a description, Claude reads that SKILL.md. If the instructions mention a reference file, Claude opens it only when the task needs it. If they mention a script, Claude runs it and only the output enters the context, not the script’s source.
Two consequences matter in practice.
First, the description is the trigger. Claude matches your request against it to decide whether to load the skill, so a vague description means a skill that never fires or fires at the wrong time. The overview says the description must state both what the skill does and when to use it.
Second, a skill can be big without being expensive. Files that are never read cost no tokens, so a skill with 70 rule files, like the Vercel React rulebook we review, loads one index and then only the rules a task touches.
You can also invoke a skill by hand. In Claude Code, /skill-name runs it directly, and the frontmatter can switch off automatic loading (disable-model-invocation: true) for skills with side effects, or hide a skill from the menu so only Claude can call it. The Claude Code skills docs list the full set of controls.
Where Claude skills live
Where you put a skill decides who can use it. Anthropic documents a different scope on each surface.
- Claude Code: personal skills in
~/.claude/skills/<skill-name>/SKILL.md, project skills in.claude/skills/<skill-name>/SKILL.md(commit them and the team gets them), and plugin skills that appear as/plugin-name:skill-name. Enterprise administrators can deploy skills through managed settings. See our Claude Code platform page. - claude.ai: you upload a custom skill as a zip file in Settings. Custom skills are individual to each user and are not shared across an organization. Team and Enterprise owners can provision skills for everyone.
- Claude API: you upload skills through the Skills API and reference them by
skill_idin thecontainerparameter alongside the code execution tool. Custom skills are shared workspace-wide.
Custom skills do not sync between surfaces. A skill uploaded to claude.ai is not on the API, and Claude Code skills are filesystem-based and separate from both.
The pre-built document skills for PowerPoint, Excel, Word and PDF (pptx, xlsx, docx, pdf) work on claude.ai and the API. Anthropic’s docs state that they are not available in Claude Code.
Types of skills
Anthropic’s help center names four kinds: skills Anthropic builds (the document skills), custom skills you or your organization write, organization-provisioned skills that Team and Enterprise owners distribute, and partner skills from companies such as Notion, Figma and Atlassian that are built to work with their connectors.
There is a fifth kind that the docs do not describe because it is not Anthropic’s: community skills on GitHub. This is where most of the volume is: our catalog covers 195 repositories, from one-skill repos to packs with hundreds of skills. Nobody vetted these for you, so you do the reading.
Skills also vary in weight. Some are a prompt in a file, such as a reply-style skill. Others point to a library of rules the agent reads on demand, and the heaviest bundle scripts, validators and templates so part of the work is deterministic. Our methodology scores this as a 1 to 5 depth rating. A short skill can be excellent at its job and a deep one can be a risk, so depth tells you what you are getting, not whether it is good.
Skills vs CLAUDE.md, MCP, subagents and plugins
Skills sit next to several other ways to shape an agent, and the boundaries confuse people.
CLAUDE.md is always loaded. A skill’s body loads only when it is used. The Claude Code docs recommend moving procedures out of CLAUDE.md into skills for this reason: long reference material costs almost nothing until you need it.
Slash commands were merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy, and existing command files keep working. Skills add a folder for supporting files and the invocation controls.
MCP connects Claude to external services and data. Skills carry the procedure for using those tools well. Anthropic’s help center puts it this way: MCP gives access, skills give know-how, and the two work together. Several skills we review exist to wrap an MCP server in sensible rules, such as the Supabase skill covered in our examples. For the longer comparison see skills vs MCP.
Subagents run a task in a separate context. A skill with context: fork can run inside a forked subagent, and a subagent can preload skills as reference material. See skills vs subagents.
Hooks run code every time an event occurs. If a rule must hold on every edit, the Claude Code docs say to move it from a skill into a hook, because Claude may not follow skill text on every turn. A skill can register its own hooks through the hooks frontmatter field.
Plugins package skills together with other extensions, which is how you distribute a set of them. Browse them on our plugins page.
Projects and custom instructions on claude.ai hold background that is always loaded. Skills activate only when a task needs them.
What a Claude skill can access
This is the part most guides skip. A skill is instructions, and sometimes code. What it can reach depends on where it runs.
Anthropic’s documentation is direct about the surfaces:
- Claude Code: skills have the same network access as any other program on your computer. A bundled script runs with your user permissions.
- Claude API: skills run in a sandboxed container with no network access and no runtime package installation.
- claude.ai: network access varies with user and admin settings.
The same overview carries a security warning: use skills only from trusted sources, because a malicious skill can direct Claude to call tools or run code in ways that do not match its stated purpose, which could lead to data exfiltration or unauthorized system access. It tells you to audit every bundled file, to be wary of skills that fetch external URLs (fetched content can contain instructions, and dependencies can change later), and to treat installing a skill like installing software.
We do that audit for each page in the catalog and record what the files show. Of the 283 pages we have reviewed (195 repositories and 88 single skills), 38 came out as “No issues found”, 174 as “Review before installing” and 71 as “Broad access”. Only 13% are clean, because most skills do at least one thing worth knowing about, such as calling a CLI, hitting a network endpoint or editing a config file. A few specific examples from our reviews:
- A Vercel design-review skill is a single small file that fetches its rules from a GitHub branch every time it runs, so its effective instructions can change without the skill changing.
- A Matt Pocock skill installs a Claude Code hook by editing your
settings.json. It is a useful guardrail, and it is also a skill that changes your configuration. - Anthropic’s pptx skill runs local Python helpers and LibreOffice, makes no network calls and declares no pre-approved tools.
- A one-line skill that only tells the agent to call another skill has nothing to audit in itself, but it does nothing unless the second skill is installed too.
Our scanner baseline shows why you cannot rely on pattern matching alone. In the last run, NVIDIA’s SkillSpector recommended “do not install” for 193 of 286 popular skills, mostly because instructions mention commands like git push. A scary scan is a lead, not a verdict. Read how we triage this on the security page.
How to read a skill before you install it
You do not need special tools. Open the folder and check these things, in this order:
- Frontmatter. Look for
allowed-tools,hooks,context: forkanddisable-model-invocation. Pre-approved shell access and registered hooks are the fields that widen what the skill can do. - Shell injection. In Claude Code,
!`command`lines inside a skill run before the content reaches Claude. Read each one. - Scripts. Anything in
scripts/runs on your machine. Look for network calls, file writes outside the project, and anything that installs packages. - Remote instructions. Search the Markdown for URLs the agent is told to fetch and follow.
- Installer. If the README says to pipe a script into a shell or run an installer, read that script first.
- Dependencies. A skill that needs another skill, a CLI or a paid API key is not a standalone download.
If a pack has hundreds of skills, install only the one you need.
Skills are an open format
The format is no longer Claude-only. Anthropic points to agentskills.io as the home of the Agent Skills specification, and other agents read the same SKILL.md layout. Codex scans .agents/skills in your repository and $HOME/.agents/skills for user skills, and Cursor looks in .agents/skills/ and .cursor/skills/ and also reads .claude/skills/ for compatibility. Each agent adds a few of its own frontmatter fields and behaviors, but a plain skill with name, description and a Markdown body travels. Our platform pages list the install path for each agent.
When a skill is the right tool
A skill earns its place when you keep pasting the same instructions, when the model gets a procedure wrong without help, or when a team should share a workflow through version control.
It is the wrong tool for a rule that must never be broken (use a hook or a permission rule), for access to a live service (that is MCP), and for a one-off request (just ask). It also does not guarantee quality. A skill is a prompt, and prompts can be thin. One of the most installed skills in our catalog is a single line that points to another skill. That is why we rate depth separately from popularity.
Frequently asked questions
Are Claude skills free? They are available on Free, Pro, Max, Team and Enterprise plans and require code execution to be enabled. Licenses vary, so check each repository. Our reviews flag proprietary ones, such as Anthropic’s docx and pptx skills.
Do I need to code to write one? No. A skill can be only Markdown. Anthropic’s skill-creator skill, which we review as a depth 5 example, interviews you and drafts the file.
Will Claude always use my skill? No. It uses a skill when the request matches the description. If it does not fire, rewrite the description with the words people actually use, or call the skill directly with /skill-name.
Where to go next
- See real examples in Claude skills examples, grouped by job.
- Learn the file format in the SKILL.md format guide.
- Install and write your own with the guides on installing skills and creating a skill.
- Browse the reviewed skills and our best skills lists.