Skills

Reusable prompt-based workflows that extend Claude Code with custom commands you invoke with /skill-name.

Skills are Markdown files that define reusable prompt workflows. When you invoke a skill with /skill-name, Claude Code loads the skill’s content and sends it as a prompt — the same way built-in commands like /compact work. Skills let you encode repeated workflows, project-specific instructions, or multi-step procedures into a single command.

/simplify
/review
/remember organize my notes

How skills work

A skill is a directory containing a SKILL.md file with optional YAML frontmatter followed by the prompt body:

---
description: Review the current diff for code quality issues and fix them.
argument-hint: <optional focus area>
allowed-tools: Bash, Read, Edit, Glob, Grep
---

Review all changed files for reuse, quality, and efficiency...

When you type /my-skill, Claude Code:

1. Finds the matching skill file
2. Substitutes any arguments into the prompt body
3. Sends the expanded prompt to the model as a user message

The model then follows the skill’s instructions, using the tools listed in allowed-tools.

Skill sources

Skills are loaded from multiple locations in priority order:

Source	Location	Priority
Managed (policy)	<managed-path>/.claude/skills/	Highest
User	~/.claude/skills/	High
Project	.claude/skills/	Normal
Additional directories	Any --add-dir path’s .claude/skills/	Normal
Bundled	Compiled into the CLI binary	Low
MCP	Exposed by connected MCP servers	Varies

Project skills override user skills with the same name; user skills override bundled skills. If a skill directory exists deeper in your project tree, skills there are loaded dynamically when you touch files in that subtree.

Directory structure

The /skills/ directory uses a directory-per-skill layout:

.claude/
└── skills/
    ├── my-workflow/
    │   └── SKILL.md
    └── api-review/
        ├── SKILL.md
        └── checklist.md   # Reference files Claude can read

Each skill lives in its own subdirectory. The directory name becomes the command name (/my-workflow, /api-review). Reference files in the same directory are accessible to the model via their absolute paths.

The legacy .claude/commands/ directory is also supported. Skills there can use either a single .md file or the SKILL.md directory format, and take the filename (without extension) as the command name.

Frontmatter fields

All frontmatter fields are optional. The skill still works with just a bare Markdown file.

Field	Type	Description
description	string	Shown in /skills list and typeahead. If omitted, extracted from the first heading or paragraph.
argument-hint	string	Placeholder shown in typeahead, e.g. <file> or [branch name].
arguments	string or array	Named argument placeholders that are substituted into the prompt body (e.g. $FILE, $BRANCH).
when_to_use	string	Guidance for Claude about when to invoke the skill proactively.
allowed-tools	string	Comma-separated list of tools the skill is permitted to call, e.g. Bash, Read, Edit.
model	string	Override the model for this skill invocation. Use inherit to use the session model.
effort	string or integer	Effort level for this skill: low, medium, high, max, or an integer.
context	inline or fork	inline (default) expands the skill into the current conversation; fork runs it as a sub-agent with a separate context.
agent	string	When context: fork, the agent type to use (e.g. general-purpose).
paths	string	Glob patterns — skill is only activated when Claude touches matching files.
user-invocable	boolean	Set false to hide the skill from typeahead (only Claude can use it).
hooks	object	Session-scoped hooks registered when the skill is invoked.

Named arguments

Use arguments frontmatter to define named placeholders:

---
description: Summarize a file for the given audience.
arguments: FILE, AUDIENCE
---

Summarize the contents of $FILE for an audience of $AUDIENCE. Be concise.

Invoke it with:

/summarize path/to/notes.md engineers

If no argument hint is set, Claude Code shows [args] in the typeahead.

Conditional activation (paths)

Skills with a paths field are dormant until Claude touches a matching file:

---
description: Apply migration best practices.
paths: db/migrations/**
---

Review this migration for common pitfalls...

Once Claude reads or writes a file matching db/migrations/**, the skill becomes available in the session.

Example skill file

---
description: Review changed code for reuse, quality, and efficiency, then fix any issues.
argument-hint: <optional focus area>
---

# Simplify: Code Review and Cleanup

Review all changed files for reuse, quality, and efficiency. Fix any issues found.

## Phase 1: Identify Changes

Run `git diff` to see what changed.

## Phase 2: Review and Fix

Check for:
- Duplicate code that reuses existing utilities
- Redundant state or unnecessary complexity
- Missed concurrency opportunities

Fix each issue directly. When done, briefly summarize what was fixed.

Bundled skills

Claude Code ships with a set of built-in skills compiled into the binary. These are available in every session without any configuration.

Skill	Description
simplify	Reviews changed code for reuse, quality, and efficiency, then fixes issues
verify	Verifies that a code change works correctly by running the app
remember	Reviews auto-memory entries and proposes promotions to CLAUDE.md or CLAUDE.local.md
loop	Runs a workflow in a loop until a condition is met
batch	Applies a skill to multiple inputs in parallel

Bundled skills follow the same YAML frontmatter format as user-defined skills. They appear in /skills alongside your custom skills.

Shell execution in prompts

Skill prompt bodies can embed shell commands that run when the skill is invoked. Use backtick blocks prefixed with !:

The current git status is:

!`git status --short`

Review the changes above and...

The output of the shell command is substituted into the prompt before it is sent to the model. This lets skills include dynamic context like the current branch name, environment variables, or file listings.

Shell execution only runs for local skills (not MCP-provided skills). MCP skills are remote and untrusted — inline shell commands in their bodies are ignored for security.

Creating a skill

1. Create the directory

   Inside your project or home config directory, create a skill subdirectory:

   mkdir -p .claude/skills/my-workflow
   
2. Write SKILL.md

   Create .claude/skills/my-workflow/SKILL.md with frontmatter and your prompt:

   ---
   description: Describe what this skill does.
   argument-hint: <optional argument>
   allowed-tools: Read, Edit, Bash
   ---
   
   Your prompt content here. Claude will follow these instructions
   when you run /my-workflow.
   
3. Invoke the skill

   Type /my-workflow at the Claude Code prompt. The skill appears in the typeahead list immediately.

   /my-workflow
   

Skills can also come from plugins. See Plugins for how to install and publish skill packages.