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:
---
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.
What stays in context all the time for a skill that is not currently in use?
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
descriptionandwhen_to_usetext 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.mdunder 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.
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.
Why mark a deploy skill with disable-model-invocation: true?
Chapter complete
You've finished chapter 1 of 6 in Extending Claude Code.
A CLAUDE.md line is a request the model usually honours. A hook is code the harness runs, so it happens every time. Choose hooks only for rules that have no exceptions.
Next chapter