Claude Code Skills: How to Create Them for Your Team

Claude Code Skills: How to Create Them for Your Team

A Claude Code skill is a folder with a SKILL.md file that holds a name, a description and written instructions, plus optional supporting files. To create one for your team, add a folder inside .claude/skills in your repository, write a clear description of when the skill should be used, and keep everything in Git. Claude then loads the skill on its own when a request matches the description.

Key takeaways

• A skill is a folder with a SKILL.md file: a header with a name and description, followed by instructions in Markdown.
• The description is the most important part, because it is what helps Claude decide when to load the skill.
• Project skills live in .claude/skills and travel with the repository, which makes them the natural way to share routines with a team.
• Start with repetitive routines that have a clear definition of "done", and treat the skill like code: review, version control and permission limits.
• Always check the official documentation, because the format and features of Claude Code change over time.

What is a skill in Claude Code?

According to the official Claude Code documentation, a skill is a package of knowledge and procedure that extends what Claude can do on a specific task. Instead of pasting the same paragraph of instructions into the chat every week, you write it once, in a file, and Claude uses it when it is relevant.

The technical point that matters for a decision maker is on-demand loading. At the start, Claude sees only the name and description of each skill. The body of the instructions, the templates and the scripts enter the context only when the skill is triggered. That lets you install many skills without filling every conversation with text that has nothing to do with the task. It is the same context-saving logic Anthropic discusses in its material on context engineering for AI agents.

It helps to separate skills from other features that look similar:

• CLAUDE.md: instructions that are always loaded. Use it for general project rules, such as code conventions and test commands.
• Slash commands: shortcuts that a person triggers explicitly. A skill, by contrast, is chosen by Claude itself based on the description.
• Subagents: assistants with their own context and permissions, useful for isolating a task.
• MCP (Model Context Protocol): a connection between Claude and external systems and tools. The skill teaches the procedure; MCP provides the access.

In this article, what comes from the official documentation is described as such. The suggested routines and the way to organize them come from our implementation experience and are working hypotheses, not product rules.

Where do skills live and how does Claude find them?

There are generally three places a skill can live:

• Personal: in the .claude/skills folder inside your user directory. It applies only to you, in any project.
• Project: in the .claude/skills folder inside the repository. Anyone who clones the project gets the skills along with it.
• Plugins: packages that can bundle skills and other features for wider distribution.

For a team, the project option is usually the best starting point. The skill goes through the same pull request flow as the rest of the code: someone proposes it, someone else reviews it, and the history is recorded. That solves the classic problem of knowledge that exists only in one person's head or in a forgotten wiki page.

Each skill has its own subfolder. The folder name should describe the routine, in lowercase with hyphens, for example pr-review or release-notes. Inside it, the SKILL.md file is required and everything else is optional: templates, examples, checklists and scripts.

How to create a Claude Code skill step by step

This is the sequence we suggest for a team's first skill:

• Step 1, pick a routine: a task that repeats, has a clear input and output, and today depends on someone remembering the steps. Avoid starting with anything that touches sensitive data or production.
• Step 2, write the procedure as if for a new hire: what to look at first, which criteria to apply, what to do when information is missing and what never to do.
• Step 3, create the folder: inside .claude/skills, a subfolder named after the routine.
• Step 4, create the SKILL.md: at the top, a YAML header with the name and description fields. Below it, the instructions in Markdown.
• Step 5, move long material out: document templates, examples and references go into files next to it, and SKILL.md only says when to consult them.
• Step 6, restrict the tools: if the official documentation for your version offers the allowed-tools field, use it to limit what the skill can do. A review skill, for example, only needs to read files.
• Step 7, test with real requests: ask for the task in different ways and watch whether the skill is triggered and whether the result follows the procedure.
• Step 8, review and publish: open a pull request, ask another person to review it and only then merge.

The official documentation sets limits on size and format for the name and description. Check the Claude Code skills page in the official docs before you standardize the format for your team, because these details can change.

How do you write a good description and good instructions?

The description decides whether the skill gets used. Claude compares the person's request with the description of each available skill. A vague description means the skill is never triggered, or is triggered at the wrong moment.

Compare two examples. A weak description would be: "Helps with PRs". A better one would be: "Reviews a pull request against the team's review checklist. Use when the person asks for a code review, a PR review or an analysis of a diff." The second says what the skill does and when to use it, with the words the team actually uses day to day.

For the instructions in the body of the file, a lean checklist helps:

