Claude Code Skills: How to Add, Organize and Share Them

Introduction

Claude Code skills are folders of instructions that Claude loads only when a task needs them, and they are the cleanest way I know to teach an AI agent how your team works. A skill packages custom instructions and scripts for specialized tasks. A skill can hold a review checklist, a release procedure or a writing style. Claude reads it when it is relevant and ignores it the rest of the time.

This guide is for developers and tech leads who already use Claude Code and want to go from one personal skill to a library the whole team shares. We cover what agent skills are, how to add one, how Claude decides which skill to load and how to write descriptions that fire. Then we show the skills we use every day and how we manage around a hundred of them across projects, including the mistakes we still make.

Skills are one layer of context, so if you want the bigger picture, read our article on context engineering first or after this one.

What Are Claude Code Skills (and Agent Skills)?

A skill is a folder with a SKILL.md file, and an agent skill is simply a skill that an AI agent can load. The file has a short header that describes the skill and a body with instructions. According to the Claude Code documentation, Claude adds the skill to its toolkit and extends its capabilities, uses it when it is relevant, and you can also call it yourself with a slash command such as /skill-name.

The key idea is that a skill costs almost nothing until it is needed. Only the description sits in the context all the time. The body loads when the skill is used, so you can keep long reference material in a skill without paying for it on every request.

Claude Skills vs CLAUDE.md, Subagents, MCP and Plugins

The docs separate these tools by job, and the split is useful in practice.

• CLAUDE.md holds project-wide facts and is always in context, so keep it short.
• Skills hold knowledge and procedures that apply only to some tasks.
• Subagents are agents that take a delegated task and work in their own context.
• MCP connects Claude to external tools and data through an MCP server.
• Plugins distribute bundles of skills, agents and hooks.

If you used custom commands before, a skill is called the same way, with a slash, but Claude can also load it on its own. A simple rule works for us: if a rule applies to every task in a project, it goes into CLAUDE.md. If it applies to one kind of task, it becomes a skill.

Claude skills follow the Agent Skills format, which the docs describe as an open standard published at agentskills.io. That means a skill you write is a plain folder of markdown and scripts, not something locked into one product. It is also easy to review, version and share like any other code.

How to Give Claude Code a Skill

Adding a skill takes a few minutes. You create a folder, write one file and ask Claude something that matches. There is no build step and no registration in Claude Code itself.

Where Skills Live: Personal, Project and Plugin

The docs list several locations, and the choice decides who gets the skill.

• Personal: ~/.claude/skills/<name>/SKILL.md makes the skill available in all your projects on that machine.
• Project: .claude/skills/<name>/SKILL.md lives in the repo, so you can commit it and share it with the team.
• Plugin: a plugin can ship skills inside its own skills folder, which is how Claude Code plugins distribute them.
• Enterprise: an organization can provide skills through managed settings.

If the same name exists in several places, the docs say the enterprise skill wins over a personal one, and a personal one wins over a project one.

Write and Invoke Your First SKILL.md

The file must start with a header on the first line. The description is the important part, because it decides when the skill loads. Here is a small custom skill:

---
name: summarize-changes
description: Summarizes uncommitted changes in plain language. Use when the user asks what changed, wants a commit summary, or says "what did I touch".
---

Run git diff, group the changes by purpose, and write a summary in
three bullets. Mention any file that changed without a test.

The name is optional and defaults to the folder name. The docs mark the description as recommended, and they cap the description plus the optional whentouse field at 1,536 characters in the skill listing.

After you save the file, ask Claude something that matches the description, for example "what changed since my last commit?". Claude should load the skill by itself. You can also type the slash command, here /summarize-changes, when you want to be sure.

The docs also describe fields such as disable-model-invocation and user-invocable, which control whether Claude can load a skill on its own or only when you call it. We use that for skills with side effects, where we want a person to decide.

Add Scripts, Reference Files and Other Resources

A skill can contain more than one file. The docs give the examples reference.md for long reference material and scripts/helper.py for a script the skill can run, and they provide a variable that points to the skill folder. Our local-loop skill keeps its plan and handoff templates in a reference file instead of the main body.

Scripts are where skills become reliable. Anything that must happen the same way every time, such as validating output or checking a naming rule, is better as a script than as a sentence the model may interpret differently. A Python helper works as well as a shell or Node script, so use whatever your team already maintains.

Do Skills Work in Claude Code? How Claude Decides What to Load

Yes, they do, and the mechanism is simple. Claude, as an agent, sees the list of skill names and descriptions, so the match is a bit like a search over short descriptions. When your request matches a description, it loads the body of that skill. Once a skill is used, its body stays in the conversation for later turns.

