Skip to main content
Skills are Markdown files containing instructions that Claude Code loads as reusable workflows. You invoke them with a /skill-name slash command, or Claude can invoke them automatically via the SkillTool. Skills ship with Claude Code, can be defined per-project, and can be created globally for personal use.

​
How skills are loaded

At startup, Claude Code scans the following directories for skills and merges them into the active command set:
SourceDirectoryScope
Managed (enterprise)<managed-path>/.claude/skills/Highest priority
User (global)~/.claude/skills/User-wide
Project.claude/skills/ (project root and parents up to home)Per-project
Additional dirs (--add-dir)<dir>/.claude/skills/Explicit paths
Legacy commands.claude/commands/Deprecated format
BundledCompiled into the binaryAlways available
Skills from deeper directories take precedence over those from parent directories. Symlinks are resolved before deduplication, so the same file accessed via different paths is only loaded once.
Skills are also discovered dynamically during a session as Claude reads or edits files. If a .claude/skills/ directory exists in a subdirectory, its skills become available once Claude touches a file in that subtree.

​
Skill file format

Each skill lives in its own directory containing a SKILL.md file: 
.claude/skills/
└── my-workflow/
    └── SKILL.md

​
SKILL.md frontmatter

Skills use YAML frontmatter to define metadata: 
---
description: Run the full test suite and fix any failures
allowed-tools: Bash, FileEdit, FileRead
argument-hint: <optional test filter>
when_to_use: Use when you want to verify correctness after a change
model: claude-sonnet-4-5
user-invocable: true
---

Run `npm test` with the given filter (if provided). If any tests fail,
read the relevant source files and fix the failures. Then run the tests
again to confirm they pass.

Arguments: $ARGUMENTS

​
Frontmatter fields

FieldTypeDescription
descriptionstringShort description shown in /skills listing
allowed-toolsstringComma-separated list of tools the skill may use
argument-hintstringHint shown when invoking the skill (e.g. <filename>)
when_to_usestringNatural-language hint for when Claude should invoke this skill
modelstringOverride the model used for this skill invocation
user-invocablebooleanWhether the skill appears as a /command (default: true)
argumentsstring or arrayNamed argument placeholders (e.g. [file, branch])
effortstring or intEffort level hint: low, medium, high, or an integer
contextforkRun skill in a forked context (separate conversation thread)
agentstringRoute invocation to a specific named agent
pathsstringGitignore-style path patterns — skill only activates for matching files
hooksobjectHooks configuration scoped to this skill

​
Template variables

Inside the skill body, you can use:
  • $ARGUMENTS — the raw argument string passed by the user
  • ${arg-name} — named argument from the arguments frontmatter field
  • ${CLAUDE_SKILL_DIR} — absolute path to the skill’s own directory (useful for referencing bundled scripts)
  • ${CLAUDE_SESSION_ID} — current session ID

​
Inline shell commands

Prefix a line with ! to run a shell command when the skill is loaded (not during invocation): 
---
description: Show current branch info
---

Current git status:
!`git status --short`
!`git log --oneline -5`
Inline shell commands (!) are not executed in skills loaded from MCP servers, as remote skill content is untrusted.

​
Built-in bundled skills

Several skills ship with Claude Code and are always available:
SkillDescription
/commitCreate a conventional git commit from staged changes
/reviewPerform a code review on recent changes
/verifyRun tests and typechecks to verify correctness
/simplifySimplify complex code while preserving behavior
/debugDiagnose and fix a reported bug
/rememberSave information to persistent memory
/stuckGet unstuck — reflect on the current state and suggest next steps
/loopIteratively run a command until it succeeds
/skillifyConvert a CLAUDE.md instruction into a reusable skill
/batchRun multiple tasks in parallel using sub-agents
Run /skills to see the full list of available skills in your current session.

​
The /skills slash command

Run /skills to open the interactive skills browser. From there you can:
  • List all loaded skills with their descriptions
  • Filter skills by source (user, project, bundled, MCP)
  • Invoke a skill directly
You can also invoke any skill directly as a slash command: 
/my-workflow optional-arguments here

​
How Claude invokes skills via SkillTool

The SkillTool allows Claude to invoke skills programmatically, without the user explicitly typing a slash command. When Claude is deciding which tools to use, it can call SkillTool with a skill name and arguments. This is how skills declared with when_to_use are automatically selected — Claude reads the hint and decides whether the skill applies to the current task. In coordinator mode, workers can also invoke skills, so you can delegate skill invocations (e.g. /commit, /verify) to worker agents rather than running them in the coordinator context.

​
Conditional skills (path-filtered)

A skill with a paths frontmatter key only becomes active when Claude operates on files matching those patterns: 
---
description: Apply React component best practices
paths: src/components/**/*.tsx
---

When editing React components, ensure they follow our conventions...
The paths field uses gitignore-style matching relative to the project root. Conditional skills are stored in memory at load time and activated the first time Claude reads or writes a matching file.

​
Creating a custom skill

1

Create the skill directory

Inside your project, create a directory under .claude/skills/:
mkdir -p .claude/skills/deploy-staging
2

Write the SKILL.md file

Create .claude/skills/deploy-staging/SKILL.md:
---
description: Deploy the current branch to the staging environment
allowed-tools: Bash
argument-hint: <optional environment name>
when_to_use: Use when the user asks to deploy to staging or test the build
---

Deploy the current branch to staging.

1. Run `npm run build` and verify it succeeds.
2. Run `npm run deploy:staging` (or `npm run deploy:$ARGUMENTS` if an
   environment name was provided).
3. Report the staging URL from the command output.
3

Verify the skill loads

Start (or restart) a Claude Code session in the project directory and run:
/skills
Your deploy-staging skill should appear in the list.
4

Invoke the skill

/deploy-staging production
Claude will execute the skill with production as $ARGUMENTS.

Plugins

Package and distribute skills as plugins.

Configuration

Configure skill loading behavior and enterprise policies.

Agent tools

Learn how SkillTool and AgentTool work together.

Hooks

Run shell commands before and after skill invocations.

Build docs developers (and LLMs) love

Get started for freeTalk to us