---
title: "Claude Code skills: what they are, how to write one | Bombos"
description: "A Claude Code skill is a SKILL.md file with instructions that Claude loads when the task fits its description, or that you run yourself with /skill-name."
image: "https://bombos.ai/assets/og-en-v2.png"
---

# What are Claude Code skills and how do you write one?

Short answer

A skill is a folder with a SKILL.md file: a short YAML header with a name and description, then instructions in Markdown. Claude sees only the name and description in every session and reads the full file when a task fits, or when you type /skill-name. Personal skills live in ~/.claude/skills/, project skills in .claude/skills/ in the repo, and plugins can ship their own.

*Piet Baudoin · published November 17, 2026 · November 17, 2026*

## What a skill looks like

A skill is a directory with one required file, `SKILL.md`. The file starts with YAML frontmatter between `---` lines and continues with plain Markdown instructions. Every field is optional, but `description` is the one that matters: Claude reads it to decide when the skill applies. `name` becomes the command and defaults to the directory name.

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

That example, from the official docs, also shows one of the extras Claude Code adds on top of the open standard: a line like `` !`git diff HEAD` `` runs before the skill is sent, and its output replaces the placeholder. Other useful fields:

| Field | What it does |
| --- | --- |
| `disable-model-invocation: true` | Only you can start the skill, with `/name`. Its description is not in context. |
| `user-invocable: false` | Hidden from the `/` menu; only Claude uses it, for background knowledge. |
| `allowed-tools` | Tools Claude may use without a permission prompt during the turn that invokes the skill. |
| `context: fork` | Runs the skill as a subagent with its own context, with `agent` choosing the type. |
| `arguments` / `$ARGUMENTS` | Pass input in, as in `/fix-issue 123`. |
| `model`, `effort`, `paths` | Per-skill model and effort, and activation based on file paths. |

A skill can carry more files next to `SKILL.md`, such as `reference.md`, `examples.md` or a `scripts/` folder. Claude opens the extra files only when it needs them, and scripts are executed rather than loaded into context.

## Where skills live

| Level | Path | Who gets it |
| --- | --- | --- |
| Enterprise | `.claude/skills/<name>/SKILL.md` in the managed settings directory | Everyone on managed machines |
| Personal | `~/.claude/skills/<name>/SKILL.md` | You, in all your projects |
| Project | `.claude/skills/<name>/SKILL.md` | Everyone who works in the repo, once committed |
| Plugin | `<plugin>/skills/<name>/SKILL.md` | Anyone with the plugin enabled, as `/plugin-name:skill-name` |

When two skills share a name, enterprise beats personal and personal beats project. Plugin skills are namespaced, so they never collide.

## How Claude picks a skill

For a skill Claude may start on its own, it sees only the name and description in every session. The full body is read when the task calls for it, or when you type `/skill-name` at the start of a message. That is why the description should say both what the skill does and when to use it, with the main trigger first: the description plus the optional `when_to_use` field is truncated at 1,536 characters in the listing.

Once a skill is invoked, its content stays in context for the rest of the session, so the docs advise keeping `SKILL.md` under 500 lines and pushing long reference material into separate files.

## Skills vs CLAUDE.md vs slash commands vs subagents