The docs add a detail that matters for long sessions. After auto-compaction, skills that were already invoked are attached again within a combined budget of 25,000 tokens. So a skill can survive compaction, but a very long skill will compete for that budget.

Why the Description Is the Trigger

The description is the only part of a skill that Claude sees when it decides whether to load it. If the description is vague, the skill never fires. If it is too broad, the skill fires when it should not.

In our skills repo this is a written rule: the description is the trigger, not a summary. It should name the situations, the artifacts and the phrases people type, and it should say what the skill does not cover.

Our best descriptions read like a list of phrases a person might say. The grilling skill says to use it when the user wants their thinking stress-tested or says "grill me", "poke holes in this" or "am I missing anything". Our delegate skill lists phrases in two languages, such as "do this in the background", because that is how we talk to it.

The commit skill taught us a second lesson. Its description once blocked agents from using it, so we rewrote it to say that the skill must load before the first commit of any run, not only when the user says the word commit. If a skill is not firing, change the description before you touch the body.

What Makes Claude Good at Coding (and What Skills Add)

People often ask what makes Claude so good at coding. We cannot explain the internals of a model, and we would not trust anyone who claims to. What we can say from daily work is that the model is only half of the result.

The other half is what the model knows about your project: your conventions, your review rules, your release steps and your vocabulary. A strong model without that knowledge writes good generic code. With it, the code matches how your team builds software.

Skills are the cheapest way to supply that knowledge. They are plain files, you can review them in a pull request, and Claude only reads them when they matter. That makes them a form of context management, the same discipline we describe in our context engineering article.

The Top Skills for Claude Code

There is no single list of the best skills, because the useful ones depend on your work. We group them into the ones that ship with the tool, the ones from Anthropic, and the ones we wrote ourselves.

Built-In Tools and Official Skills on GitHub

The docs list bundled skills including /run, /verify, /debug, /code-review, /doctor, /claude-api, /batch and /loop. The /code-review skill reviews your current changes, and /loop runs a prompt on a schedule. They are a good starting point because they show how a well-built skill behaves.

Anthropic also publishes example skills in a public GitHub repository. The documentation describes categories such as creative and design work, development tasks like web app testing, enterprise workflows and document skills for Word, PDF, PowerPoint and Excel files. Read a few of them before you write your own, because they show how to structure instructions and supporting files.

The /claude-api skill, for example, helps with work on the Claude API. The docs also describe a skill-creator plugin that can generate evaluations and A/B comparisons for your skills. You install it with the plugin command shown in the documentation.

Code Review and Other Skills We Use Every Day

These are the skills from our own repo that we would miss the most.

• delegate hands a task to a background agent, a second agent that works in its own git worktree, so the main chat stays free. The briefs are deliberately short, because the delegate cannot ask questions.
• local-loop plans a task and then works through it as small verified steps. It makes one commit per step and a checkpoint every five steps, and it keeps its state on disk, so if Claude stops mid-task a new session can continue. It suits long work such as a refactoring or a migration.
• grilling interviews you about a plan, one question at a time, each with a recommended answer.
• code-reviewer is our code review skill. It treats the skills linked in the project as the review rubric, checks that they are linked before it reads any code, and cites the skill and the rule behind every blocking finding.
• commit writes short commit messages and stages files by name.

None of these is clever. Each one removes a decision we used to make slightly differently every time.

Custom Skills for Backend and Infrastructure

The code review skill gets its rules from other custom skills, and the backend and infrastructure skills show best how we encode the way we build. We did not write one big backend skill. We split it by concern into four.

• backend-architecture is the baseline: where logic lives when you add a feature, how to layer transport, services and persistence, module boundaries, and what to do with caches and locks when several replicas run.
• backend-rest covers controllers, DTOs, validation and error handling.
• backend-graphql covers resolvers, N+1 prevention and query complexity limits, which are performance topics.
• backend-data covers entities, migrations and database access.

Each description says when to use the skill and points to its neighbors by name, for example that the layering baseline lives in backend-architecture. All four are marked as not user-invocable, which is one of the header fields in the docs. Nobody types a command for them. Claude loads the right one when we work on that kind of code.

Infrastructure has a different shape. Our AWS resource health skill takes a misbehaving resource, such as a Lambda that errors or an RDS instance that runs slow, reads its CloudWatch metrics and logs, and produces a remediation plan ranked by severity. We left this one user-invocable, because a person decides when to start a diagnosis. The split between skills Claude loads on its own and skills you call yourself is worth planning from the start.

Managing Skills Across a Team

One skill is easy to manage. A hundred are not, unless you decide on a structure early. Our skills live in a single private Git repository of markdown and two small scripts, and every project links only what it needs.

