Claude Code Skills: How to Build, Use, and Avoid Mistakes

Last Updated: October 3, 2026

Summary: Claude Code Skills are reusable folders of instructions, scripts, and reference files that Claude loads only when a task needs them. Anthropic launched the feature on October 16, 2025 and opened the underlying format as a public standard in December 2025, and search interest has climbed from near zero to 8,000 monthly US searches in under a year. This guide covers how skills work, how to build one, and the mistakes that cause them to misfire.

Most people who start customizing Claude Code run into the same wall. CLAUDE.md gets crowded with one-off instructions that only apply to a single task, context fills up with rules the model rarely needs, and repeating the same multi-step process to Claude in every session wastes time. Skills exist to fix that specific problem.

A skill is a folder that sits on disk until Claude actually needs it. When it's relevant, Claude loads the instructions inside; when it isn't, the folder costs nothing in context. That one design choice is why skills have become the default way developers package repeatable Claude Code workflows instead of stuffing everything into a single project file.

This guide covers what a Claude Code skill actually is, how the underlying mechanism works, how to build one step by step, where skills live on disk, how they differ from subagents, MCP servers, and plugins, and the mistakes that cause skills to misfire in practice. It's also one of the features that comes up in Claude Code vs. Cursor comparisons, since Cursor has no direct equivalent.

💡 Not sure which AI tool is actually right for your business?

Get the free guide, Which AI Tool Should You Actually Use? — a straightforward breakdown of the leading AI tools to help you pick the right one for your needs.

Subscribe to AI Business Weekly for the guide, plus daily coverage of AI trends, acquisitions, and product launches.

Get the Free Guide →

A Claude Code skill is a folder containing a SKILL.md file, written in YAML frontmatter plus markdown, along with any supporting scripts or reference files the task needs. Claude invokes it either automatically, when the task matches the skill's description, or manually, by typing a /skill-name command.

Anthropic shipped Agent Skills across Claude apps, the API, and Claude Code on October 16, 2025, as a direct answer to a recurring problem: giving Claude deep, specialized knowledge without permanently bloating its context window. Two months later, on December 18, 2025, Anthropic opened the SKILL.md format as a public standard, with early partners including Atlassian, Canva, Cloudflare, Figma, Notion, Ramp, and Sentry building their own skills on top of it, according to SiliconANGLE's coverage of the announcement. (Source: SiliconANGLE)

The search data backs up how fast this moved from niche to mainstream. "Claude code skills" went from essentially zero monthly US searches in late 2025 to 8,000 by October 2026, according to SE Ranking, a far faster climb than most developer-tooling features see. The jump tracks closely with the open-standard announcement and the wave of partner-built skills that followed, which suggests a lot of adoption is coming from teams installing ready-made partner skills first and learning to build their own second, not the other way around. For the usage trend behind the underlying tool, see our Claude Code statistics breakdown. (Source: Claude Code Skills documentation)

Claude Code skills work through progressive disclosure: Claude scans short skill descriptions every turn, then loads the full instructions for a specific skill only once it's actually invoked, instead of keeping every skill's full content in context window space at all times.

A SKILL.md file has two parts. The YAML frontmatter at the top defines the skill's name, a description that tells Claude when to use it, and optional settings like which tools it's allowed to call. The markdown body underneath is the actual instructions Claude follows once the skill loads.

This is a genuinely different design from Anthropic's own Model Context Protocol, which keeps a persistent connection to an external tool or data source running the whole session. A skill is stateless and file-based; it either isn't loaded, or it's loaded and sitting in context like any other message. Industry coverage of the skills launch has drawn the comparison directly, framing skills as Anthropic repeating the same open-standard playbook that made MCP the default way AI agents connect to outside tools, just applied to packaged expertise instead of live connections. (Source: The New Stack)

Building a working skill takes five steps, and the whole thing can be done in plain markdown with no coding required for a basic version.

A minimal real example, a skill that summarizes uncommitted git changes:

The ! backtick syntax runs a shell command and inserts its output before Claude ever sees the rest of the skill, which is how skills pull in live, current information instead of relying on stale instructions. (Source: Claude Code Skills documentation)

Claude Code checks five different locations for skills, in a fixed priority order, which matters when two skills share the same name.

An enterprise-managed skill always wins a name collision over a personal one, which is a deliberate design choice: organizations can lock down a shared "deploy" or "code-review" skill that individual engineers can't quietly override. Anthropic added this centralized admin layer specifically for Team and Enterprise plans alongside the December 2025 open-standard update, letting admins provision approved skills org-wide rather than relying on every engineer to set one up individually, according to VentureBeat's coverage of the launch. For most solo developers, the practical decision is simpler: personal skills for workflows that follow you across every project, project skills for anything the rest of the team needs to use the same way you do. (Source: VentureBeat)

Skills get confused with three other Claude Code concepts constantly, and the distinction actually matters for which one to reach for.

The simplest way to decide: if the need is "remember how to do this specific thing," it's a skill. If it's "research this independently without cluttering my current context," it's a subagent. If it's "talk to a live external system," it's MCP, and if the need is closer to "feed the model relevant knowledge retrieved from a large document store," that's really a RAG setup, not a skill. If it's "package several of the above into one installable thing for other people," it's a plugin. A skill can even run inside an isolated subagent context using the context: fork setting, which shows these aren't fully separate categories so much as composable layers. (Source: Claude Code Skills documentation)

