Claude Code skills. What they are, and how to write one.

A Claude Code skill is a SKILL.md file with instructions that Claude uses automatically when relevant, or that you run directly as /skill-name. Write one when you keep pasting the same instructions into chat, or when a section of your CLAUDE.md has grown into a procedure. Unlike CLAUDE.md, a skill's body loads only when it is used.

01Skills and slash commands

If you learned Claude Code a while ago, this is the main change. Custom commands have merged into skills. .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy and work the same way, and your existing command files keep working.

Skills add three things a command file does not have: a folder for supporting files, frontmatter that controls who can invoke them, and the ability for Claude to load them on its own.

02Where skills live

The location sets who gets the skill:

When two skills share a name, enterprise beats personal, and personal beats project. Plugin skills are namespaced, so they never collide.

03What ships built in

Claude Code includes bundled skills you can run today, such as /code-review, /batch, /debug, /loop, /run, /verify, /claude-api, and /skill-doctor. Check these before writing your own. A skill of yours with the same name replaces the bundled command, so pick names on purpose.

Anthropic's document skills are a different case. The Word, Excel, PowerPoint, and PDF skills are not bundled with Claude Code, though pdf and xlsx do arrive through account sync if you sign in with claude.ai.

04Write your first skill

This one drafts customer-facing release notes from your git history. Create the folder:

mkdir -p ~/.claude/skills/release-notes

Save this inside that folder as SKILL.md:

---
name: release-notes
description: Drafts customer-facing release notes from recent git commits. Use when the user asks for release notes, a changelog entry, or a summary of what shipped.
disable-model-invocation: true
allowed-tools: Bash(git log *)
---

Write release notes from these commits:

!`git log --oneline -20`

Rules:
- Group entries under Added, Changed, and Fixed.
- Describe what changed for the customer, not the code.
- Skip merge commits and internal refactors.
- If nothing is customer-facing, say so.

Now type /release-notes. No restart needed, because Claude Code watches skill folders and picks up edits live. The one exception is creating a top-level .claude/skills/ directory mid-session, which needs /reload-skills.

Two details are doing real work here. The !`command` line runs before Claude sees the skill, so it receives the actual commit list. And disable-model-invocation: true means only you can start it, which suits anything you want to time yourself.

05The frontmatter that matters

In Claude Code every field is optional, though description is strongly recommended. Without one, Claude falls back to the first line of the file. These are the fields worth learning first:

06When a skill is the wrong tool

Skills are not the answer to everything. Each of these does a job a skill does badly:

07Install and share

For a team, commit .claude/skills/ to the repository. For wider distribution, publish a plugin. Installing from a marketplace takes two commands:

/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills

Run /plugin with no arguments to browse and manage what you have installed. Skills have the same network access as any other program on your computer, so read third-party skills first, scripts included.

08When a skill misbehaves