What Are Claude Code Skills? A Practical Guide

Claude Code skills are one of the more quietly powerful ways to extend Anthropic's agentic coding tool. At their core, they're reusable capabilities you package as a folder — a SKILL.md file plus any supporting scripts or reference material — that Claude can discover and load on its own when a task calls for it. Instead of pasting the same instructions into every session, you write a skill once and Claude pulls it in when it's relevant, or you invoke it directly. This article explains what skills are, how they're structured, where they live, and how they relate to slash commands and subagents. Claude Code follows the open Agent Skills standard, so the same model-invoked pattern shows up across several of Anthropic's products.

What are Claude Code skills?

A skill is a self-contained bundle of expertise that teaches Claude Code how to do a specific kind of task well. Think of a recurring workflow you keep explaining: how your team writes migration scripts, how you format a release changelog, how to run your project's accessibility audit, or the exact steps to scaffold a new API route. A skill captures that knowledge in a structured folder so Claude can apply it consistently without you re-typing the instructions every time.

A defining trait of Claude Code skills is that they are model-invoked by default: Claude reads the short description of each available skill, decides whether the current task matches, and loads the full instructions only when needed. You can also invoke a skill yourself by typing /skill-name, the same way you'd run a command. This loading pattern is called progressive disclosure — Claude sees just enough up front to know a skill exists, then pulls in the detail on demand.

How a skill is structured: the SKILL.md file

Every skill is a directory containing a SKILL.md file. That file has two parts: a small YAML frontmatter block with metadata, and a Markdown body with the actual instructions. The most important field is the skill's description — it's what Claude reads to decide whether the skill is relevant.

• description — a concise summary of what the skill does and, crucially, when Claude should use it. Per the official docs, the directory name becomes the command you type, and a clear, trigger-focused description is what lets Claude load the skill automatically.
• name — an optional display label shown in skill listings. If you omit it, Claude Code falls back to the directory name. It does not need to match the command name.
• instructions (the body) — the full Markdown content Claude loads once the skill is selected. This is where the step-by-step guidance, conventions, examples, and gotchas live.

The folder can hold more than just SKILL.md. You can include helper scripts, templates, reference documents, or example files alongside it and point to them from the instructions. Because the body only loads when the skill activates — and bundled scripts run via the shell without their source entering the context window at all — a skill can be richly detailed without bloating Claude's context on every turn. The description stays cheap, and the heavy content arrives just in time.

my-skill/
  SKILL.md          # frontmatter (description, optional name) + instructions
  reference.md      # optional supporting docs the instructions can point to
  scripts/
    run.sh          # optional helper script the skill can invoke

Where Claude Code skills live

Skills are kept in a skills directory under .claude. A project skill lives in .claude/skills inside your repository and is scoped to that project — ideal for conventions specific to one codebase, and easy to commit so your whole team shares it. A personal skill lives in your home directory at ~/.claude/skills and follows you across every project. Each individual skill gets its own subfolder containing a SKILL.md. Organizations can also distribute skills through managed settings, and plugins can bundle their own.

Because project skills are just files in your repo, they version like any other code: they show up in pull requests, get reviewed, and evolve with the codebase. If you've ever browsed the Claude Code changelog to see how the tool's capabilities have grown, skills fit that same philosophy of putting durable, shareable context into your project rather than into one-off prompts.

Skills vs. slash commands vs. subagents

Skills, slash commands, and subagents all let you extend Claude Code, but they're related rather than rival concepts. Worth knowing up front: in current Claude Code, custom commands have effectively merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create a /deploy command and behave the same way — skills simply add optional features like a folder for supporting files and frontmatter that controls who can invoke them.

The cleanest way to think about it: a skill is the reusable unit, and its frontmatter decides who gets to invoke it. By default both you and Claude can. You can restrict a skill to manual-only invocation (good for actions with side effects like deploys), or to model-only (good for background knowledge that isn't a meaningful command). Subagents are the separate idea: a worker Claude spins up in its own context — and skills and subagents compose, since a skill can even be configured to run inside a forked subagent. To go deeper, see our guides on Claude Code slash commands and Claude Code subagents.

Why Claude Code skills matter

The practical payoff of Claude Code agent skills is consistency and reuse without context bloat. A few reasons they're worth adopting:

• Reusability — encode a workflow once and Claude applies it across sessions and teammates, instead of relying on whoever remembers the right prompt.
• Progressive disclosure — only short descriptions stay loaded; the full instructions arrive when relevant, and bundled scripts run without loading their source, keeping context lean.
• Shareability — project skills commit to your repo, so the whole team benefits and improvements flow through normal code review.
• Composability — skills can reference scripts and other files, and pair naturally with subagents and commands.
• Lower prompt overhead — you stop re-explaining the same conventions in every conversation.

Skills shine for anything you'd otherwise document in a wiki and hope people read. Database migration conventions, your changelog format, environment-specific deploy steps, testing standards — all good candidates. If you're still mapping the broader vocabulary here, our Claude Code glossary covers how skills, subagents, commands, and other concepts relate.

How to use Claude Code skills

Getting started is deliberately lightweight. The general flow looks like this:

1. Create a folder for the skill under your project's .claude/skills directory (or ~/.claude/skills for cross-project use).
2. Add a SKILL.md with a description that states when the skill should be used. The directory name becomes the command, so name the folder for the command you want.
3. Write the instructions in the body — concrete steps, conventions, and examples Claude should follow.
4. Optionally add supporting scripts or reference files and point to them from the instructions.
5. Let Claude discover and invoke it automatically when a task matches the description, or run it yourself with /skill-name.

For the precise authoring format — required and optional frontmatter fields, naming rules, and how to reference bundled files — follow the official Claude Code documentation. If you want to track how skills and related features land over time, the public Claude Code changelog on GitHub is the source of truth, and you can browse a readable view on our changelog hub.

Conclusion

Claude Code skills turn your repeated instructions into durable, shareable capabilities — packaged as a simple SKILL.md folder, loaded through progressive disclosure, and scoped to a project or to you. They unify what used to be separate slash commands, they let you control whether you or Claude triggers them, and they pair naturally with subagents for focused, isolated work. Any team that wants consistent, low-friction workflows benefits. Want to stay current as new capabilities ship? Browse the Claude Code changelog or grab the Claude Drops app to get a push notification the moment a new release lands.