Skills: what they are, how to add and use

You have a Tuesday ritual. You paste the same three paragraphs into Claude Code: how your team names branches, which tests must pass before a PR, the house style for error messages, and a reminder not to reformat half the monorepo while fixing one bug. By Thursday the paste is slightly wrong because you edited it in a doc and forgot to update the chat version. By next month a new hire asks where “the good prompt” lives and you point at a Slack thread from February.

That is the skill problem. This is Part 4 of the Claude Code tutorial. Part 3 covered slash commands and shell patterns (claude, -c, -r, -p). Here we treat skills as first-class: what they are, how they differ from always-on project memory, where files live, how to add one, how to invoke /name, and when Claude should load one without you asking. If you still need product orientation before coding-agent depth, use the Claude product map.

What you’ll learn

• A plain definition of a Claude Code skill (SKILL.md playbook in a toolkit)
• Skills vs CLAUDE.md: on-demand body vs always-on standing rules
• Where skills live: personal ~/.claude/skills/, project .claude/skills/, plugins, enterprise
• How to add a skill, write frontmatter, and test both auto and manual invoke
• Legacy .claude/commands/ still works; skills are the recommended home
• Bundled skills such as /code-review and how they differ from fixed built-in commands

Facts below track official docs at code.claude.com/docs/en/skills. Frontmatter fields and version edges move. Re-check the live page before you encode team policy in a hundred repos.

What a skill is (plain English)

A skill is a packaged set of instructions Claude can load into its toolkit. On disk it is usually a directory with a required SKILL.md file. That file has two parts:

• YAML frontmatter between --- markers: at least a good description so Claude knows when the skill is relevant
• Markdown body: the checklist, conventions, steps, or reference Claude should follow when the skill runs

You can invoke a skill directly by typing / plus the skill name (the directory name for personal and project skills). Claude can also load a skill automatically when your conversation matches the description. Official docs put it simply: create a skill when you keep pasting the same instructions, checklist, or multi-step procedure, or when a section of CLAUDE.md has grown into a procedure rather than a standing fact.

Skills follow the broader Agent Skills idea used across tools. Claude Code adds product-specific controls: who may invoke a skill, optional subagent execution, dynamic context injection, and more. You do not need the whole advanced catalog on day one. You need one working skill that replaces a sticky note.

Plain definition: A skill is an on-demand playbook. The short description is always cheap to list. The long body loads when you invoke the skill or when Claude decides it is relevant.

Skills vs CLAUDE.md: the load story

People mash these together because both are markdown that steer Claude. The load behavior is different, and that difference is the whole reason skills exist.

CLAUDE.md (and friends) is always-on project memory for a session. Standing facts live here: language version, how to run tests, naming conventions that apply to almost every task, “never commit secrets,” preferred libraries. Official guidance treats this as context Claude reads early so it does not rediscover basics every time. Always-on text costs context even when the task is unrelated. Stuffing a 400-line deploy runbook into always-on memory is how you waste tokens on a typo fix.

Skills keep a short description available so Claude knows the toolkit entry exists. The long body loads when used. That means long reference material is almost free until you need it. Deploy checklists, PR templates with many steps, domain API catalogs, incident response playbooks: those are skill shapes.

A practical migration rule from official skill docs: if a section of CLAUDE.md became a procedure, peel it into a skill. Leave the always-on file for constraints and facts. Part 6 of this series goes deeper on instruction files; keep the split in mind now so you do not build the wrong thing this week.

Where skills live

Location decides who gets the skill.

Name precedence matters when the same skill name appears at multiple levels. Official docs describe overrides such as enterprise over personal over project, and a skill at those levels can override a bundled skill with the same name. Plugin skills use a namespaced form so they do not collide the same way. Nested monorepo skills under package directories can appear with directory-qualified names. You do not need every edge case memorized before your first skill. You do need to pick personal vs project on purpose.

Personal is perfect for your own taste: how you like commit messages, your preferred explore checklist, a summarize-diff habit. Project is for team truth: how this service deploys, which tests gate a PR, domain language for this product. Putting team deploy steps only in your home directory is how the next engineer ships without the checklist.

Legacy .claude/commands/ still works

Older custom commands were markdown files under .claude/commands/ (project) or ~/.claude/commands/ (personal). Official docs are explicit: custom commands have been merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and work the same for invocation. Existing command files keep working. Skills add optional power: a directory for supporting files, frontmatter to control who invokes the skill, and automatic loading when relevant.

If you already have command files, do not panic-migrate on a Friday. Prefer skills for anything new. When a command grows, convert it into a skill directory so you can attach examples, scripts, and references without one giant markdown blob.

Bundled skills (including /code-review)

Claude Code ships bundled skills such as /code-review, and others documented alongside commands (examples in docs include playbooks like debug, batch-style work, doctor-style checkup depending on version). Bundled skills are prompt-based: they give Claude detailed instructions and let it orchestrate tools. Most built-in commands instead execute fixed product logic.

You invoke a bundled skill the same way as any other skill: type / and the name. Some bundled skills may auto-run when relevant; others, including longer checks such as code review in recent versions, may run only when you invoke them so you stay in control of time and tokens. Exact auto-invoke rules can change by version. When a long review starts “by itself” and you did not want it, check skill visibility settings and release notes.

