SKILL.md file with instructions, and Claude adds it to its toolkit. Claude uses skills when relevant, or you can invoke one directly with /skill-name.
For built-in commands like
/help and /compact, see interactive mode.Custom slash commands have been merged into skills. A file at .claude/commands/review.md and a skill at .claude/skills/review/SKILL.md both create /review and work the same way. Your existing .claude/commands/ files keep working. Skills add optional features: a directory for supporting files, frontmatter to control whether you or Claude invokes them, and the ability for Claude to load them automatically when relevant.Getting started
Create your first skill
This example creates a skill that teaches Claude to explain code using visual diagrams and analogies. Since it uses default frontmatter, Claude can load it automatically when you ask how something works, or you can invoke it directly with/explain-code.
Create the skill directory
Create a directory for the skill in your personal skills folder. Personal skills are available across all your projects.
Write SKILL.md
Every skill needs a
SKILL.md file with two parts: YAML frontmatter (between --- markers) that tells Claude when to use the skill, and markdown content with instructions Claude follows when the skill is invoked. The name field becomes the /slash-command, and the description helps Claude decide when to load it automatically.Create ~/.claude/skills/explain-code/SKILL.md:Where skills live
Where you store a skill determines who can use it:| Location | Path | Applies to |
|---|---|---|
| Enterprise | See managed settings | All users in your organization |
| Personal | ~/.claude/skills/<skill-name>/SKILL.md | All your projects |
| Project | .claude/skills/<skill-name>/SKILL.md | This project only |
| Plugin | <plugin>/skills/<skill-name>/SKILL.md | Where plugin is enabled |
plugin-name:skill-name namespace, so they cannot conflict with other levels. If you have files in .claude/commands/, those work the same way, but if a skill and a command share the same name, the skill takes precedence.
Automatic discovery from nested directories
When you work with files in subdirectories, Claude Code automatically discovers skills from nested.claude/skills/ directories. For example, if you’re editing a file in packages/frontend/, Claude Code also looks for skills in packages/frontend/.claude/skills/. This supports monorepo setups where packages have their own skills.
Each skill is a directory with SKILL.md as the entrypoint:
SKILL.md contains the main instructions and is required. Other files are optional and let you build more powerful skills: templates for Claude to fill in, example outputs showing the expected format, scripts Claude can execute, or detailed reference documentation. Reference these files from your SKILL.md so Claude knows what they contain and when to load them. See Add supporting files for more details.
Files in
.claude/commands/ still work and support the same frontmatter. Skills are recommended since they support additional features like supporting files.Configure skills
Skills are configured through YAML frontmatter at the top ofSKILL.md and the markdown content that follows.
Types of skill content
Skill files can contain any instructions, but thinking about how you want to invoke them helps guide what to include: Reference content adds knowledge Claude applies to your current work. Conventions, patterns, style guides, domain knowledge. This content runs inline so Claude can use it alongside your conversation context./skill-name rather than letting Claude decide when to run them. Add disable-model-invocation: true to prevent Claude from triggering it automatically.
SKILL.md can contain anything, but thinking through how you want the skill invoked (by you, by Claude, or both) and where you want it to run (inline or in a subagent) helps guide what to include. For complex skills, you can also add supporting files to keep the main skill focused.
Frontmatter reference
Beyond the markdown content, you can configure skill behavior using YAML frontmatter fields between--- markers at the top of your SKILL.md file:
description is recommended so Claude knows when to use the skill.
| Field | Required | Description |
|---|---|---|
name | No | Display name for the skill. If omitted, uses the directory name. Lowercase letters, numbers, and hyphens only (max 64 characters). |
description | Recommended | What the skill does and when to use it. Claude uses this to decide when to apply the skill. If omitted, uses the first paragraph of markdown content. |
argument-hint | No | Hint shown during autocomplete to indicate expected arguments. Example: [issue-number] or [filename] [format]. |
disable-model-invocation | No | Set to true to prevent Claude from automatically loading this skill. Use for workflows you want to trigger manually with /name. Default: false. |
user-invocable | No | Set to false to hide from the / menu. Use for background knowledge users shouldn’t invoke directly. Default: true. |
allowed-tools | No | Tools Claude can use without asking permission when this skill is active. |
model | No | Model to use when this skill is active. |
context | No | Set to fork to run in a forked subagent context. |
agent | No | Which subagent type to use when context: fork is set. |
hooks | No | Hooks scoped to this skill’s lifecycle. See Hooks in skills and agents for configuration format. |
Available string substitutions
Skills support string substitution for dynamic values in the skill content:| Variable | Description |
|---|---|
$ARGUMENTS | All arguments passed when invoking the skill. If $ARGUMENTS is not present in the content, arguments are appended as ARGUMENTS: <value>. |
$ARGUMENTS[N] | Access a specific argument by 0-based index, such as $ARGUMENTS[0] for the first argument. |
$N | Shorthand for $ARGUMENTS[N], such as $0 for the first argument or $1 for the second. |
${CLAUDE_SESSION_ID} | The current session ID. Useful for logging, creating session-specific files, or correlating skill output with sessions. |
Add supporting files
Skills can include multiple files in their directory. This keepsSKILL.md focused on the essentials while letting Claude access detailed reference material only when needed. Large reference docs, API specifications, or example collections don’t need to load into context every time the skill runs.
SKILL.md so Claude knows what each file contains and when to load it:
Control who invokes a skill
By default, both you and Claude can invoke any skill. You can type/skill-name to invoke it directly, and Claude can load it automatically when relevant to your conversation. Two frontmatter fields let you restrict this:
-
disable-model-invocation: true: Only you can invoke the skill. Use this for workflows with side effects or that you want to control timing, like/commit,/deploy, or/send-slack-message. You don’t want Claude deciding to deploy because your code looks ready. -
user-invocable: false: Only Claude can invoke the skill. Use this for background knowledge that isn’t actionable as a command. Alegacy-system-contextskill explains how an old system works. Claude should know this when relevant, but/legacy-system-contextisn’t a meaningful action for users to take.
disable-model-invocation: true field prevents Claude from running it automatically:
| Frontmatter | You can invoke | Claude can invoke | When loaded into context |
|---|---|---|---|
| (default) | Yes | Yes | Description always in context, full skill loads when invoked |
disable-model-invocation: true | Yes | No | Description not in context, full skill loads when you invoke |
user-invocable: false | No | Yes | Description always in context, full skill loads when invoked |
In a regular session, skill descriptions are loaded into context so Claude knows what’s available, but full skill content only loads when invoked. Subagents with preloaded skills work differently: the full skill content is injected at startup.
Restrict tool access
Use theallowed-tools field to limit which tools Claude can use when a skill is active. This skill creates a read-only mode where Claude can explore files but not modify them:
Pass arguments to skills
Both you and Claude can pass arguments when invoking a skill. Arguments are available via the$ARGUMENTS placeholder.
This skill fixes a GitHub issue by number. The $ARGUMENTS placeholder gets replaced with whatever follows the skill name:
/fix-issue 123, Claude receives “Fix GitHub issue 123 following our coding standards…”
If you invoke a skill with arguments but the skill doesn’t include $ARGUMENTS, Claude Code appends ARGUMENTS: <your input> to the end of the skill content so Claude still sees what you typed.
To access individual arguments by position, use $ARGUMENTS[N] or the shorter $N:
/migrate-component SearchBar React Vue replaces $ARGUMENTS[0] with SearchBar, $ARGUMENTS[1] with React, and $ARGUMENTS[2] with Vue. The same skill using the $N shorthand:
Advanced patterns
Inject dynamic context
The!command“ syntax runs shell commands before the skill content is sent to Claude. The command output replaces the placeholder, so Claude receives actual data, not the command itself.
This skill summarizes a pull request by fetching live PR data with the GitHub CLI. The !gh pr diff“ and other commands run first, and their output gets inserted into the prompt:
- Each
!command“ executes immediately (before Claude sees anything) - The output replaces the placeholder in the skill content
- Claude receives the fully-rendered prompt with actual PR data
Run skills in a subagent
Addcontext: fork to your frontmatter when you want a skill to run in isolation. The skill content becomes the prompt that drives the subagent. It won’t have access to your conversation history.
Skills and subagents work together in two directions:
| Approach | System prompt | Task | Also loads |
|---|---|---|---|
Skill with context: fork | From agent type (Explore, Plan, etc.) | SKILL.md content | CLAUDE.md |
Subagent with skills field | Subagent’s markdown body | Claude’s delegation message | Preloaded skills + CLAUDE.md |
context: fork, you write the task in your skill and pick an agent type to execute it. For the inverse (defining a custom subagent that uses skills as reference material), see Subagents.
Example: Research skill using Explore agent
This skill runs research in a forked Explore agent. The skill content becomes the task, and the agent provides read-only tools optimized for codebase exploration:- A new isolated context is created
- The subagent receives the skill content as its prompt (“Research $ARGUMENTS thoroughly…”)
- The
agentfield determines the execution environment (model, tools, and permissions) - Results are summarized and returned to your main conversation
agent field specifies which subagent configuration to use. Options include built-in agents (Explore, Plan, general-purpose) or any custom subagent from .claude/agents/. If omitted, uses general-purpose.
Restrict Claude’s skill access
By default, Claude can invoke any skill that doesn’t havedisable-model-invocation: true set. Skills that define allowed-tools grant Claude access to those tools without per-use approval when the skill is active. Your permission settings still govern baseline approval behavior for all other tools. Built-in commands like /compact and /init are not available through the Skill tool.
Three ways to control which skills Claude can invoke:
Disable all skills by denying the Skill tool in /permissions:
Skill(name) for exact match, Skill(name *) for prefix match with any arguments.
Hide individual skills by adding disable-model-invocation: true to their frontmatter. This removes the skill from Claude’s context entirely.
The
user-invocable field only controls menu visibility, not Skill tool access. Use disable-model-invocation: true to block programmatic invocation.Share skills
Skills can be distributed at different scopes depending on your audience:- Project skills: Commit
.claude/skills/to version control - Plugins: Create a
skills/directory in your plugin - Managed: Deploy organization-wide through managed settings
Generate visual output
Skills can bundle and run scripts in any language, giving Claude capabilities beyond what’s possible in a single prompt. One powerful pattern is generating visual output: interactive HTML files that open in your browser for exploring data, debugging, or creating reports. This example creates a codebase explorer: an interactive tree view where you can expand and collapse directories, see file sizes at a glance, and identify file types by color. Create the Skill directory:~/.claude/skills/codebase-visualizer/SKILL.md. The description tells Claude when to activate this Skill, and the instructions tell Claude to run the bundled script:
~/.claude/skills/codebase-visualizer/scripts/visualize.py. This script scans a directory tree and generates a self-contained HTML file with:
- A summary sidebar showing file count, directory count, total size, and number of file types
- A bar chart breaking down the codebase by file type (top 8 by size)
- A collapsible tree where you can expand and collapse directories, with color-coded file type indicators
codebase-map.html, and opens it in your browser.
This pattern works for any visual output: dependency graphs, test coverage reports, API documentation, or database schema visualizations. The bundled script does the heavy lifting while Claude handles orchestration.
Troubleshooting
Skill not triggering
If Claude doesn’t use your skill when expected:- Check the description includes keywords users would naturally say
- Verify the skill appears in
What skills are available? - Try rephrasing your request to match the description more closely
- Invoke it directly with
/skill-nameif the skill is user-invocable
Skill triggers too often
If Claude uses your skill when you don’t want it:- Make the description more specific
- Add
disable-model-invocation: trueif you only want manual invocation
Claude doesn’t see all my skills
Skill descriptions are loaded into context so Claude knows what’s available. If you have many skills, they may exceed the character budget (default 15,000 characters). Run/context to check for a warning about excluded skills.
To increase the limit, set the SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable.
Related resources
- Subagents: delegate tasks to specialized agents
- Plugins: package and distribute skills with other extensions
- Hooks: automate workflows around tool events
- Memory: manage CLAUDE.md files for persistent context
- Interactive mode: built-in commands and shortcuts
- Permissions: control tool and skill access