Claude Code skills: packaged expertise the agent loads on demand

The shape of a skill

.claude/skills/
  release-notes/
    SKILL.md          <- required, the entrypoint
    template.md       <- optional reference, read on demand
    scripts/
      collect.sh      <- optional script, executed not read

---
name: release-notes
description: Writes release notes from merged pull requests between two git tags. Use when asked to draft release notes, a changelog entry, or a summary of what shipped.
allowed-tools: Bash(git log *) Bash(gh pr list *)
---

# Release notes

## Gathering the input

Run `${CLAUDE_SKILL_DIR}/scripts/collect.sh <from-tag> <to-tag>`. It outputs one
line per merged PR with number, title, and author.

## Writing them

Follow `template.md` exactly. Rules that matter:

- Group by user-visible impact, never by component.
- One line per change, written from the user point of view. "Sessions no
  longer drop on reconnect", not "fixed WebSocket handler".
- Omit anything invisible to a user: refactors, test changes, CI.
- Breaking changes go first, under their own heading, with the migration.
- Never invent a change that is not in the input.

• On a name clash, enterprise beats personal beats project, and any of them beats a bundled skill of the same name.
• Plugin skills are namespaced plugin-name:skill-name, so they cannot collide.
• Project skills also load from every parent directory up to the repository root, so starting in a subdirectory still picks up the root ones.
• Nested .claude/skills/ below your starting directory load lazily, the first time the agent reads or edits a file in that subtree. A monorepo package can therefore ship skills that only appear when you work on it.
• Skill directories are watched live: adding or editing a SKILL.md takes effect in the running session with no restart.

Why progressive disclosure is the whole point

This is the property that makes skills worth using rather than a stylistic alternative to project memory.

The listing is not free, though, and it is budgeted. Claude Code allocates roughly 1 percent of the model context window to skill names and descriptions. The listing always contains every skill name; when it overflows, descriptions are dropped starting with the skills you invoke least. Each entry combining description and when_to_use is capped at 1,536 characters regardless of budget.

/doctor        # estimates the listing cost and names the biggest contributors
/context       # the Skills row reports the listing size after the budget is applied

The frontmatter, field by field

Every field is optional. Only description is genuinely recommended, because it is how the model decides the skill applies.

Pre-approving tools, and the trust question

---
name: commit
description: Stage and commit the current changes
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---

Stage the relevant changes and commit with a message that explains why,
not what. Never use --no-verify. Never commit to main.

Skills, commands, and subagents

Custom commands were merged into skills. A file at .claude/commands/deploy.md and a directory at .claude/skills/deploy/SKILL.md both create /deploy and behave the same way. Existing command files keep working; skills add a directory for supporting files, frontmatter, and automatic invocation.

• Use a skill when the agent should know how to do something in the conversation you are already having.
• Use a skill with context: fork when the skill is a self-contained task and you want it out of your context. It runs in the background by default; set background: false to wait for the result in the invoking turn.
• Use a subagent when you want a reusable agent type with its own system prompt and tool set that the model delegates to on its own judgement.

Writing one that actually fires

The most common complaint about skills is that they never trigger, and the cause is nearly always the description.

That last row is worth stating precisely. Once invoked, the rendered SKILL.md stays in the conversation for the rest of the session, and the file is not re-read on later turns. After a compaction, Claude Code re-attaches the most recent invocation of each skill, keeping the first 5,000 tokens of each within a 25,000 token combined budget, newest first. Invoke six skills in one long session and the earliest are simply gone.

Questions people ask

Keep reading