← All posts

How Do I Create a Skill in Claude Code?

A skill is a folder with a SKILL.md file that teaches Claude a procedure. It costs almost nothing until it is used, and it doubles as your own slash command.

November 17, 2026 7 min read Guide
Quick answer

Make a folder .claude/skills/<skill-name>/ in your project (or ~/.claude/skills/<skill-name>/ for every project) and put a SKILL.md file in it. Start the file with YAML frontmatter that has at least a description, then write the instructions in Markdown. At startup Claude only sees the description; the full file loads when you type /skill-name or when Claude decides the skill fits your request. Add disable-model-invocation: true if only you should trigger it, as with a deploy.

What does a minimal skill look like?

.claude/skills/release-notes/SKILL.md
---
name: release-notes
description: Drafts release notes from merged pull requests. Use when asked for release notes or a changelog entry.
disable-model-invocation: true
allowed-tools: Bash(git log *) Read
---

1. Run git log from the last tag to HEAD.
2. Group changes into Added, Changed and Fixed.
3. One line per change, in plain language, no commit hashes.
4. Write the result to CHANGELOG.md under a new heading.

Type /release-notes and Claude follows the steps. The name defaults to the folder name, so you can leave it out.

Where do skills live?

ScopePath
Personal~/.claude/skills/<name>/SKILL.md
Project (commit to share).claude/skills/<name>/SKILL.md
Nested in a subfolder<subdir>/.claude/skills/<name>/SKILL.md, loaded when Claude works in that folder
Plugin<plugin>/skills/<name>/SKILL.md, called as /plugin-name:skill-name
EnterpriseThe managed settings directory, for everyone your organization deploys to

Which frontmatter fields should I know?

FieldWhat it does
descriptionWhat the skill does and when to use it. Claude decides from this text
disable-model-invocationtrue means only you can run it; the description is not loaded at startup
user-invocablefalse hides it from the / menu so only Claude uses it
allowed-toolsTools Claude may use without asking during the turn that runs the skill
argument-hint, argumentsAutocomplete hint and named arguments
model, effortOverride the model or effort level for that turn
context: forkRun the skill in a forked subagent instead of the main conversation
pathsGlob patterns; Claude loads the skill on its own only for matching files

Unknown fields are ignored without an error. One portability note from the skills docs: fields beyond name, description, license, compatibility, metadata and allowed-tools are Claude Code extensions, and skill uploads to claude.ai or the Skills API reject them.

How does a skill load, and what does it cost?

The docs recommend keeping SKILL.md under 500 lines and putting the important steps first. This is also why moving rarely used instructions out of CLAUDE.md into skills shrinks every request: CLAUDE.md loads every session, a skill body only when needed.

How do I pass arguments?

Text after the command becomes the arguments. Inside SKILL.md:

If no placeholder takes the input, Claude Code appends it as ARGUMENTS: <value>.

Can a skill include scripts and reference files?

Yes. Anything in the skill folder is available. Mention each file in SKILL.md so Claude knows when to open it:

my-skill/
├── SKILL.md        (required)
├── reference.md    (read when needed)
├── examples.md     (read when needed)
└── scripts/
    └── helper.py   (run, not loaded)

Scripts are executed rather than read into context, which keeps long logic out of the token count.

What about my old .claude/commands files?

They still work: .claude/commands/deploy.md still gives you /deploy. Commands have been merged into skills, which means Claude may now run a command on its own unless you set disable-model-invocation: true. To add supporting files, move it to .claude/skills/deploy/SKILL.md; you still type /deploy. If both exist with one name, the skill wins.

Does Claude Code ship with skills?

Yes. Bundled skills such as /doctor, /code-review, /batch, /debug and /loop are available in every session. Run /skills to list everything available, filter by name, and press t to sort by token count.

FAQ

Why does Claude not use my skill on its own?

Claude decides from the description. Lead with the words a request would contain, say when to use it, and check that disable-model-invocation is not set.

Do I need to restart after editing a skill?

No. Edits inside existing skill folders apply in the current session. Creating a brand new top-level skills folder needs /reload-skills.

Should a workflow be a skill or a subagent?

Use a skill for instructions you want in the current conversation. Use a subagent, or a skill with context: fork, when the work produces lots of output you do not need to keep.

Can a skill run without permission prompts?

List the tools in allowed-tools. They run without prompting only during the turn that invokes the skill; your deny rules still apply.

Sources

Checked against the official docs on November 17, 2026: Extend Claude with skills, Commands and Manage costs effectively.

See every current command and shortcut in one reference.

Open the Claude Code Cheatsheet →