You can also override a bundled skill by shipping a same-named skill in project or personal space if your team needs different review standards. Do that carefully: surprise overrides confuse newcomers who expected the stock behavior.

Add your first skill (worked path)

We will build a small personal skill that summarizes uncommitted changes and flags risks. This mirrors the shape of official getting-started examples without pretending your repo is their demo.

Step 1: create the directory

mkdir -p ~/.claude/skills/summarize-changes

For a team skill, use the project path instead:

mkdir -p .claude/skills/summarize-changes

Step 2: write SKILL.md

Create ~/.claude/skills/summarize-changes/SKILL.md (or the project path). Minimum useful shape:

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Instructions

1. Inspect the current git status and uncommitted diff.
2. Summarize the changes in two or three bullet points a teammate could skim.
3. List risks: missing tests, hardcoded secrets, drive-by refactors, unclear naming.
4. If there are no uncommitted changes, say so and stop.

Keep the tone plain. Do not invent files that are not in the diff.

The directory name becomes the command you type: /summarize-changes. The description is what Claude uses to decide auto-loading. Put the key use case first. Vague descriptions cause wrong or missed loads.

Official examples often inject live shell output into the skill body with a special !`command` form so Claude sees real data before reasoning. That is powerful and worth learning once you are comfortable. Your first skill can stay simpler: tell Claude which tools and git commands to use in the instructions, then tighten with dynamic injection later.

Step 3: test two ways

Open a git project, make a tiny edit, start Claude Code:

cd ~/work/my-app
# make a small edit to any tracked file
claude

Manual invoke:

/summarize-changes

Natural language that should match the description:

What did I change? Flag anything risky before I commit.

If auto-load fails but manual works, fix the description. If neither works, check the path, the filename (SKILL.md exact), and whether slash skills are disabled for the session. Live change detection usually picks up skill edits under watched directories without a full reinstall; creating a brand-new top-level skills directory that did not exist at session start may require restarting Claude Code so it can watch the new folder.

Frontmatter you will actually use

All frontmatter fields are optional in the strict sense; description is the one you should treat as required for quality. A short practical set:

Side-effect workflows should almost always set disable-model-invocation: true. You do not want Claude deciding that your code “looks ready” and firing /deploy because the description matched a victory lap in chat. Knowledge packs that are never a sensible button can hide from the menu with user-invocable: false while still informing the model when relevant.

Arguments and stacking

Text after the skill name becomes arguments. Skills can reference $ARGUMENTS (and indexed forms) in the body. Example shape:

---
description: Fix a GitHub issue by number following repo standards. Use when the user wants a full issue fix workflow.
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS.

1. Read the issue and restate acceptance criteria.
2. Implement the smallest change that meets them.
3. Add or update tests.
4. Summarize residual risks. Do not push unless asked.

Then:

/fix-issue 1234

Newer versions can stack multiple skills at the start of a message and share trailing arguments across them. Treat stacking as an advanced convenience after single-skill habits are solid. If a skill runs as a forked subagent, stacking rules may stop expansion there. When behavior surprises you, simplify to one skill plus plain follow-up chat.

Supporting files and keeping SKILL.md short

A skill directory can hold more than one file:

my-skill/
├── SKILL.md           # required entrypoint
├── reference.md       # long API notes, load when needed
├── examples/
│   └── sample.md
└── scripts/
    └── validate.sh

Point to those files from SKILL.md so Claude knows when to open them. Official tips push for a concise body (on the order of hundreds of lines, not a novel). Once a skill loads, its content stays in the conversation for the rest of the session, so every line is a recurring cost. Write instructions, not essays about how proud the team is of the process.

Worked workplace examples

Project skill: PR checklist

Commit .claude/skills/pr-ready/SKILL.md with steps: run the unit suite command your README names, check for leftover debug logs, confirm migration files have down paths if your stack needs them, draft a PR summary with risk section. Set disable-model-invocation: true if you only want humans to trigger the ship ritual.

Personal skill: explore-first

A personal skill that forces map-before-edit: list entry points, cite three files, propose a plan, wait for approval language. Useful if you personally tend to approve too fast. Not every teammate may want your caution ritual as project law.

Domain skill: analytics SQL house rules

If your team generates SQL with agents, a skill can encode grain rules, required filters (tenant, date), and “show EXPLAIN before large scans” habits. Pair that with human review. Our guide on how to check AI-written SQL still applies after a skill runs.

How auto-load should feel

When descriptions are sharp, auto-load feels like a competent teammate grabbing the right binder. When descriptions overlap or stay vague, Claude may load the wrong skill or miss the right one. Write descriptions with trigger language real humans use: “when the user asks for a commit message,” “when reviewing a pull request,” “when changing billing migrations.”

If auto-load becomes annoying, options include tightening the description, setting disable-model-invocation: true for manual-only skills, or using skill visibility overrides in settings so a skill is name-only, user-only, or off. Official docs document a /skills style menu for listing and adjusting visibility without hand-editing JSON every time.

