# Claude Code skills: how to write a SKILL.md, with examples

A Claude Code skill is a folder with a SKILL.md file of instructions. Put it in .claude/skills/<name>/ and it becomes the command /<name>; Claude also loads it by itself when a request matches its description. Use skills for procedures and reference you need sometimes, and CLAUDE.md for facts Claude needs every time.

- Page: https://tecyfy.com/coding-agents/claude-code/skills
- Guide: Claude Code (https://tecyfy.com/coding-agents/claude-code), from Anthropic's documentation (https://code.claude.com/docs/en/overview)

A skill is a set of instructions you write once and Claude uses when it needs them. It is a folder with a `SKILL.md` file inside. Claude Code turns it into a slash command, and Claude can also load it on its own when a request matches what the skill says it is for.

Make a skill when you keep pasting the same checklist into the chat, or when a part of [CLAUDE.md](/coding-agents/claude-code/project-instructions) has grown from a fact into a procedure.

## Your first skill

Create `.claude/skills/release-notes/SKILL.md` in your project:

```markdown
---
description: Writes release notes from the commits since the last tag. Use when asked for release notes, a changelog entry or "what shipped".
disable-model-invocation: true
---
## Commits since the last tag
!`git log $(git describe --tags --abbrev=0)..HEAD --oneline`

## Instructions
Group the commits above under Added, Changed and Fixed. Write each as one
plain sentence a customer would understand. Leave out merges, version bumps
and anything that only touches tests or CI.
```

Now `/release-notes` runs it. 3 parts are doing the work:

- **The description** tells Claude what the skill is for. It is the only part Claude sees until the skill is used, so put the main use first and use the words people actually type.
- **The `` !`command` `` line** runs before Claude reads the skill, and its output takes the line's place. Claude gets the real commit list, not a guess.
- **`disable-model-invocation: true`** means only you start it. Leave it out and Claude may load the skill whenever someone asks for release notes.

## Where skills live

| Folder | Available |
| --- | --- |
| `.claude/skills/<name>/` in a project | In that repository, for everyone once committed |
| `~/.claude/skills/<name>/` | In all your projects on this machine |
| Inside a [plugin](/coding-agents/claude-code/plugins) | Wherever the plugin is installed, as `/plugin-name:skill-name` |

The folder's name is the command's name. Files in the older `.claude/commands/` folder, such as `.claude/commands/deploy.md`, still make `/deploy` and work the same way.

Claude Code also comes with bundled skills, such as `/code-review`, `/debug` and `/simplify`. They are prompts for Claude like yours, listed with the [commands](/coding-agents/claude-code/commands).

## Passing arguments

Whatever you type after the command arrives as `$ARGUMENTS`:

```markdown
---
description: Fix a GitHub issue by number
disable-model-invocation: true
---
Fix GitHub issue $ARGUMENTS. Read the issue, write a failing test first,
then make it pass. Do not commit.
```

`/fix-issue 482` sends "Fix GitHub issue 482...". For several values, use `$0`, `$1` and so on, or name them with an `arguments` field and write `$issue`. Wrap a value with spaces in quotes.

## The fields that matter

All are optional, but write a `description`.

| Field | What it does |
| --- | --- |
| `description` | What the skill does and when to use it. Claude reads this to decide |
| `disable-model-invocation` | `true`: only you can start it, with its command |
| `user-invocable` | `false`: only Claude can start it; it is hidden from the `/` menu |
| `allowed-tools` | Tools that run without asking during the turn the skill is used, such as `Bash(git log *)` |
| `paths` | Load it automatically only when Claude works on matching files, such as `src/api/**` |
| `model`, `effort` | Use another model or effort level while the skill runs |
| `context: fork` | Run it in a separate [Subagent](https://tecyfy.com/concepts#subagent) that does not see your conversation |
| `argument-hint` | The hint shown as you type, such as `[issue-number]` |

`allowed-tools` deserves a second look in any repository you did not write: a skill can give itself permission to run commands, and that applies even before you trust the folder.

## Long material: supporting files

Keep `SKILL.md` short and point to other files in the folder:

```text
api-guide/
  SKILL.md          # what the skill is for and which file to read when
  endpoints.md      # read only when needed
  scripts/
    check_schema.py # run, not read
```

Claude reads `endpoints.md` only when the task calls for it, and runs scripts rather than loading them. A long API reference costs nothing until it is needed.

## How skills use context

Until a skill is used, only its name and description are in the [Context Window](https://tecyfy.com/concepts/context-window). Once used, its instructions stay in the conversation for the rest of the session, so every line is a cost on every later turn. When the conversation is compacted, Claude Code keeps the first 5,000 tokens of each skill used. Write what to do, not why, and move detail into supporting files.

With `context: fork`, a skill runs in its own subagent instead, with the skill as its whole prompt. Use it for self-contained jobs, such as a research sweep, whose working steps you do not need in your conversation; only the result comes back.

## Skill, CLAUDE.md, subagent or hook?

- **[CLAUDE.md](/coding-agents/claude-code/project-instructions)**: short facts Claude needs in every session.
- **Skill**: a procedure or reference Claude needs sometimes.
- **[Subagent](/coding-agents/claude-code/subagents)**: a helper with its own context and tools that does a job and reports back.
- **[Hook](/coding-agents/claude-code/hooks)**: something that must happen every time, decided by Claude Code rather than by Claude.

## Questions

### How do I create a skill in Claude Code?

Make a folder, such as .claude/skills/release-notes/, and put a SKILL.md file in it with a short description between --- lines at the top and your instructions below. Run it with /release-notes, or ask for something the description mentions and Claude loads it itself.

### What is the difference between a skill and CLAUDE.md?

CLAUDE.md is loaded into every session, so it should hold short facts Claude always needs. A skill's instructions load only when it is used, so it can hold a long procedure or reference without costing anything the rest of the time. Only its description is always visible to Claude.

### Are skills and slash commands the same thing in Claude Code?

Yes, they have merged. A file in .claude/commands/deploy.md and a skill in .claude/skills/deploy/SKILL.md both make /deploy. Old command files keep working; skills add a folder for supporting files and more options.

### Why does Claude not use my skill?

Claude decides from the description, so make it say what the skill does and when to use it, with the words people actually type. Check the skill appears when you type /, and that disable-model-invocation is not set to true, which stops Claude loading it on its own.

### Can I use Claude Code skills in other tools?

Skills follow the Agent Skills open standard, which other AI tools also read. Claude Code adds its own fields, such as context fork and allowed-tools, that other tools may ignore.

## Sources

- [Extend Claude with skills](https://code.claude.com/docs/en/skills)
- [How Claude remembers your project](https://code.claude.com/docs/en/memory)