• Start with the goal and the expected result, in one or two sentences.
• List the steps in the order they should happen.
• State the output format: bullet points, a table of findings, text to paste into a ticket.
• Define what to do when in doubt, for example ask before assuming.
• Write the limits explicitly: what the skill must not change, delete or send.
• Use short examples of good input and output instead of long abstract explanations.
• Keep SKILL.md short and move reference material into separate files.

The principle is the same as in designing tools for agents: a few clear, unambiguous instructions work better than a long manual. Anthropic discusses this in its guidance on writing effective tools for agents.

Which team routines make good skills?

Good candidates share three traits: they happen often, they follow a recognizable procedure and they produce a result someone can check. A few ideas, all offered as suggestions for how to organize the work:

• Pull request review: applies the team checklist, flags risks and suggests missing tests.
• Release notes: turns a list of commits or completed tasks into text that non-technical readers can follow.
• Bug triage: reads a report, asks for missing details and classifies it by area and urgency using defined criteria.
• Incident runbook: guides the first diagnosis in read-only mode, following the team's runbook.
• Repository onboarding: explains how to set up the environment, run tests and where the conventions live.
• Integration documentation: generates the draft of a standardized page for each new connector or endpoint.

To decide whether something should be a skill or another feature, use this guide:

• If the rule applies to all work in the project, put it in CLAUDE.md.
• If a person wants to trigger an action explicitly and predictably, use a slash command.
• If the task has its own procedure and should be triggered when the context calls for it, use a skill.
• If the task needs access to an external system, combine the skill with an MCP connection.
• If the task needs isolated context or different permissions, consider a subagent.

Illustrative scenario: a small software team ships a release every week, and every Friday someone spends time putting together the update text for the sales team. The team creates a release-notes skill. The description says it is for preparing release notes from the week's changes. The instructions ask Claude to group changes by area, use plain language, highlight changes that affect customers and flag what is uncertain instead of guessing. A text template sits in a file next to it. The responsible person still reviews and publishes; the skill only delivers the first draft. After a few weeks, the team compares the draft with the final text and adjusts the instructions where corrections were most frequent.

If the routine involves customer service, remember that Claude Code is a tool for development and internal operations. Customer service flows on channels like WhatsApp need a different design, with human handoff and a record of decisions. See, for example, the guide on how to integrate AI into your company's WhatsApp.

How do you keep skills secure and under control?

A skill is instruction, and sometimes executable code. It deserves the same care as any other item in the repository.

• Mandatory review: every new or changed skill goes through a pull request. Scripts inside a skill are read carefully, line by line.
• Least privilege: limit the tools and avoid granting write or network access when the task does not need it.
• No secrets: never put keys, passwords or tokens in SKILL.md or in the supporting files.
• No personal data: examples should be fictional. Real customer data in a repository creates a data protection problem (under Brazil's LGPD, for instance) that nobody needs. For official guidance, consult the data protection authority in your jurisdiction.
• Watch for untrusted content: if the skill reads web pages, emails or tickets, that text can contain malicious instructions. The OWASP recommendations on prompt injection prevention are a good starting point.
• Human approval for irreversible actions: sending messages, changing production and deleting data should require confirmation. A template for this is in the AI agent approval policy.

Our method applies directly. First we map the routine as it is done today and note the starting point. Then we limit data, tools and actions. Next we pilot a single skill, logging what was asked and what was corrected, with a success criterion agreed before the start. Finally we hand over: the team becomes the owner of the file, and the decision is to expand, adjust or stop. To define the criterion, the article on how to measure an AI automation pilot offers metrics and decision gates.

Frequently asked questions

What is the difference between a skill and CLAUDE.md? CLAUDE.md is always loaded and holds general project rules. A skill is loaded on demand, when the description matches the request, and holds a specific procedure. If an instruction only makes sense for one task, it is probably a skill.

Do I need to know how to code to create a skill? For the simplest case, no. A skill can be just a SKILL.md with Markdown text and a header with a name and description. Programming only comes in if you want to include supporting scripts, and in that case review by someone technical is essential.

How do I share a skill with the whole team? Put the folder in .claude/skills inside the project repository and commit it. Anyone who updates the repository receives the skill. For distribution across several projects, the official documentation describes the use of plugins, so check what your version supports.

How do I know whether the skill is working well? Test with real, varied requests and watch whether it is triggered and whether the output follows the procedure. In a pilot, record how often the result needed human correction and why, and adjust the description and instructions based on that. If the routine does not improve after a few cycles, that is a legitimate signal to stop or redesign it.

Sources

• Anthropic: Claude Code, documentação de skills
• Anthropic: Effective context engineering for AI agents
• Anthropic: Writing effective tools for agents
• OWASP: prompt injection prevention