Organize Skills by Role

We group skills by role, meaning who needs them. A baseline set is for everyone and covers core coding principles, tech stack choices, the development process and security. Each project also gets one platform role, such as Next.js, Vue, mobile or backend, and the right one is detected from the project.

Other groups are opt-in, for example marketing or research. A backend service never loads frontend conventions, which keeps the list of skill descriptions short and the matching reliable.

Share Skills Across Projects With Symlinks

A small script links skills into a project. Running it in a project folder links the baseline and the detected platform into the project's .claude/skills folder. A flag links skills globally into your home directory, and another links only the roles you name, for example only marketing for a content project.

Because the links are symlinks, there is one copy of every skill. When we check out a new version of the repo, every linked skill in every project updates at once. The projects themselves ignore the .claude/skills folder, so no skill is ever committed twice.

There is one trap. Creating a skill folder does not make it callable. You still have to link it, and without the link you get an unknown skill error.

Release Skills Like Software

A change to a shared skill reaches every project that links it, so we treat a release as a broadcast. Changes land on the main branch through a pull request, then we tag a version, and teammates check out that tag.

We also prefer editing an existing skill over adding a near-duplicate. Overlapping descriptions make automatic loading unreliable, because Claude has two plausible matches and may pick the wrong one.

Best Practices for Writing Custom Skills

Most of what makes a skill good is restraint. These practices come from rewriting our own skills many times.

Design Rules and Guidelines, Not Essays

A skill body should state rules, show the right pattern in a short example and name the anti-pattern. It should not explain the history of the decision. Long skills drown their own rules, and one of ours is long enough that we have admitted it in the skill itself.

The same applies to briefs and prompts that mention a skill. Anything a skill already says is better loaded than restated, because the skill is the maintained copy and a paraphrase goes stale silently.

One Job per Skill, Edit Instead of Duplicating

Give each skill one job and a description that says what it does and what it rejects. When a new need appears, first ask whether an existing skill should grow. A new skill is only worth it when the trigger is clearly different.

Skills also do not replace plan mode, which asks Claude to plan before it edits. A skill makes sure that plan follows your conventions.

Skills can also point to each other by name instead of copying content. Our content refresh skill, for example, uses the data skills and the writing skill rather than repeating their rules.

Testing Skills Before You Trust Them

Treat a skill like code. Try it on a real task in Claude Code, read what Claude did, and tighten the description or the rules where it drifted. The skill-creator plugin from the docs can run evaluations and compare versions, which helps once a skill is used by many people.

Keep secrets out of skills. Document only the name of the environment variable, never the value, because skills end up in repositories and in review.

Caveats: Skills Are Not Guaranteed to Run

Skills help a lot in Claude Code, but they do not make an agent obedient. In our experience the main failure is simple: the agent forgets to use the right skill, and an agent that delegates to other agents forgets it most. This happens most with orchestrators that hand work to other agents, because they have a lot to remember and a skill is just one more thing.

We saw this when a background agent delivered a pull request with dozens of added comment lines, even though we have a skill that says not to add them. The skill existed, the agent had access to it, and it still did not apply it. Nothing was wrong with the rules, and nobody can blame the model for that. It simply did not load the skill at that moment.

Two things help. First, remind your orchestrators routinely which skills to use, for example in the task brief or in CLAUDE.md. Second, add deterministic checks, such as a script that counts comment lines before a pull request goes out.

Scripts are not perfect either, because they can fail or be skipped. In our estimate, a check like that misses roughly one case in twenty, which is still far better than no check. Plan for the miss: review the result instead of assuming the skill ran.

Conclusion

I started using skills to stop repeating myself, and they turned into the way our whole team shares how we work. The format is simple enough to learn in an afternoon, and the hard part is the discipline around it.

The main takeaways:

• Claude Code skills are folders with a SKILL.md file that load only when a task needs them, so they cost almost nothing until used.
• The description is the trigger, so write it as the phrases people say and fix it first when a skill does not fire.
• Put project-wide facts in CLAUDE.md and task-specific procedures in skills, and move anything that must be exact into a script.
• For a team, group skills by role, link them with symlinks from one repo and release changes like software.
• Skills are not guaranteed to run, so remind your agents which ones to use and check the result.

As a next step, pick the one instruction you repeat most often and turn it into a skill today. Then ask Claude for a task that should trigger it and see whether it fires.

Frequently Asked Questions

What is a Claude Code skill, and how does it differ from CLAUDE.md?

How does Claude Code decide when to load a skill automatically?

Why isn't my custom skill triggering automatically?

Can Claude Code skills include executable scripts and reference files?

How can engineering teams share and manage skills across multiple projects?