Skills in other surfaces (brief honesty)

Local Claude Code sessions read personal and project skill directories on your machine. Cowork sessions and some cloud sessions do not magically mount your home ~/.claude/skills/ the way a laptop session does. Cloud work often relies on project skills committed to the repo, plugins declared for the environment, or account-level skills depending on product. If a routine says a skill was not found, check whether the skill exists only on your laptop. Part later in this series and product-map posts cover surface differences; the practical rule is: team-critical skills belong in the repo or managed distribution, not only on one engineer’s disk.

Common mistakes

Putting a novel in CLAUDE.md

Always-on memory is for always-true facts. Long procedures belong in skills. If every task pays for a deploy essay, your typo fixes get worse, not better.

Vague descriptions

“Helps with code” matches everything and nothing. Name the job and the trigger phrases.

Side-effect skills without disable-model-invocation

Deploys, messages to customers, force-pushes, production data fixes: human-triggered only unless you have a very intentional automation design.

Personal-only team rituals

If the skill is how the service ships, commit it under project .claude/skills/. Onboarding should not require cloning your home directory.

allowed-tools without review

Pre-approving broad shell patterns in a committed project skill is a trust decision. Read the skill before you accept workspace trust prompts. Treat surprise allowed-tools like surprise CI secrets.

Expecting skills to replace judgment

A perfect /code-review run is still not a merge. Skills improve consistency. They do not own outcomes.

FAQ

Is a skill the same as a slash command?

Invocation looks the same: /name. Built-in commands are fixed product actions. Skills (including bundled ones) are playbooks. Custom commands and skills both create slash entries; skills are the recommended packaging now.

Can Claude invent a skill without a file?

It can follow instructions you type in chat. That is not a skill. A skill is a durable file others can share and invoke by name. If you keep retyping, write the file.

Do I need plugins first?

No. Personal and project skills work without plugins. Plugins become useful when you want distributeable bundles with more moving parts. Later parts of this series cover plugins and connectors.

Will skills replace CLAUDE.md?

No. Different load jobs. Always-on facts stay in instruction files. On-demand procedures move to skills. Healthy repos use both.

How to practice

1. List three prompts you paste more than twice a month. Circle one that is a procedure, not a standing fact.
2. Create a personal skill directory and a minimal SKILL.md with a sharp description.
3. Test /your-skill-name on a real small change. Then test a natural-language prompt that should auto-load it.
4. If auto-load fails, rewrite only the description and try again before adding frontmatter complexity.
5. Promote one team ritual into project .claude/skills/ and open a PR that only adds the skill plus a one-line README note.
6. Invoke a bundled skill such as /code-review on a throwaway branch and compare its notes with your own reading of the diff.

What comes next

Part 5 of the Claude Code tutorial covers memory and context: what sticks across sessions, what resets, and how compaction interacts with skills and instruction files. Part 6 goes deep on CLAUDE.md, AGENTS.md, and friends. Later parts cover plugins, agent loops, diff review, and team safety rails.

For product-family orientation again, see Claude product map. Everyday chat habits remain in Learn Claude from scratch. Verification culture without vendor lock-in sits in the Practical AI series.

Quick recap

• A skill is a SKILL.md playbook Claude can load on demand or when relevant.
• Invoke with /skill-name; directory name is the command for personal and project skills.
• CLAUDE.md is always-on; skill bodies are on-demand. Peel procedures out of always-on memory.
• Personal path: ~/.claude/skills/. Project path: .claude/skills/. Commit team truth.
• Legacy .claude/commands/ still works; prefer skills for new work.
• Bundled skills like /code-review are playbooks, not fixed light switches.
• Write sharp descriptions; lock side effects to human invoke; review allowed-tools in shared repos.

Sources

Official Claude Code documentation used for skills claims in this article (re-check after upgrades):

• Extend Claude with skills: https://code.claude.com/docs/en/skills
• Commands reference (built-ins vs bundled skills): https://code.claude.com/docs/en/commands
• Features overview: https://code.claude.com/docs/en/features-overview
• Claude Code overview (CLAUDE.md and skills in the product story): https://code.claude.com/docs/en/overview
• Best practices (when to create skills): https://code.claude.com/docs/en/best-practices
• Context window notes (skills and compaction): https://code.claude.com/docs/en/context-window
• CLI reference: https://code.claude.com/docs/en/cli-reference
• Glossary (skill and bundled skills definitions): https://code.claude.com/docs/en/glossary
• Analytics Made Simple: Claude Code tutorial series
• Analytics Made Simple: Claude product map series

More definitions in Key Terms →

Merch on Etsy

Open store →

Naive Bayes Mouse Pad, Data Science Mouse Pad, Analytics Mouse Pad, Bayesian Mouse Pad View on Etsy → Boxplot Mouse Pad, Data Science Mouse Pad, Analytics Mouse Pad, Box Plot, Whisker Plot View on Etsy → Dashboard to Excel Ceramic Coffee Mug View on Etsy → You're On Mute White Ceramic Coffee Mug, Data Science Mug, Data Mug, Analytics Mug, Statistics Mug, Programming Mug, Gift Mug, Coffee Mug View on Etsy →