Claude Skills: What They Are and How to Install Them

Claude Skills are folders of instructions that Claude loads only when a task calls for them. Each one is a directory with a SKILL.md file: a short name and description at the top, then the steps Claude should follow. Claude Code, the Claude apps and the Claude API all support them, though each surface stores them separately. Anthropic's examples live in the anthropics/skills repository. We checked the docs on 31 October 2026.

This page is the hub for the topic. It explains the format, how each product loads a skill, where to find skills, and how to install one. It also lists the skill collections that have a live page on our site. For the longer explainers, see our Agent Skills directory and install guide and the glossary entry on Agent Skills.

What an Agent Skill is

A skill is a reusable bundle of know-how. Anthropic's overview describes it as a filesystem-based resource that gives Claude domain-specific expertise: workflows, context and best practices that turn a general-purpose agent into a specialist. A prompt covers one conversation. A skill loads on demand, so you do not repeat the same guidance in every chat.

The smallest skill is one file.

---
name: my-skill-name
description: A clear description of what this skill does and when to use it
---

# My Skill Name

[Instructions Claude follows when this skill is active]

That layout comes straight from the anthropics/skills README. The frontmatter needs a name and a description. The markdown below holds the instructions, examples and guidelines.

A bigger skill adds supporting files. The Claude Code docs show a folder like this:

my-skill/
├── SKILL.md           (required: overview and navigation)
├── reference.md       (detailed docs, loaded when needed)
├── examples.md        (usage examples, loaded when needed)
└── scripts/
    └── helper.py      (utility script, executed, not loaded)

Claude Code skills follow the open Agent Skills standard, which Anthropic says works across several AI tools. Claude Code then adds its own features on top: control over who invokes a skill, running a skill in a subagent, and injecting live command output into the prompt.

Field rules worth knowing

The API and claude.ai docs set limits on the two required fields.

The description does the real work. Anthropic says Claude matches your request against it to decide whether to trigger the skill, so it must say both what the skill does and when to use it. Claude Code is looser: all fields are optional there, and only description is recommended. It also adds a when_to_use field for trigger phrases, and caps the combined description text at 1,536 characters in its skill listing.

How skills load: progressive disclosure

The main design idea is that Claude does not read every skill up front. Anthropic describes three levels.

Here is how the docs walk through a PDF skill. At startup the system prompt carries only the skill's name and description. You ask for text from a PDF. Claude decides the description matches, and reads SKILL.md using bash. If that file points at a forms guide and your task does not need it, Claude never opens it. If a script is needed, Claude runs it and only the output enters the context, not the code.

Two consequences follow. You can install many skills without paying much for the idle ones, since only their names and descriptions sit in context. And a skill can bundle a lot of reference material, because unused files cost nothing.

Claude Code limits the always-on listing. It loads skill names and descriptions into context, with a character budget of 1% of the model's context window. When you have too many skills, it drops descriptions, starting with the skills you invoke least, and the keywords Claude needs to match your request can vanish. The docs give two fixes: raise skillListingBudgetFraction, or set low-priority skills to "name-only" in skillOverrides.

How each Claude product loads skills

The same format runs in several places, but the details differ. This is the part people get wrong.

Claude Code

Claude Code reads skills from several locations, and the location decides which sessions see a skill.

When two skills share a name, enterprise beats personal, and personal beats project. Plugin skills never clash because they carry the plugin name as a prefix.

You call a skill two ways. Claude can pick it up on its own when your request matches the description. Or you type / and the skill name. Claude Code watches the skill folders, so an edit during a session takes effect without a restart, with one exception: a top-level skills folder that did not exist when the session started needs /reload-skills.

Custom commands have been merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy. The old command files still work, but skills add a directory for supporting files and control over who invokes them.

Claude Code also ships bundled skills, such as /doctor, /code-review, /batch, /debug, /loop and /claude-api. They are prompt-based: they give Claude detailed instructions and let it orchestrate the work with its tools. A setting, disableBundledSkills, turns them off. If you have not installed the tool yet, start with the Claude Code listing and the first-run guide.

