Claude Code skills: how to write, use and share them

A Claude Code skill is a folder with a SKILL.md file: a short description and the instructions behind it. Claude loads a skill when your request matches its description, or you run it yourself with /skill-name. Use skills for checklists, conventions and multi-step procedures you would otherwise paste into the chat again and again.

What is a Claude Code skill?#

A skill holds instructions that Claude Code reads only when they are needed. Anthropic suggests one when you keep pasting the same playbook into the chat, or when part of CLAUDE.md has grown into a procedure. CLAUDE.md loads in every session, while a skill's body loads only when used, so long reference material costs little until you need it.

Custom commands are now part of skills: .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy, and old command files keep working. Claude Code also ships bundled skills such as /code-review, /debug and /loop, which the disableBundledSkills setting turns off.

How is a skill built?#

A skill is a folder. Its name becomes the command, and SKILL.md is the only required file:

my-skill/
├── SKILL.md           # instructions and frontmatter (required)
├── reference.md       # detailed docs, read only when needed
├── examples.md        # sample output
└── scripts/
    └── helper.py      # a script Claude runs, not loads

SKILL.md starts with YAML frontmatter between two --- lines, then the instructions in Markdown. description matters most, since Claude uses it to decide when the skill applies. The common fields:

The listing cuts description and when_to_use together at 1,536 characters, so lead with the words people actually type. Keep SKILL.md under 500 lines and move long reference material into supporting files it names.

Where do skills live?#

Where you save a skill decides who can use it:

Claude Code also loads nested folders such as packages/web/.claude/skills/ when it works on files there. When names clash, enterprise wins over personal and personal over project; plugin skills carry the plugin's name as a prefix, so they never clash.

Three skills to try#

Reference skills add knowledge, such as conventions or a style guide. Task skills give the steps for one action, such as a deploy, and you usually run them yourself.

A reference skill for API conventions. With paths, Claude loads it on its own only under src/api/:

---
name: api-conventions
description: REST API conventions for this project. Use when writing or reviewing endpoints.
paths: "src/api/**"
---

When writing API endpoints:
- Use RESTful naming with plural nouns, such as /users and /orders
- Return errors in the shared format from src/api/errors.ts
- Validate the request body before any database call

A task skill that takes an argument. disable-model-invocation: true keeps Claude from running it on its own, and allowed-tools lets it read the issue without asking:

---
name: fix-issue
description: Fix a GitHub issue by number
argument-hint: "[issue-number]"
disable-model-invocation: true
allowed-tools: Bash(gh issue view *)
---

Fix GitHub issue $ARGUMENTS following our coding standards.

1. Read the issue with gh issue view
2. Find the code it describes
3. Implement the fix
4. Write or update tests
5. Summarize the change for the commit message

You run it with the issue number:

/fix-issue 123

$ARGUMENTS becomes everything typed after the name, and $0 and $1 pick out separate arguments.

A personal skill that reads your diff before Claude sees the instructions:

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

Claude Code first runs ` !git diff HEAD and puts the command's output in its place, so the instructions arrive with the real diff. Ask "what did I change?" and Claude loads the skill, or run /summarize-changes` yourself.

Who runs a skill: you or Claude?#

By default both you and Claude can run a skill. Two frontmatter fields change that:

With disable-model-invocation: true, the description stays out of Claude's context, so the skill costs nothing until you call it. /skill-name at the start of a message runs the skill; later in a message, it only lets Claude use it.

Skill, CLAUDE.md, hook or subagent?#

Each tool solves a different problem:

Anthropic's rules of thumb: if Claude gets a convention wrong twice, add it to CLAUDE.md. If you paste the same playbook a third time, make it a skill. If something must happen every time, write a hook: Claude may skip an instruction, but a hook runs on every matching event.

Do skills add to the cost?#

A little, and you can measure it. Every skill's name and description sits in the context, within a budget of 1% of the model's context window. The full body loads only when the skill runs, then stays in the conversation.

To check, open /context and look at the skills row, or run /skill-doctor (Claude Code v2.1.252 or later) to see what each skill costs and how often it gets used.

On an API key, skill text is ordinary input, billed per token at the model's price. The current price of the default model:

How do you share skills with a team?#

• Commit .claude/skills/ to the repository, and everyone who clones it gets the project skills.
• Package skills in a plugin, which runs them as /plugin-name:skill-name.
• Roll skills out to a whole organization through managed settings.

When a skill doesn't work#

• Claude doesn't load it: make sure the description holds the words you use, or run /skill-name directly.
• `/skill-name` works but Claude never picks it: the frontmatter YAML is probably malformed, and claude --debug shows the parse error.
• A skill with `paths` never activates: the patterns are relative to Claude's working directory.
• It triggers too often: make the description more specific, or set disable-model-invocation: true.
• Claude stops following it in a long session: put the key instructions at the top and run the skill again after compaction. A rule that must always hold belongs in a hook.

Claude Code skills through 5abeer#

5abeer is an independent service, not affiliated with Anthropic. Its API follows the Anthropic Messages format, so Claude Code works with it as it ships, and both routes cost less than the official price.

Skills are files on your machine, so they work the same on a 5abeer key; only the base URL and key change.

With an API key: create a key for Claude models, then set the base URL and key in Claude Code's settings:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.5abeer.ai",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_5ABEER_API_KEY",
    "ANTHROPIC_MODEL": "claude-sonnet-5.5"
  }
}

Skills synced from a claude.ai account load only when you sign in with that account, so on a key keep yours in ~/.claude/skills/ or .claude/skills/.

Every request is deducted from your balance by model and token count, and you control each key with a spend limit, an expiry date and an IP allow-list. The full setup is in Claude Code setup, and prices are on Claude API.

With a plan: the 5abeer AI app turns Claude Code on for your plan in one click, with no key and no files to edit. The plan runs with a 5-hour limit and a weekly limit, as in Subscription limits. Plans are for the supported apps, and to use the models from your own code you need an API key. See What each plan runs and the pricing page.

FAQ#

What is the difference between commands and skills?#

Custom commands were merged into skills, and a file in .claude/commands/ still creates the same /name. Skills add supporting files, control over who runs them and loading on their own, so write new ones as skills.

Do skills work with an API key?#

Yes. Personal and project skills are files on your machine, so they work the same on a plan or a key. Only skills synced from a claude.ai account need that account's sign-in.

Can a skill choose the model?#

Yes. The model field switches the model for the rest of the turn that runs the skill. On a key, each model bills at its own price: the default is claude-sonnet-5.5, and claude-opus-5.5 or claude-fable-5.1 suit the hardest problems. The full list with prices is on the models page.

Can I use a Claude Code skill outside Claude Code?#

Partly. Skills follow the open Agent Skills standard, but claude.ai uploads and the Skills API accept only six frontmatter fields: name, description, license, compatibility, metadata and allowed-tools. Claude Code extras such as ! command lines don't work there.

Should I move my CLAUDE.md into skills?#

Move procedures, not rules. Facts Claude needs in every session stay in CLAUDE.md, which Anthropic suggests keeping under 200 lines, and long procedures become skills.

Sources#

Checked on 1 November 2026.

• Claude Code docs: Extend Claude with skills
• Claude Code docs: Extend Claude Code

Get started#

To compare what Claude Code costs on a plan and on a key, read The cheapest way to use Claude Code, or set up Claude Code now.