# Skills, loaded only when needed

A skill is a folder whose description sits in context and whose body arrives only when the task calls for it. That split is what makes skills cheap, and what makes a bad description expensive.

## Instructions that cost nothing until used

Everything you put in CLAUDE.md is read at the start of every session. That is fine for a few rules and wasteful for a twenty-step release procedure you need once a week.

A **skill** solves this. It is a folder containing a `SKILL.md` file: YAML frontmatter on top, markdown instructions below. Only the description stays in context. The body loads when the skill is used, either because you called it or because Claude decided the description matches the task.

So a skill is a table of contents entry that can expand into a chapter. The entry is always there. The chapter is not.

## Where a skill lives

A skill can sit in several places, and the place decides who sees it.

- `~/.claude/skills/` for your own skills in every project
- `.claude/skills/` inside a project, shared through git
- a plugin, which you will meet in a later lesson
- managed settings, for an organisation

When the same name exists twice, enterprise beats personal and personal beats project. Custom commands in `.claude/commands/` have been merged into skills, so one mechanism covers both.

## What is in the file

Every frontmatter field is optional, but two do most of the work: `name` and `description`. Here is a small, real shape:

```markdown
---
name: release-notes
description: Draft release notes from the commits since the last tag. Use when asked for a changelog or release summary.
disable-model-invocation: true
---

Summarise the commits since the last tag.

!`git log $(git describe --tags --abbrev=0)..HEAD --oneline`

Group them under Added, Changed and Fixed. Skip merge commits.
```

The line that starts with `!` and a backtick runs a shell command before Claude sees the text, so the commit list is already inside the prompt. The catch: if that command fails, the whole skill invocation aborts. Append `|| true` when a failure is acceptable.

`disable-model-invocation: true` means only you can start it. Use it for anything with side effects, such as deploying or sending something. A skill that publishes should never run because Claude thought it sounded relevant.

**Question:** What stays in context all the time for a skill that is not currently in use?

- The whole SKILL.md file
- Only its description
- Nothing at all
- Only the supporting files

**Answer:** Only its description. The description is the part Claude uses to decide whether the skill applies. The body loads only when the skill is used.


## Writing one that works

Most of the quality is in the description, because that is the only part Claude sees when deciding.

- Put the key use case first. The `description` and `when_to_use` text together are cut at 1,536 characters in the skill listing.
- Say when to use it, not only what it is. "Draft release notes. Use when asked for a changelog" beats "Release notes helper".
- Keep `SKILL.md` under about 500 lines and move reference material into supporting files in the same folder.
- Put the most important instructions first, because truncation keeps the start.

> **Silent failures**
Frontmatter only parses if `---` is the very first line of the file. Unknown fields are ignored without any message, so a misspelled `disable-model-invocation` simply does nothing.


## Seeing what it costs

Run `/skills` to list your skills with token counts, and `/skill-doctor` to see cost and usage. If a skill's description is long and rarely useful, that cost is paid every turn for nothing.

Edits to an existing skill file are picked up live. A brand new top-level skill directory needs `/reload-skills` before it appears.

> **Turn a habit into a skill**
Think of something you explained to Claude three times this month. Create `.claude/skills/<name>/SKILL.md`, write a description that says when to use it, run `/reload-skills`, then check `/skills` to see what it costs.


**Question:** Why mark a deploy skill with disable-model-invocation: true?

- It makes the skill load faster
- Only you can run it, so Claude cannot trigger it by guessing
- It removes the description from context
- It lets the skill use more tools

**Answer:** Only you can run it, so Claude cannot trigger it by guessing. Side-effecting workflows should start only when you decide. With the flag set, Claude cannot invoke the skill on its own.