Course contents
Agent Skills
Package a procedure as a skill that Claude picks up when it's relevant: write the description that routes it, keep the body lean with supporting files, and decide who may run it.
A skill is a folder with a SKILL.md inside: frontmatter that says what the skill is for, instructions Claude follows, and any scripts, templates or reference docs the job needs. The difference from a plain prompt is when it loads. In every session Claude sees only each skill's name and description. The full instructions load when you run the skill or when Claude judges your request matches it. That's why a project can carry dozens of skills without crowding every session, and why the description is the line worth getting right.
Make a skill when you keep pasting the same checklist or multi-step procedure into chat, or when a section of CLAUDE.md has grown from a fact into a procedure. Skills follow the Agent Skills open standard, originally developed by Anthropic and published at agentskills.io, which Claude Code, the Claude API and Cursor's tools support. Claude Code adds its own fields on top, such as invocation control and running a skill in a subagent; a skill you upload to claude.ai can use only the standard's fields.
| Frontmatter | You can run it | Claude can run it | Description in context |
|---|---|---|---|
| (default) | Yes | Yes | Always |
disable-model-invocation: true | Yes | No | No, until you run it |
user-invocable: false | No | Yes | Always |
Which invocation setting fits each skill?
/changelog, which drafts release notes from commits
The description is the router
Claude decides whether to load a skill from its description, so write it the way you'd actually ask. Put the main use first, because the description and when_to_use text are cut off at 1,536 characters in the skill listing. Name the phrases people use (“release notes,” “what shipped”). Keep the procedure in the body, not the description. If a skill doesn't trigger when you expect, the description didn't match your wording; if it triggers too often, it's too broad.
Write a description that makes the changelog skill trigger when it should, and only then.
description: Changelog stuff.
Why can a repository carry thirty skills without bloating every session?
Riley turns a folder of skills into a working agent team — the clearest demo of why skills beat pasting instructions.
Scaffold a skill
Project skills live in
.claude/skills/<name>/SKILL.md; personal ones in~/.claude/skills/<name>/follow you across projects.bashmkdir -p .claude/skills/changelogVerifyThe folder exists at your project root.Write SKILL.md
Frontmatter carries the description Claude matches against. The body is the playbook, and it can point to supporting files that load only when needed. Keep
SKILL.mdunder about 500 lines.markdown--- name: changelog description: Drafts a CHANGELOG entry from the commits since the last tag. Use when the user asks for a changelog, release notes or what shipped. --- # Writing the changelog 1. Run `git log --oneline` since the last tag. 2. Group commits into Added, Changed and Fixed. 3. Write each entry as a user-facing outcome, not a commit message. 4. Append under a new version heading in CHANGELOG.md; never rewrite old entries. For our wording conventions, see [style.md](style.md).VerifySKILL.mdexists with frontmatter, numbered steps and a link to a supporting file.Trigger it in plain language
Don't type the command. Ask the way you normally would and watch Claude pick the skill up.
promptWhat shipped since the last release? Draft the changelog entry.VerifyThe transcript shows the changelog skill loading, then the steps being followed in order.Tune the description
If the skill didn't load, add the phrases you actually used; if it loads for unrelated requests, narrow it.
markdowndescription: Drafts a CHANGELOG entry from the commits since the last tag. Use when the user asks for a changelog, release notes, version-bump notes or what shipped.VerifyThe same plain-language request now loads the skill reliably.Check what your skills cost
List your skills and sort them by token count to see which ones carry the most weight in every session.
prompt/skillsVerifyThe list shows each skill; pressingtsorts by token count.
Plain-English definitions from the AI Coding Dictionary.