The Claude apps

On claude.ai, Anthropic's pre-built document skills for PowerPoint, Excel, Word and PDF are active when you create documents, with no setup. Custom skills are uploaded as zip files under Settings > Features. They are available on Pro, Max, Ultra, Team and Enterprise plans with code execution on. Anthropic also notes that custom skills there belong to one user. They are not shared across the organization, and admins cannot manage them centrally.

The API

On the API, a skill rides along in the container parameter of a Messages request, and the code execution tool must be enabled. A request can carry up to 20 skills. The documented shape for an Anthropic-managed skill looks like this.

{
  "container": {
    "skills": [
      { "type": "anthropic", "skill_id": "pptx", "version": "latest" }
    ]
  }
}

The pre-built skill ids are pptx, xlsx, docx and pdf. You upload your own through the Skills API. The upload limit is 30 MB for all files combined, uncompressed. Skills run in a sandboxed container with no network access and no runtime package installation, so a skill that calls an external API will not work there. Anthropic's overview also notes that Agent Skills are not covered by zero data retention arrangements, and that data is kept under the standard retention policy.

Skills do not sync

Anthropic states this plainly: custom skills do not sync across surfaces. A skill uploaded to claude.ai is not on the API, a skill uploaded through the API is not on claude.ai, and Claude Code skills are separate from both. If you use two surfaces, you maintain two copies. Cloud and Cowork sessions also do not read ~/.claude/skills/ on your machine, so a scheduled cloud task that calls a personal skill reports it as not found.

The official skills repository

Anthropic publishes its examples at github.com/anthropics/skills. The README calls it Anthropic's implementation of skills for Claude and says the examples range from creative work (art, music, design) to technical tasks (testing web apps, MCP server generation) to enterprise workflows. The repo has a skills folder of examples, a spec folder holding the Agent Skills specification, and a template folder for starting your own.

Licensing is mixed, and the README says so. Many skills are open source under Apache 2.0. The document skills for docx, pdf, pptx and xlsx, which power Claude's document features, are source-available and not open source. The README also states that these skills are provided for demonstration and educational purposes, that your results in Claude may differ, and that you should test any skill thoroughly before relying on it.

Our listings follow the same split. The Skill Creator skill and the frontend-design skill are Apache 2.0 entries from that repo, and the document skills are listed with a proprietary licence.

Install a skill

How you install depends on the surface. Here are the common routes, each from the docs.

In Claude Code, from the official marketplace

Register the repository as a plugin marketplace, then install a plugin from it.

/plugin marketplace add anthropics/skills

/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills

The README's other route is the menu: choose Browse and install plugins, pick anthropic-agent-skills, pick document-skills or example-skills, and select Install now. After install, you use a skill by mentioning it. The README's example is asking Claude Code to use the PDF skill to extract form fields from a file.

In Claude Code, by hand

Make a folder and drop a SKILL.md in it.

mkdir -p ~/.claude/skills/summarize-changes

Then write ~/.claude/skills/summarize-changes/SKILL.md. For a project skill, use .claude/skills/ inside the repo and commit it so the team gets it too. A symlink to a folder elsewhere on disk also works, and Claude Code loads the skill once even if several locations point to the same target.

Some names are reserved. Do not call a folder synced, since Claude Code uses ~/.claude/skills/synced/ for skills downloaded from claude.ai. A folder named anthropic-skills outside a plugin does not load.

On claude.ai

Zip the folder and upload it under Settings > Features, on a plan that has code execution on. Anthropic's Help Center has articles on using skills in Claude and creating custom ones, linked from the repository README.

On the API

Upload through the Skills API, then reference the returned skill id in the container parameter. The skill files are copied into the container at /skills/{skill-name}/.

Vet before you install

