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

> What a Claude Code skill is, how to write SKILL.md, where skills live, who runs them and how to share them, with setup on an API key.

Updated: 2026-11-01

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:

```text
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:

| Field | What it does |
| --- | --- |
| `name` | The command name in the `/` menu. Defaults to the folder name. |
| `description` | What the skill does and when to use it. Put the main use case first. |
| `argument-hint` | An autocomplete hint, such as `[issue-number]`. |
| `disable-model-invocation` | `true` means only you can run the skill. |
| `allowed-tools` | Tools Claude can use without asking during the turn that runs the skill. The grant ends with your next message. |
| `paths` | Glob patterns. Claude loads the skill on its own only for matching files. |
| `model` and `effort` | The model and effort level for the rest of the current turn. |

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:

| Location | Path | Who gets it |
| --- | --- | --- |
| Personal | `~/.claude/skills/skill-name/SKILL.md` | You, in all your projects |
| Project | `.claude/skills/skill-name/SKILL.md` | Everyone in the repository, once committed |
| Plugin | `skills/skill-name/SKILL.md` inside the plugin | Wherever the plugin is on, as `/plugin-name:skill-name` |
| Enterprise | Managed settings | Everyone in your organization |

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/`:

```text
---
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:

```text
---
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:

```text
/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:

```text
---
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:

| Frontmatter | You run it | Claude runs it | Good for |
| --- | --- | --- | --- |
| Neither field | Yes | Yes | Most skills |
| `disable-model-invocation: true` | Yes | No | Actions with side effects, such as `/commit` or `/deploy` |
| `user-invocable: false` | No | Yes | Background knowledge you never call by hand |

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:

| Feature | When it loads | Use it for |
| --- | --- | --- |
| `CLAUDE.md` | Every session | Project conventions and rules that always apply |
| Skill | The description always, the body when used | Reference material and repeatable tasks |
| Hook | Outside the model, on an event | Steps that must run every time, such as ESLint after every edit |
| Subagent | In its own context, returning a summary | Side tasks that would fill the main conversation |

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:

Claude Sonnet 5.5 (`claude-sonnet-5.5`) per 1M tokens: input $0.60 (official $2), output $3 (official $10). Official price checked October 19, 2026.

## 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.

> Workspace trust does not gate `allowed-tools`: a project skill's grants apply even in a folder you never trusted. Review `allowed-tools` in any repository you clone, and keep your own grants narrow, such as `Bash(git status *)` rather than all of `Bash`.

## 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:

| Format | Base URL | Key header |
| --- | --- | --- |
| OpenAI | `https://api.5abeer.ai/v1` | `Authorization: Bearer <KEY>` |
| Anthropic | `https://api.5abeer.ai` | `x-api-key: <KEY>` |
| Gemini | `https://api.5abeer.ai/v1beta` | `x-goog-api-key: <KEY>` |

`~/.claude/settings.json`

```json
{
  "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](https://5abeer.ai/en/docs/apps/claude-code.md), and prices are on [Claude API](https://5abeer.ai/en/api/claude).

**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](https://5abeer.ai/en/docs/subscriptions/limits.md). 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](https://5abeer.ai/en/docs/subscriptions/plan-apps.md#claude-code) and the [pricing page](https://5abeer.ai/en/pricing).

## 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`](https://5abeer.ai/en/models/claude-sonnet-5.5), and [`claude-opus-5.5`](https://5abeer.ai/en/models/claude-opus-5.5) or [`claude-fable-5.1`](https://5abeer.ai/en/models/claude-fable-5.1) suit the hardest problems. The full list with prices is on the [models page](https://5abeer.ai/en/models).

### 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](https://code.claude.com/docs/en/skills)
- [Claude Code docs: Extend Claude Code](https://code.claude.com/docs/en/features-overview)

## Get started

To compare what Claude Code costs on a plan and on a key, read [The cheapest way to use Claude Code](https://5abeer.ai/en/guides/claude-code-cheapest-way), or set up Claude Code now.