Claude Code Skills: How to Build and Use Them in 2026

Claude Code skills are one of the highest-leverage features in the Anthropic stack right now. If you use Claude Code regularly and you are still stuffing every workflow into CLAUDE.md or repeating the same prompt by hand, you are leaving a lot on the table.

The timing is good too. Anthropic formally introduced Skills across Claude in late 2025, expanded them in early 2026, and the last two weeks brought a visible wave of new tutorials, plugin ecosystem posts, and developer confusion around one basic question: what exactly is a skill, and how is it different from a slash command or a plugin?

This guide answers that, then shows you how to build a Claude Code skill that is actually useful in a real codebase.

Why Claude Code skills matter right now

There are three reasons this keyword is worth caring about in March 2026.

First, the feature is no longer niche. Anthropic now treats Skills as a core extension model across Claude apps, Claude Code, the API, and the broader Agent Skills standard. That means this is not some temporary hack hidden in a beta branch. It is part of how Anthropic expects developers to customize agents.

Second, the docs changed in a way that created search demand. Claude Code used to have a cleaner separation between custom commands and skills. Now custom commands have effectively been folded into skills, and both surface as slash-invoked tools. That is useful, but it also means a lot of developers are searching for the same thing in different words: Claude Code skills, Claude commands, Claude slash commands, Claude plugins, and how they fit together.

Third, this is a practical developer feature, not a hype keyword. People searching for Claude Code skills usually want one of three things:

to install something that saves time immediately
to package a repeatable workflow for themselves or their team
to understand whether skills are the right abstraction versus plugins, MCP servers, or plain prompt files

That is exactly the kind of intent you want on a site like agentincome.io.

What Claude Code skills actually are

A Claude Code skill is a folder with a SKILL.md entrypoint and, optionally, supporting files like templates, examples, or scripts.

At minimum, the file looks like this:

---
name: deploy-check
description: Review deployment readiness before a release. Use when checking release risk, test coverage, migrations, and rollback plans.
---

When invoked, do the following:
1. Inspect the changed files
2. Check test coverage for touched areas
3. Look for schema or config changes
4. Summarize release risks and rollback steps

That looks simple because it is. The clever part is not the file format. The clever part is how Claude uses it.

Claude Code loads lightweight metadata up front, uses the description to decide when a skill is relevant, and only reads the heavier instructions or supporting files when needed. Anthropic calls this progressive disclosure. In practice, it means you can package domain knowledge and workflows without bloating every session with a giant system prompt.

If you already read the Claude API tutorial, this should feel familiar. The same core idea applies everywhere: keep the default context lean, then load the right instructions at the moment they matter.

Claude Code skills vs commands vs plugins

This is where most of the confusion comes from.

Skills

Skills are prompt-based capabilities. They can include instructions, supporting files, tool permissions, model overrides, and even subagent execution behavior. Claude can invoke them automatically when relevant, or you can run them manually with /skill-name.

Built-in slash commands

Built-in slash commands like /help, /clear, or /compact are fixed product behaviors. They are not your custom workflow layer. They are product commands.

Old custom commands