Four mistakes account for most skills that don't work as expected, based on how the triggering and loading mechanism actually behaves.

A vague description field is the most frequent cause of a skill that Claude simply never invokes automatically. Claude's auto-trigger decision runs entirely on that description text; "handles deployment stuff" matches almost nothing, while "deploy the application to a named environment, use when the user asks to ship, release, or push to production" matches real phrasing people actually type.

A SKILL.md file that tries to hold everything, including long reference tables or full API documentation, instead of linking out to supporting files, blows past the practical 500-line guidance and risks hitting the per-skill context cap during auto-compaction, which silently truncates it to the first 5,000 tokens.

Treating the skill body as a one-time script rather than standing instructions causes drift across multiple turns; because skill content persists in context once loaded rather than being re-read from disk, instructions phrased as a single past-tense action ("I renamed the files") rather than a standing rule ("always check naming conventions before committing") stop guiding later turns in the same session.

And skipping the allowed-tools frontmatter field on a skill that runs shell commands means every command triggers a fresh permission prompt, which defeats the point of automating a repeatable task in the first place.

Treat SKILL.md as a table of contents, not an encyclopedia. The file itself should orient Claude and point to deeper material in separate linked files, which keeps the core skill light enough to stay well under the context cap even as the supporting documentation grows.

Write the description field the way a user would actually phrase the request, not the way an engineer would name the function. This single field decides whether the skill triggers automatically at all.

Use disable-model-invocation: true for anything destructive or expensive, like a production deploy, so it only runs when explicitly typed as a /command, and reserve automatic triggering for safe, informational skills.

Test with the skill both on and off using skillOverrides, so there's an actual before-and-after comparison rather than an assumption that the skill is helping. Anthropic's own skill-creator plugin supports this kind of A/B evaluation directly.

Start personal, promote to project-level only once a skill has proven useful across more than one task, since a project-level skill becomes a shared team dependency the moment it's committed to the repo.

The payoff for getting this right is real, not theoretical. Anthropic's enterprise customer Rakuten reported that an accounting workflow which "once took a day" now takes about an hour after building it as a skill, according to Anthropic's own case study. That's the kind of repeatable, document-heavy task skills are built for. (Source: Anthropic)

Claude Code skills are folders containing a SKILL.md file plus optional scripts and reference material that Claude loads only when a task actually needs them. They let Claude handle a repeatable workflow, like deploying an app or reviewing a diff, without permanently occupying context space.

They depend on a clearly written description field, since that's what triggers automatic loading, and on keeping the file focused since Claude Code enforces context budgets during auto-compaction. They don't replace CLAUDE.md, which still loads every turn for ongoing project context; skills are specifically for workflows that apply only sometimes. For the broader setup, see our guide on what Claude Code is.

Create a folder at ~/.claude/skills/<name>/ for a personal skill or .claude/skills/<name>/ at the repo root for a project skill, then add a SKILL.md file with a YAML frontmatter description and a markdown body of instructions.

The result depends on how precisely the description matches real phrasing people use, and on whether the instructions are written as standing rules rather than a one-off script. This covers the basic markdown-only skill; skills that need pre-approved tool access or isolated subagent execution require additional frontmatter fields covered in Anthropic's own documentation. Our guide on how to use Claude Code covers the broader setup around skills.

A skill shares the current session's context and is meant for a specific, repeatable task; a subagent runs in an isolated context with no visibility into the conversation history, meant for complex, multi-step work that benefits from a clean slate.

Which one fits depends on whether the task needs the existing conversation's context (skill) or actively benefits from not having it (subagent, for independent research or review). A skill can even run inside a forked subagent using the context: fork setting, so the two aren't mutually exclusive. This doesn't cover MCP servers, which solve a different problem: a live connection to an external system rather than packaged instructions.

They're the same underlying SKILL.md format and the same Agent Skills standard, but Claude.ai's skills (Excel, PowerPoint, Word, PDF handling built in by Anthropic, plus partner skills from Notion, Figma, and others) run inside the chat app, while Claude Code skills are specifically for developer workflows inside the CLI tool.

Portability depends on which product a given skill was built for and whether it needs filesystem or shell access that only Claude Code provides. Skills built for one product don't automatically work in another without adjustment. Anthropic's own support documentation covers the consumer-app side in more depth.

Yes. A project-level skill committed to .claude/skills/ at the repo root is tracked in git like any other file, so it ships to every teammate who pulls the repository, and enterprise-managed skills can be centrally provisioned to override personal ones.

Sharing successfully depends on the skill's instructions being general enough to apply across different teammates' workflows, not written for one person's specific setup. This covers skills built in-house; skills distributed through the public Agent Skills directory or a formal plugin follow a separate packaging and installation path. See our guide on AI agents for how skills fit into the broader agent-tooling picture.

Claude Code Skills are reusable SKILL.md folders that Claude loads only when a task needs them, launched by Anthropic on October 16, 2025 and opened as a public standard two months later. Search interest for the term has grown from roughly zero to 8,000 monthly US searches in under a year, a pace that tracks closely with the open-standard launch and the wave of partner skills that followed it.

Building one well comes down to a clear, user-phrased description field, a focused SKILL.md body under 500 lines with supporting detail pushed into linked files, and treating the instructions as standing rules rather than a one-time script. Get those three right, and a skill turns a repeated multi-step Claude Code task into a single reliable command.

By Sameer Khan

AI-assisted. Researched, reviewed, and edited by Sameer Khan before publication.