What are Claude Code skills?
Anthropic introduced skills as "organized folders of instructions, scripts, and resources that agents can discover and load dynamically" in Equipping agents for the real world with Agent Skills (October 2025), and later published Agent Skills as an open standard. The idea is simple: instead of pasting the same long instructions into every session, you write them once as a skill, and Claude pulls them in when they're relevant.
What makes skills cheap is progressive disclosure, documented in Anthropic's Agent Skills overview. There are three levels:
- Metadata (the name and description) is always loaded, roughly 100 tokens per skill.
- The SKILL.md body loads only when the skill is triggered, and should stay under about 5,000 tokens.
- Bundled files load only when needed; scripts run through bash and only their output enters the context.
So you can install dozens of skills without filling the context window. That makes skills one of the most practical pieces of an agent harness: reusable know-how, loaded on demand.
The SKILL.md format
A minimal skill, from Anthropic's docs:
---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
---
# Your Skill Name
## Instructions
[Clear, step-by-step guidance for Claude to follow]
## Examples
[Concrete examples of using this Skill]- • name: up to 64 characters, lowercase letters, numbers, and hyphens only; it can't contain "anthropic" or "claude".
- • description: up to 1,024 characters, and it should say both what the skill does and when to use it. This is the line Claude matches against, so it decides whether your skill ever triggers.
- • Claude Code is more lenient. Per the Claude Code skills docs, no field is strictly required (the name defaults to the folder name), and there are extra optional fields such as
allowed-tools,disable-model-invocation,argument-hint, andcontext: fork. Stick tonameanddescriptionif you want the skill to work everywhere.
Where do skills live, and how are they triggered?
- • Personal:
~/.claude/skills/<name>/SKILL.md, available in all your projects. - • Project:
.claude/skills/<name>/SKILL.md, committed with the repo so your team shares it. - • Plugin: installed skills, namespaced as
/plugin-name:skill-name.
Claude loads a skill automatically when its description matches what you asked, unless the skill sets disable-model-invocation: true. You can also call it yourself with /skill-name plus arguments. Since Claude Code 2.1, custom slash commands and skills are the same thing: .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both give you /deploy.
Skills vs subagents vs MCP vs hooks vs plugins
Claude Code has five ways to extend it, and Anthropic's features overview draws the lines clearly:
| Feature | What it is | Use it for |
|---|---|---|
| Skill | Reusable knowledge or a workflow, loaded into the main context when relevant | Teaching Claude how your team does a recurring task |
| Subagent | An isolated worker with its own context that returns a summary | Delegating a big, self-contained job without filling your context |
| MCP server | A connection to external tools and data | Giving Claude access to a system (GitHub, a database, Slack) |
| Hook | A deterministic script that runs on lifecycle events | Rules that must always hold, such as formatting or blocking a command |
| Plugin | The packaging layer that bundles skills, hooks, subagents, and MCP servers | Sharing a complete setup with a team or the community |
Two quotes from that page settle most debates: MCP connects Claude to tools, and "Skills give Claude knowledge about how to use those tools"; and for anything that must always happen, "Put guardrails in hooks." A skill is guidance the model follows; a hook is code that runs regardless. More on MCP in What is MCP? and on subagents in multi-agent orchestration patterns.
How to create a Claude Code skill
- Pick a task you repeat and that Claude gets wrong without guidance: your release process, your API conventions, a report format.
- Make the folder:
.claude/skills/release-notes/(or under~/.claude/skills/for personal use). - Write SKILL.md: a name, a description that names the trigger ("Use when the user asks for release notes or a changelog"), then numbered steps and one worked example.
- Move bulk into files: long references go in separate markdown files the skill points to; repeatable logic goes in a script Claude runs.
- Test the trigger: ask for the task in a few different phrasings and check the skill loads; if it doesn't, the description is the thing to fix.
Or let Claude do it. Anthropic's skill-creator skill will "create new skills, modify and improve existing skills, and measure skill performance." Install it with:
/plugin install skill-creator@claude-plugins-officialIt works in a loop: capture what you want, draft the skill, write test prompts, run them, grade the results, and rewrite. It can store test cases in evals/evals.json, run them in isolated subagents, compare runs with and without the skill, and A/B two versions, which is the same discipline we recommend for any LLM feature in evaluating RAG systems.
Get the weekly AI engineering brief
Claude Code, skills, agents, and the tools worth using: one practical email a week for engineers. Plus the free roadmap PDF.
By subscribing you agree to receive emails from AI Engineer Insights. Unsubscribe anytime. See our Privacy Policy.
The best Claude skills to install first
Start with official skills from anthropics/skills; they are maintained, readable, and good examples of how to write your own. Descriptions below come from each skill's own SKILL.md:
| Skill | Source | What it does |
|---|---|---|
skill-creator | Official (anthropics/skills) | Builds new skills, runs evals on them, and tunes descriptions so they trigger reliably |
docx | Official | Creates and edits Word documents and templates |
pdf | Official | Extracts, merges, splits, fills forms in, and creates PDFs |
pptx | Official | Creates and parses slide decks |
xlsx | Official | Creates, cleans, and charts spreadsheets, including CSV and TSV |
frontend-design | Official | Gives UI work a distinctive design direction instead of templated defaults |
mcp-builder | Official | Guides you through building an MCP server in Python (FastMCP) or TypeScript |
webapp-testing | Official | Tests local web apps with Playwright, including screenshots and logs |
superpowers (obra/superpowers) | Community, not reviewed by Anthropic | A development-methodology pack of skills for planning, testing, and debugging |
To get the official document skills in Claude Code: /plugin marketplace add anthropics/skills, then /plugin install document-skills@anthropic-agent-skills. Most skills in that repo are Apache 2.0; the docx, pdf, pptx, and xlsx skills are source-available under a proprietary license. From the official plugin marketplace, code-review, feature-dev, commit-commands, and security-guidance are worth a look. Self-hosted agents use the same idea; see how Hermes Agent skills work.
The Claude skills marketplace: plugins and marketplaces
Skills are shared through plugins, which can bundle skills, agents, hooks, and MCP and LSP servers, and plugins are published in marketplaces. Anthropic runs three:
- • claude-plugins-official (
anthropics/claude-plugins-official): the official marketplace, added automatically the first time you run Claude Code interactively. - • claude-community (
anthropics/claude-plugins-community): community plugins; you add it yourself. - • claude-code-plugins (
anthropics/claude-code): demo plugins, which the docs note "isn't the official marketplace."
The commands you'll use:
/plugin # browse (Discover tab)
/plugin marketplace add owner/repo # add any marketplace
/plugin install <name>@<marketplace> # install a plugin
/plugin marketplace list | update | remove
claude plugin install <name>@<marketplace> --scope project # from your shellThere is also a web catalog at claude.com/marketplace/plugins that marks some plugins "Anthropic verified." Large community collections exist on GitHub, such as awesome-claude-skills lists, but treat them as directories, not endorsements.
Are Claude skills safe? What Anthropic recommends
- • "Use Skills only from trusted sources: those you created yourself or obtained from Anthropic." Read every bundled file first, and be wary of skills that fetch external URLs.
- • Plugins carry more risk: per Anthropic's plugin security docs, "A Claude Code plugin you install can execute arbitrary code on your machine with your user privileges." Hooks and MCP servers run outside the sandbox.
- • Check
hooks/hooks.json,.mcp.json, and anybin/folder before installing, and remember auto-updates can change files after you reviewed them. - • "Anthropic doesn't review third-party marketplaces." The same caution we give for vetting MCP servers applies here.
Skills in the Claude app and the API
Skills aren't only for Claude Code. In the Claude apps, Anthropic's help center says skills are available on Free, Pro, Max, Team, and Enterprise plans with code execution turned on, and Team and Enterprise owners can provision skills for everyone. On the API, skills require the code execution tool; prebuilt skills (pptx, xlsx, docx, pdf) are referenced by ID and custom skills are uploaded through /v1/skills. Custom skills don't sync between these surfaces, so keep the source in a repo.
Go deeper on Claude Code skills with AI
Ask your next question with this article as context. Opens in a new tab; you can edit the question before sending.
Frequently Asked Questions
What are Claude Code skills?
Skills are folders of instructions, scripts, and resources that Claude discovers and loads when a task needs them. Each skill has a SKILL.md file with a name and a description; Claude keeps only that short metadata in context and loads the full instructions, and any bundled files, when your request matches the description. In Claude Code you can also run a skill directly with /skill-name. Skills are an open standard (Agent Skills) and work in Claude Code, the Claude apps, and the Claude API.
How do I create a Claude Code skill?
Create a folder under ~/.claude/skills/ (for yourself) or .claude/skills/ (for a project), add a SKILL.md file with YAML frontmatter containing a name and a description that says what the skill does and when to use it, then write the instructions below it. Add reference files or scripts next to it if needed. The easiest route is Anthropic's skill-creator skill, installed with /plugin install skill-creator@claude-plugins-official, which drafts the skill, writes test prompts, runs evals, and improves the description.
What are the best Claude skills?
Start with Anthropic's official ones: skill-creator for building your own, the document skills (docx, pdf, pptx, xlsx), frontend-design, mcp-builder, and webapp-testing, all in the anthropics/skills repository. The official claude-plugins-official marketplace adds plugins such as code-review, feature-dev, commit-commands, and security-guidance. Popular community packs like obra/superpowers exist too, but Anthropic doesn't review third-party skills, so read them before installing.
Is there a Claude skills marketplace?
Yes. Skills are distributed through plugin marketplaces. Anthropic runs the official marketplace, claude-plugins-official, which Claude Code adds automatically, plus a community marketplace (claude-community) and a web catalog at claude.com/marketplace/plugins. You can add any marketplace with /plugin marketplace add owner/repo, for example /plugin marketplace add anthropics/skills, and install with /plugin install name@marketplace.
What is the difference between skills, subagents, MCP, and hooks?
A skill adds knowledge or a workflow to Claude's main context when it's relevant. A subagent is a separate worker with its own context that returns a summary. An MCP server connects Claude to external tools and data; skills teach Claude how to use them. A hook is a deterministic script that runs on events, which is where Anthropic recommends putting guardrails. A plugin packages any of these for sharing.
Are Claude skills safe to install?
Only from sources you trust. Anthropic's guidance is to use skills you wrote yourself or got from Anthropic, to audit every bundled file, and to treat installing a skill like installing software. Plugins are riskier still: Anthropic's docs warn that an installed plugin can execute arbitrary code on your machine with your user privileges, and that it doesn't review third-party marketplaces.
References
- • Anthropic — Claude Code skills docs
- • Anthropic — Agent Skills overview (format, progressive disclosure, security)
- • Anthropic Engineering — Equipping agents for the real world with Agent Skills
- • Anthropic — Claude Code features overview
- • anthropics/skills (GitHub)
- • Anthropic — Anthropic's plugin marketplaces
- • Anthropic — Plugin security
- • Claude Help Center — Using skills in Claude
Verified against Anthropic's docs on October 20, 2026.