Claude Code used to support .claude/commands/*.md as a separate concept. Those still work, but Anthropic now treats skills as the preferred path. In other words: new custom behavior should generally live in .claude/skills/<name>/SKILL.md.

Plugins

Plugins are packaging and distribution. They bundle extension points like skills, hooks, subagents, and MCP servers so you can install or share them together.

That distinction matters:

Skill = the behavior or workflow
Plugin = the box you ship it in
MCP server = the tool surface the model can call
Built-in command = product-native command logic

If you remember only one thing, remember this: a skill teaches Claude how to do something. An MCP server gives Claude tools it can use. A plugin helps you install and share the whole setup.

If you need a refresher on MCP specifically, read the MCP server tutorial. Skills and MCP are complementary, not competing ideas.

Where Claude Code skills live

You can scope skills at different levels:

~/.claude/skills/<skill-name>/SKILL.md for personal skills across all projects
.claude/skills/<skill-name>/SKILL.md for project-specific skills
plugin-provided skills when a plugin is enabled
enterprise-managed locations if your org distributes them centrally

For most solo developers, the choice is simple:

put reusable personal habits in ~/.claude/skills
put repo-specific workflows in .claude/skills

A good project skill knows something about that codebase. A good personal skill knows something about how you like to work.

Your first useful Claude Code skill

Do not start with a giant autonomous workflow. Start with something you already repeat by hand.

A good first skill for most developers is a pre-commit reviewer.

Create the directory:

mkdir -p .claude/skills/pre-commit-review

Then create .claude/skills/pre-commit-review/SKILL.md:

---
name: pre-commit-review
description: Review staged or recently changed code before commit. Use when checking for bugs, missing tests, risky assumptions, and unnecessary complexity.
argument-hint: [optional focus]
---

When this skill runs:

1. Inspect the changed files first.
2. Identify correctness risks before style issues.
3. Flag missing tests, migrations, env changes, and breaking interface changes.
4. Suggest the smallest fix that reduces risk.
5. End with a short ship/no-ship recommendation.

If the user provides a focus area, prioritize it.

Now you can run it directly:

/pre-commit-review

Or:

/pre-commit-review focus on migrations and rollback risk

This is the right level of ambition for a first skill. It packages judgment, not just syntax.

Add supporting files so the skill stays small

The biggest mistake people make with Claude Code skills is cramming everything into one giant markdown file.

A better pattern is:

pre-commit-review/
├── SKILL.md
├── checklist.md
├── examples/
│   └── good-review.md
└── scripts/
    └── changed-files.sh

Then your SKILL.md can stay lean:

---
name: pre-commit-review
description: Review changed code before commit. Use when checking for bugs, tests, and release risk.
---

Read `checklist.md` for the full review checklist.
Read `examples/good-review.md` for the preferred output format.
Use `scripts/changed-files.sh` if you need a quick changed-file summary.

This matters for two reasons.

First, smaller entry files make invocation more reliable. Claude has a clearer summary of when to use the skill.

Second, supporting files make the workflow easier to maintain. If your review checklist changes, you update one file instead of rewriting the whole skill.

Anthropic’s own Agent Skills design guidance pushes this same idea: keep the top layer small, then let the agent load more detail only when needed.

When Claude should invoke a skill automatically

Not every skill should auto-trigger.

Claude Code lets you control this with frontmatter.

If a skill is background knowledge or a broadly useful workflow, automatic invocation is great. For example:

coding conventions
API response format rules
repo-specific testing patterns
architecture explainer skills

But if a skill does something deliberate or potentially expensive, make it manual.

For example:

---
name: deploy
description: Deploy the application to production
context: fork
disable-model-invocation: true
---

That tells Claude not to fire it automatically. Good. You do not want a deployment workflow activating because a prompt vaguely mentioned releases.

My rule is simple:

Auto-invoke for guidance and reusable context
Manual invoke for side-effect-heavy workflows

That same rule keeps your skills useful instead of surprising.

A better mental model: skills are reusable operating procedures

The easiest way to misuse skills is to treat them like a place to dump random prompts.

A better way to think about them is this: a skill is a reusable operating procedure for an agent.

That means a good skill usually has four ingredients:

a crisp trigger condition in the description
a clear sequence of actions
a preferred output format
boundaries about what not to do

If you are already doing agentic coding, this should sound familiar. The best agent workflows are not magic. They are good process design wrapped in the right interface.

Common mistakes when building Claude Code skills

1. Writing vague descriptions

If the description is mushy, invocation gets mushy.

Bad:

---
description: Helps with development tasks
---

Better:

---
description: Reviews changed backend files for auth, validation, and error-handling bugs. Use after editing API routes or middleware.
---

Claude needs concrete cues.

2. Mixing multiple unrelated jobs

One skill should not be a code reviewer, deploy helper, changelog writer, and bug triager at the same time.

Split them. Smaller skills are easier to trigger, debug, and trust.

3. Forgetting the output format

If you want structured output, say so.

Do not hope Claude will guess your preferred shape. Include the format directly in the skill instructions.

4. Using skills where a tool is the real need

If the hard part of the task is external access, you probably need an MCP server, a script, or another tool integration. A skill can teach workflow, but it does not replace tool access.

5. Making dangerous workflows automatic

Anything that deploys, writes broadly, deletes files, or changes infrastructure should generally be manual.

Convenience is nice. Surprise production changes are not.

Security and trust: the boring part that matters

Anthropic is explicit about this in its Skills guidance: skills can contain instructions and executable code, which means a bad skill can do bad things.

That does not mean skills are unsafe by default. It means you should treat third-party skills the same way you treat third-party scripts.

Before you install a skill from somewhere random:

read the SKILL.md
read the bundled scripts
check what external services it touches
check whether it quietly widens allowed tool access
prefer trusted marketplaces and repos

This is one reason project-local skills are powerful. They are easy to audit because they live next to your code.

A realistic way to use Claude Code skills to make money

The monetization angle is not “sell a thousand generic skills in a marketplace.” Maybe that works for a few people, but it is not the obvious play.

The more realistic paths are:

build skills that speed up your own consulting or product development
package internal best practices for a team so onboarding gets faster
sell outcome-driven plugins or templates around a niche workflow
use skills to make your coding agent more reliable on a money-making product

The highest-value skill is usually not the fanciest one. It is the one that turns a messy repeated workflow into something dependable.

That might be a migration reviewer, a PR triage flow, a release checklist, a customer bug reproduction workflow, or a codebase-specific docs writer.

If the skill saves you thirty minutes a day and prevents one expensive mistake a month, it is already doing real work.

The best place to start

Build one project skill this week.

Not ten. One.

Pick the workflow you repeat most often and write the smallest skill that makes it more consistent. Test it for a few days. Notice where Claude misses the point. Tighten the description, split supporting files, and make the output format sharper.

That is how good Claude Code skills get built. Not from abstract prompt theory. From watching where your actual workflow leaks time and turning that leak into a repeatable tool.

If you do that well, you will stop thinking of skills as a neat feature. You will start thinking of them as part of your development operating system.