1.  **CLAUDE.md** loads at the start of every session. Use it for what applies to almost every task. The costs guide recommends keeping it under 200 lines and moving workflow-specific instructions, such as how to do a PR review or a database migration, into skills.
2.  **Skills** hold procedures and team knowledge that matter only for some tasks: how your team cuts a release, what the incident runbook says. They cost almost nothing until used.
3.  **Slash commands** are now skills. Custom commands were merged into skills; existing `.claude/commands/` files still work, and `/deploy` still runs whether it lives there or in `.claude/skills/deploy/`.
4.  **Subagents** are separate workers with their own context window, system prompt and tool limits, defined in `.claude/agents/`. A skill runs in your conversation unless you set `context: fork`. A subagent can also preload skills through its `skills` field. See [what subagents are](https://bombos.ai/en/questions/claude-code/claude-code-subagents/).

## The misunderstanding: “a skill is a rule”

A skill Claude picks up itself is still an instruction the model reads and weighs. The Claude Code best practices put it in the non-deterministic column, next to your prompt and CLAUDE.md. What is enforced is which skills only you can start: with `disable-model-invocation: true`, a release skill will not run because Claude thought it was a good idea. If something must always or never happen, use a [hook](https://bombos.ai/en/questions/claude-code/claude-code-hooks/) or a deny rule, not a skill.

## Sharing skills with a team

1.  Put the skill in `.claude/skills/` in the repo and commit it. Everyone who pulls gets it.
2.  For skills that span several repos, bundle them in a plugin and install it from a marketplace. See [how Claude Code plugins work](https://bombos.ai/en/questions/claude-code/claude-code-plugins-memory/).
3.  For company-wide skills, IT places them in the managed settings directory.
4.  Admins can switch skills on, off or to name-only with the `skillOverrides` setting, without editing the files.

What a skill does not do is learn. It holds what someone wrote into it, and it applies only to Claude Code and other tools that read the Agent Skills format. Claude Code can separately save a colleague’s correction in auto memory, but that memory stays on the colleague’s machine: it is not shared with teammates or other AI tools unless someone writes it into the skill. More on that gap in [shared memory across coding agents](https://bombos.ai/en/knowledge-base/shared-memory-across-coding-agents/).

## Where Bombos fits

Skills are a good home for procedures someone has already written down. Bombos is a plugin that gives Claude Code and the team’s other AI tools, such as ChatGPT, Copilot, Codex and Cursor, one shared memory: team knowledge, rules learned from corrections, and what already sits in mail, documents and repos, each traceable to its source. One developer can try it on their own agents first.

## Related questions

What happened to custom slash commands?

They were merged into skills. Files in .claude/commands/ keep working, and a skill with the same name takes precedence. Moving deploy.md to .claude/skills/deploy/SKILL.md keeps /deploy and lets you add supporting files.

How do I stop Claude from running a skill on its own?

Add disable-model-invocation: true to the frontmatter. The skill then only runs when you type its name, which is what you want for anything with side effects such as a deploy or a release.

How do I see which skills are loaded?

Type /skills. The / menu also lists them by name. Edits to an existing skill take effect without restarting Claude Code.

Do skills work outside Claude Code?

Skills follow the Agent Skills open standard, and you can upload them to claude.ai or use them through the Skills API. Outside Claude Code only a few frontmatter fields are allowed: name, description, license, compatibility, metadata and allowed-tools.

How long can a skill be?

The docs advise keeping SKILL.md under 500 lines and moving reference material into separate files that Claude opens only when needed. The description plus when\_to\_use is cut off at 1,536 characters in the skill listing, so put the main use case first.

## Sources

1.  [Claude Code docs: Extend Claude with skills](https://code.claude.com/docs/en/skills)
2.  [Claude Code docs: Best practices](https://code.claude.com/docs/en/best-practices)
3.  [Claude Code docs: Manage costs effectively](https://code.claude.com/docs/en/costs)
4.  [Claude Code docs: Create custom subagents](https://code.claude.com/docs/en/sub-agents)

## What does your AI forget?

1.  01You tell us which AI you use and where it keeps starting over.
2.  02We show what a shared memory changes there, on your own examples.
3.  03You keep the plan, with or without Bombos.

![Piet Baudoin](https://bombos.ai/assets/team/piet-klein.jpg)

**Piet Baudoin**You talk to Piet, from the Bombos teamDutch team from Utrecht and Nijmegen · data in Europe

## More questions about Claude Code

-   [What are Claude Code hooks and how do I set them up?](https://bombos.ai/en/questions/claude-code/claude-code-hooks/)
-   [How do I use Claude Code in VS Code and JetBrains?](https://bombos.ai/en/questions/claude-code/claude-code-in-vs-code-and-jetbrains/)
-   [What is Claude Code Remote Control and how do I use it?](https://bombos.ai/en/questions/claude-code/claude-code-remote-control/)
-   [What is the Claude Code SDK, now the Claude Agent SDK?](https://bombos.ai/en/questions/claude-code/claude-code-sdk/)
-   [What are agent teams in Claude Code and how do you turn them on?](https://bombos.ai/en/questions/claude-code/claude-code-agent-teams/)
-   [What are subagents in Claude Code and when should you use them?](https://bombos.ai/en/questions/claude-code/claude-code-subagents/)
-   [How much does Claude Code cost per developer per month in tokens?](https://bombos.ai/en/questions/claude-code/claude-code-token-cost-per-developer/)
-   [How do Claude Code usage limits work, and how do I check my usage?](https://bombos.ai/en/questions/claude-code/claude-code-usage-limits/)

[All questions about Claude Code →](https://bombos.ai/en/questions/claude-code/)


---

```json
{"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://bombos.ai/#organization","name":"Bombos","url":"https://bombos.ai/","logo":"https://bombos.ai/assets/bombos-bee.png","description":"Bombos is the memory layer under every AI your team uses. One shared memory for Claude, ChatGPT, Copilot, Cursor and your own agents, that learns how you work.","sameAs":["https://www.linkedin.com/company/bombos-ai","https://www.youtube.com/@truebombos","https://www.instagram.com/truebombos/","https://bsky.app/profile/bombostrue.bsky.social","https://www.threads.com/@truebombos","https://mastodon.social/@Bombos","https://www.tiktok.com/@truebombos","https://t.me/truebombos","https://www.pinterest.com/truebombos/","https://github.com/bombos-ai","https://linktr.ee/bombos.ai","https://bombosai.substack.com","https://hashnode.com/@bombosai","https://hackernoon.com/u/bombos","https://dev.to/bombos"],"email":"info@bombos.ai","areaServed":["NL","Europe"],"knowsLanguage":["nl","en"],"contactPoint":{"@type":"ContactPoint","email":"info@bombos.ai","contactType":"sales","url":"https://bombos.ai/en/contact/","availableLanguage":["nl","en"]}},{"@type":"WebSite","@id":"https://bombos.ai/#website","name":"Bombos","url":"https://bombos.ai/","inLanguage":["nl-NL","en"],"publisher":{"@id":"https://bombos.ai/#organization"}}]}

{"@context":"https://schema.org","@type":"Article","headline":"What are Claude Code skills and how do you write one?","description":"A Claude Code skill is a SKILL.md file with instructions that Claude loads when the task fits its description, or that you run yourself with /skill-name.","abstract":"A skill is a folder with a SKILL.md file: a short YAML header with a name and description, then instructions in Markdown. Claude sees only the name and description in every session and reads the full file when a task fits, or when you type /skill-name. Personal skills live in ~/.claude/skills/, project skills in .claude/skills/ in the repo, and plugins can ship their own.","datePublished":"2026-11-17T00:00:00.000Z","dateModified":"2026-11-17T00:00:00.000Z","author":{"@type":"Person","name":"Piet Baudoin"},"publisher":{"@type":"Organization","@id":"https://bombos.ai/#organization","name":"Bombos","logo":{"@type":"ImageObject","url":"https://bombos.ai/assets/bombos-bee.png"}},"image":"https://bombos.ai/assets/og-en-v2.png","mainEntityOfPage":"https://bombos.ai/en/questions/claude-code/claude-code-skills/","inLanguage":"en-US","isPartOf":{"@type":"CollectionPage","name":"Claude Code","url":"https://bombos.ai/en/questions/claude-code/"},"citation":[{"@type":"CreativeWork","name":"Claude Code docs: Extend Claude with skills","url":"https://code.claude.com/docs/en/skills"},{"@type":"CreativeWork","name":"Claude Code docs: Best practices","url":"https://code.claude.com/docs/en/best-practices"},{"@type":"CreativeWork","name":"Claude Code docs: Manage costs effectively","url":"https://code.claude.com/docs/en/costs"},{"@type":"CreativeWork","name":"Claude Code docs: Create custom subagents","url":"https://code.claude.com/docs/en/sub-agents"}]}

{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Bombos","item":"https://bombos.ai/en/"},{"@type":"ListItem","position":2,"name":"Questions","item":"https://bombos.ai/en/questions/"},{"@type":"ListItem","position":3,"name":"Claude Code","item":"https://bombos.ai/en/questions/claude-code/"},{"@type":"ListItem","position":4,"name":"What are Claude Code skills and how do you write one?","item":"https://bombos.ai/en/questions/claude-code/claude-code-skills/"}]}

{"@context":"https://schema.org","@type":"FAQPage","mainEntity":[{"@type":"Question","name":"What happened to custom slash commands?","acceptedAnswer":{"@type":"Answer","text":"They were merged into skills. Files in .claude/commands/ keep working, and a skill with the same name takes precedence. Moving deploy.md to .claude/skills/deploy/SKILL.md keeps /deploy and lets you add supporting files."}},{"@type":"Question","name":"How do I stop Claude from running a skill on its own?","acceptedAnswer":{"@type":"Answer","text":"Add disable-model-invocation: true to the frontmatter. The skill then only runs when you type its name, which is what you want for anything with side effects such as a deploy or a release."}},{"@type":"Question","name":"How do I see which skills are loaded?","acceptedAnswer":{"@type":"Answer","text":"Type /skills. The / menu also lists them by name. Edits to an existing skill take effect without restarting Claude Code."}},{"@type":"Question","name":"Do skills work outside Claude Code?","acceptedAnswer":{"@type":"Answer","text":"Skills follow the Agent Skills open standard, and you can upload them to claude.ai or use them through the Skills API. Outside Claude Code only a few frontmatter fields are allowed: name, description, license, compatibility, metadata and allowed-tools."}},{"@type":"Question","name":"How long can a skill be?","acceptedAnswer":{"@type":"Answer","text":"The docs advise keeping SKILL.md under 500 lines and moving reference material into separate files that Claude opens only when needed. The description plus when_to_use is cut off at 1,536 characters in the skill listing, so put the main use case first."}}]}
```