Anthropic's security note is direct: use skills only from sources you created or got from Anthropic, because a malicious skill can direct Claude to call tools or run code in ways that do not match what the skill claims. If you must use an unknown skill, read every file in it, including scripts, and look for unexpected network calls or file access. Treat it like installing software. Skills that fetch data from outside URLs carry extra risk, since fetched content might hold instructions of its own. Claude Enterprise organizations can turn on content scanning for custom skills uploaded in claude.ai and Cowork, though the docs say scanning does not cover skills uploaded through the API or Console.

Our skills-vs-MCP comparison covers when a skill is the wrong tool, and subagents versus skills covers the other common mix-up.

Write your own

A good first skill is a procedure you keep pasting into chat. The Claude Code docs say to create a skill when you keep pasting the same checklist or multi-step procedure, or when a section of CLAUDE.md has grown into a procedure rather than a fact. Unlike CLAUDE.md content, a skill's body loads only when used.

The docs' own starter example is a skill that summarizes uncommitted changes. Its frontmatter has one line, a description that says what it does and when to use it. Its body uses a dynamic context line that runs git diff HEAD and inlines the result before Claude sees the skill. You then test it two ways: ask "What did I change?" and let Claude invoke it, or type the slash command.

Useful Claude Code fields beyond name and description:

Claude Code ignores a field name it does not recognize and does not report an error, so a typo fails silently. Field names use lowercase words with hyphens, except when_to_use. And the frontmatter counts only if the opening --- is the first line of the file.

Our step-by-step walkthrough is How to Write a Claude Code Skill That Triggers. The Skill Creator skill listed above can also draft and test skills for you.

Troubleshooting a skill that misbehaves

The Claude Code docs list the usual failures.

• It does not trigger. Check that the description holds words people would naturally say. Check it appears when you ask "What skills are available?". Try rephrasing, or invoke it with /skill-name. If the YAML is malformed, the body still loads with empty metadata, so the slash command works but Claude cannot match the description. Run with --debug to see the parse error.
• It triggers too often. Make the description more specific, or add disable-model-invocation: true.
• Claude stops following it. Skill content enters the conversation when invoked and is not re-read on later turns. Word guidance so it applies to the whole task. After the conversation is compacted, invoke the skill again, and put the most important lines near the top.
• A rule must hold every time. Move it into a hook, which runs every time its event fires. Our hooks guide shows how.
• Personal skills vanished. Look in ~/.claude/skills/.trash/. Before Claude Code 2.1.280, a manifest.json in ~/.claude/skills/ could cause listed folders to be moved there.

Skill collections live on our site

These listings are published on aiagentduo.com today. Descriptions come from our own pages and the sources each page cites. We list them for orientation, not as an endorsement. Read the security note above before installing any of them.

Two of those rows are worth a note. SkillSpector is the one to look at if you are worried about the security risk the docs describe, since it is listed as a security workflow. The Twilio and Salesforce rows are MCP servers first, and their pages explain how their skills fit in.

For a wider list, our Agent Skills directory and the add-ons index hold more.

A short checklist before you rely on a skill

1. Read SKILL.md and every script in the folder.
2. Check the licence. The repo split between Apache 2.0 and source-available is real.
3. Confirm which surface you need. A Claude Code skill will not appear in claude.ai.
4. Write a description that says what and when, and test it with two or three natural requests.
5. Keep the instructions short and put bulky reference text in separate files.
6. Move any must-never-fail rule out of the skill and into a hook.

Our take

Skills are the lightest way to teach Claude a repeatable procedure. They cost almost nothing while idle, they are plain markdown, and they are easy to review in a pull request. That makes them a better first move than a custom subagent or an MCP server for most procedures, though the three solve different problems.

The weak spots are all in the docs. No sync between surfaces means duplicate upkeep. The listing budget in Claude Code means a pile of skills can crowd out the descriptions that make them trigger. And a skill is only as safe as its author. We have not run these skills ourselves. This page is built from Anthropic's published documentation and the repository README, so if a path or command differs on your version, trust the docs over us.