A Claude Code skill is a folder with a SKILL.md file of instructions that teaches Claude how to do a specific task, loaded only when your request matches it. Think of a skill as reusable, on-demand expertise rather than a one-off prompt.
A one-off prompt lives and dies in a single chat. A skill is saved to disk, so Claude can reach for it again and again across sessions.
Anthropic introduced Agent Skills on October 16, 2025, describing them as "a new way to build specialized agents using files and folders." The format is deliberately simple: plain files you can read, edit, and share.
Key point: A skill is just a folder plus a Markdown file. No plugin, no build step, no special runtime is required to make one.
How Claude Code Skills Work
Skills stay out of your way until you need them. Claude first scans only the name and short description of each installed skill, matches them against your task, then loads the full instructions on demand.
This on-demand loading is called progressive disclosure: Claude reveals a skill's details in stages instead of all at once. It keeps the context window lean, so dozens of skills add almost nothing until one is triggered.
The token cost is small and staged. Per the progressive disclosure docs, "Level 1: Metadata — Always (at startup) — ~100 tokens per Skill; Level 2: Instructions — When Skill is triggered — Under 5k tokens."
Skills can also bundle more than instructions. A skill folder can include helper scripts and reference files that Claude pulls in only when the task calls for them.
- Level 1 (Metadata): name and description, always loaded, about 100 tokens each.
- Level 2 (Instructions): the full
SKILL.mdbody, loaded only when triggered, under 5k tokens. - Level 3 (Bundled files): scripts and reference docs, read only when needed.
Skills vs. Slash Commands vs. MCP vs. CLAUDE.md
Claude Code gives you four ways to shape its behavior, and beginners often confuse them. The table below shows what each one is and when to reach for it.
Note that slash commands and skills now share the / interface, so you invoke both the same way.
| Mechanism | What it is | Best for | How you trigger it |
|---|---|---|---|
| Skill | A folder with SKILL.md instructions and optional scripts | Multi-step tasks and reusable expertise | Automatically on match, or by name via / |
| Slash command | A saved prompt template | Quick, repeatable prompts | Typing /command-name |
| MCP server | An external service exposing tools and data over a protocol | Live data, APIs, and third-party actions | Claude calls the server's tools |
| CLAUDE.md | A project instructions file | Always-on rules and project context | Loaded automatically every session |
Key point: Use CLAUDE.md for rules that always apply, and a skill for expertise you want loaded only when relevant.
Key point: Use an MCP server when your task needs live data or an external action, not just instructions.
The SKILL.md File Format
Every skill centers on one file: SKILL.md. It has two parts — YAML frontmatter at the top and Markdown instructions below.
YAML frontmatter is the small block between two --- lines that holds settings. The key field is description, which tells Claude when to use the skill; name is optional and defaults to the skill's folder name.
Here is a minimal, copy-pastable example:
---
name: commit-helper
description: Write clear git commit messages from staged changes. Use when the user asks to commit or write a commit message.
---
# Commit Helper
When asked to commit:
1. Run `git diff --staged` to review the staged changes.
2. Summarize the change in one imperative line under 72 characters.
3. Add a short body explaining why the change was made.
4. Propose the message and wait for confirmation before committing.A few optional frontmatter fields give you more control:
allowed-tools: limits which tools the skill can use, such asReadorBash.disable-model-invocation: stops Claude from auto-triggering the skill, so it runs only when you call it.argument-hint: shows the expected input when you invoke the skill by name.
Keep the file focused. Claude Code's skills documentation advises to "Keep SKILL.md under 500 lines," and to move detailed reference material into separate bundled files.
Where Skills Live: Personal, Project, Plugin, and Enterprise
Skills load from four locations, and the path decides who can use them. The four scopes are personal, project, plugin, and enterprise.
- Personal:
~/.claude/skills/— available to you across every project. - Project:
.claude/skills/— checked into the repo and shared with your team. - Plugin: installed from a plugin marketplace as a bundle.
- Enterprise: deployed by an admin to a managed location for the whole organization.
When names collide, precedence decides which wins. Enterprise skills take priority, then personal, then project, and any of these can override a bundled skill.
Key point: Put team skills in .claude/skills/ and commit them to version control, so everyone gets the same behavior.
How to Install a Claude Code Skill
There are two simple paths to install a skill. Both take a minute or less.
The first path is manual. Drop a skill folder into ~/.claude/skills/ for personal use or .claude/skills/ for a single project.
The second path uses the plugin marketplace. Run these commands inside Claude Code:
/plugin marketplace add owner/repo
/plugin install skill-nameAfter either method, reload or restart Claude Code so it picks up the new skill. Then check that Claude scanned it by asking it to list available skills.
How to Create Your Own Skill (Step by Step)
Creating a skill takes five short steps. You only need a folder and a text editor.
- Create the folder. Make a directory in
~/.claude/skills/, for example~/.claude/skills/pr-summary/. - Add
SKILL.md. Inside that folder, create aSKILL.mdfile with the frontmatter and instructions shown earlier. - Write a specific
description. Include the trigger phrases users will actually type, such as "summarize a pull request." - Keep it concise. Stay under 500 lines and move long references to separate files in the folder.
- Test and iterate. Invoke the skill on a real task, watch what Claude does, then tighten the instructions.
The description is the single most important field. Because Claude matches your request against it, a vague description means the skill never activates.
Key point: Write the description around the words a user would say, not around the skill's internal name.
If you want a head start, Claude Code ships a skill-creator helper that scaffolds a new skill folder and SKILL.md for you.
Giving Your Skills Live, Reliable Web Data
Many skills need current web content, such as docs, pricing pages, and search results. But Claude Code's native web tools are limited: search results can be outdated, and fetch often returns too much raw content. A cleaner approach is to have the skill call an external web-data tool or MCP server that returns structured Markdown or cited JSON.
You can connect Olostep to Claude Code both as an MCP server and through Agent Skills. That lets a skill request clean, structured web data instead of parsing messy HTML itself.
Consider two concrete examples:
- A docs skill: it calls a tool to crawl documentation sites at scale and saves each page as Markdown for Claude to read.
- A research skill: it queries a real-time web search API and returns cited answers rather than stale snippets.
Under the hood, a skill points at Olostep's MCP server and gets back clean outputs. This is one option for skills that need live web data, not a requirement — a skill with no web dependency needs none of it.
Examples of Useful Claude Code Skills
You do not have to start from scratch. Claude Code bundles several skills, and the community shares many more.
Bundled skills you can use right away, as listed in the Claude Code documentation, include:
/code-review: reviews your changes or a pull request./debug: reads the session debug log to diagnose issues./run: launches and drives your app to see a change working./verify: builds and runs your app to confirm a change does what it should.
Popular community skill categories include:
- Planning and spec-driven workflows: turn a rough idea into a structured plan before coding.
- Code review and quality gates: enforce tests, linting, and TDD-style checks.
- Infrastructure and DevOps: scaffold config, manage deploys, and check settings.
- Web-data skills: fetch live pages through a web scraping API and return clean Markdown instead of raw HTML.
That last category matters because agents often act on stale assumptions without fresh input. A short read on the web data in agentic workflows explains why live data improves agent reliability.
The Best Claude Code Skills to Try
These are widely-used community skills worth knowing. Still vet each one before you install it, using the safety checklist below.
| Skill | What it does | Source |
|---|---|---|
| Superpowers | An end-to-end methodology skill that walks Claude through spec, planning, test-driven development, and review before it writes code. | obra/superpowers |
| Planning with Files | Keeps Claude on track during long tasks by writing its plan, findings, and progress to Markdown files on disk. | OthmanAdi/planning-with-files |
| Web Quality Skills | Addy Osmani's collection covering performance, Core Web Vitals, accessibility, and SEO. | addyosmani/web-quality-skills |
| HashiCorp Agent Skills | Official Terraform skills for generating code, writing tests, and building modules. | hashicorp/agent-skills |
| Code Simplifier | Anthropic's skill that cleans up recently changed code without altering its behavior. | anthropics/claude-plugins-official |
| mattpocock/skills | TypeScript-focused workflow skills, including strict TDD and refactoring plans. | mattpocock/skills |
Install these from trusted sources only, and read each skill's SKILL.md before you run it.
Are Claude Code Skills Portable? The Open Standard
Skills are not locked to Claude Code. They use one file format that works across several AI tools.
Anthropic published as an open standard the skills format: "We've ... published Agent Skills as an open standard for cross-platform portability. (December 18, 2025)." That decision made the format shareable beyond a single product.
Because of the open Agent Skills standard, the same skill runs across a growing set of tools, including Claude Code, OpenAI Codex, Cursor, and VS Code with GitHub Copilot. The payoff is simple: build a skill once, then use it across your tools.
Skill Safety: Vet Before You Install
A skill is instructions plus scripts that run in your own environment. Treat a third-party skill like any other dependency you add to a project.
The risk is real. A security review of agent skills found that "36.82% (1,467 skills) have at least one security flaw," and confirmed 76 malicious payloads across the ecosystem.
Before installing a skill from someone else, run through this quick checklist:
- Read the
SKILL.md. Confirm the instructions match what the skill claims to do. - Inspect bundled scripts. Any script in the folder can run on your machine, so review it.
- Check the source. Prefer skills from the official marketplace, Anthropic, or a maintainer you trust.
- Review
allowed-tools. A skill that only summarizes text should not request broad file or shell access.
Frequently Asked Questions
Are Claude Code skills free to use?
Skills themselves are just files, so they add no cost beyond your existing Claude plan and usage. Any external tool a skill calls, such as a web-data API, may carry its own pricing.
What's the difference between a skill and a slash command?
Slash commands were fixed prompt templates, while skills add frontmatter, supporting files, and subagent execution. The two have since merged under the / interface, so you invoke both the same way.
Do Claude Code skills work in other AI tools?
Yes — the skills format is an open standard adopted by several agents beyond Claude Code. That means a skill you build can run in tools like OpenAI Codex, Cursor, and VS Code with GitHub Copilot.
How many skills can I install?
You can install many, because progressive disclosure keeps only each skill's name and description in context until it is triggered. As a result, dozens of skills add roughly 100 tokens each and stay out of your way until needed.
Where do I find good skills to install?
Start with the official plugin marketplace and Anthropic's skills repository, then supplement with community lists. Always vet a skill's SKILL.md and scripts before installing it.
