Skills and Commands

A skill is a folder with a SKILL.md file. It teaches Claude how to do one task. A slash command is a short action that you type, such as /compact or /model. A skill also gives you a slash command. For example, .claude/skills/deploy/SKILL.md gives you /deploy. The older .claude/commands/ folder still works and acts like a skill.

Example

This skill makes a /summarize-diff command. Only you can start it.

.claude/skills/summarize-diff/SKILL.md

---
description: Summarize the uncommitted changes in plain words.
argument-hint: "[focus]"
disable-model-invocation: true
allowed-tools: Bash(git diff *)
---

Run `git diff` and summarize the changes.
Focus on: $ARGUMENTS

Type /summarize-diff tests in the prompt. $ARGUMENTS becomes tests.

Skill Locations

When two skills share a name, the one in the higher place wins.

Place	Status	What it holds	Notes
Enterprise <managed dir>/.claude/skills/<name>/SKILL.md	Documented: An official docs page names this item.	Skills for all users on a machine.	Wins over personal and project skills of the same name.
Personal ~/.claude/skills/<name>/SKILL.md	Documented: An official docs page names this item.	Skills for all your projects.	Wins over project skills.
Project .claude/skills/<name>/SKILL.md	Documented: An official docs page names this item.	Skills for one repository.	Loaded from the start folder and each parent up to the repository root. A linked worktree with no .claude/skills uses the main checkout (2.1.277 or later).
Nested .claude/skills/ below the start folder	Documented: An official docs page names this item.	Skills for a sub-project.	Loads when Claude first reads or edits a file there, or after /add-dir <subdir>. On a clash the nested skill is /apps/web:deploy.
--add-dir or /add-dir folder	Documented: An official docs page names this item.	Skills, commands/, and agents/ of another folder.	permissions.additionalDirectories grants file access only and loads none of these. Needs the project setting source. Since 2.1.309, when another skill already has its name, the skill is offered as <folder>:<name> (v2.1.309 release notes).
Plugin skills/<name>/SKILL.md	Documented: An official docs page names this item.	Skills of a plugin.	The command name is /<plugin>:<skill>. A plugin root SKILL.md with no skills/ folder loads as one skill.
Synced skills ~/.claude/skills/synced/	Documented: An official docs page names this item.	Skills turned on in your claude.ai account.	Downloaded in the background (2.1.273 or later). Checked about every 10 minutes while active and every 40 minutes while idle. Never uploaded. The name anthropic-skills is reserved. Needs a claude.ai sign-in. Not in bare mode or --safe-mode.
Trash ~/.claude/skills/.trash/	Documented: An official docs page names this item.	Removed synced skills.	A sweep removes entries after 30 days by default.
<name>@skills-dir plugin	Documented: An official docs page names this item.	A plugin made by claude plugin init in ~/.claude/skills/<name>/.	Loads with no install step. The marketplace name skills-dir is reserved.
MCP-served skill	Undocumented: Only the program shows this item. It can change without notice.	A skill that an MCP server serves.	Claude Code reads supporting files through MCP resources. The origin tag is mcp.
Skill loadedFrom values	Undocumented: Only the program shows this item. It can change without notice.	Internal origin tags.	Found: skills, commands_DEPRECATED, plugin, bundled, syncedSkills, mcp, memoryStore.

Name Resolution

Rule	Status	What it does	Notes
Clash order	Documented: An official docs page names this item.	Picks the skill that /name runs.	Enterprise, then personal, then project. A skill replaces a bundled skill or a built-in command of the same name, but not its aliases. A skill wins over a .claude/commands/ file.
Name from layout	Documented: An official docs page names this item.	Sets the command name.	.claude/commands/frontend/component.md is /frontend:component. Frontmatter name sets the name of a skill folder. A plugin name sets the last part.
Refused characters	Documented: An official docs page names this item.	Protects the / menu.	Refused: zero-width, control, private-use, bidirectional, odd blank characters, <, and >. The debug log tag is [names].
Name length	Undocumented: Only the program shows this item. It can change without notice.	Caps a frontmatter name.	Claude Code ignores a name over 256 characters. It gives a warning.

Custom Commands

Item	Status	What it does	Notes
.claude/commands/<name>.md and ~/.claude/commands/	Documented: An official docs page names this item.	The old form of a skill.	Accepts the same frontmatter except name and paths. Subfolders become : parts.
Plugin commands map	Documented: An official docs page names this item.	Commands from a plugin manifest.	Keys: source or content, description, argumentHint, model, allowedTools.

Loading and Controls

Item	Status	What it does	Notes
Live change detection	Documented: An official docs page names this item.	Reloads SKILL.md text when it changes.	Not in bare mode. A new top-level skills folder needs /reload-skills. Changes to hooks/, .mcp.json, agents/, and output-styles/ need /reload-plugins.
Skill listing budget	Documented: An official docs page names this item.	Caps how much skill text goes into context.	1 percent of the window (skillListingBudgetFraction), counted at 4 characters per token for Claude 3 to 4.6 models and 3 for newer ones (the program). So Opus 5.5 with a 200,000-token window gets 6,000 characters. Each entry is cut at 1,536 characters (skillListingMaxDescChars). When the listing is over the budget, the program drops descriptions. It leaves only the names. The env var SLASH_COMMAND_TOOL_CHAR_BUDGET sets a fixed count.
--disable-slash-commands	Documented: An official docs page names this item.	Turns off all skills and commands.	A CLI flag. Its help text is "Disable all skills and commands" since 2.1.304.
Setting skillOverrides	Documented: An official docs page names this item.	Sets the visibility of each skill.	Values: on, name-only, user-invocable-only, off. Plugin skills are not affected.
Setting disableBundledSkills	Documented: An official docs page names this item.	Removes bundled skills.	Same as CLAUDE_CODE_DISABLE_BUNDLED_SKILLS=1. Built-in commands stay. See Bundled Skills.
Setting disableSkillShellExecution	Documented: An official docs page names this item.	Disables !`cmd` injection.	See Substitutions.
CLAUDE_CODE_DISABLE_POLICY_SKILLS, CLAUDE_CODE_DISABLE_CLAUDE_API_SKILL, CLAUDE_CODE_DISABLE_CLAUDE_CODE_SKILL, CLAUDE_CODE_SKILL_PROPOSALS, CLAUDE_CODE_SKILL_ATTRIBUTION	Documented: An official docs page names this item.	Skill-related environment variables.	CLAUDE_CODE_DISABLE_CLAUDE_API_SKILL removes the claude-api skill (checked). CLAUDE_CODE_DISABLE_POLICY_SKILLS skips skills from the managed folder (checked: the managed skill was listed, and the variable removed it). CLAUDE_CODE_SKILL_PROPOSALS enables skill proposals in cloud sessions. It has no visible effect locally. Claude Code removes CLAUDE_CODE_SKILL_ATTRIBUTION from the env of subprocesses. CLAUDE_CODE_DISABLE_CLAUDE_CODE_SKILL disables the claude-code skill, which a plain -p run does not list. See Environment Variables.

How It Works

Only the skill description sits in context until the skill runs. After that the full text stays in the conversation. See Substitutions for what compaction keeps.

Pages in This Section

Page	Content
Skill Frontmatter	Every SKILL.md key.
Substitutions	$ARGUMENTS, variables, shell injection, and who can invoke a skill.
Bundled Skills	Skills that ship inside Claude Code.
Slash Commands	Every built-in slash command.

Related Pages

• Hooks: skills can carry hooks in frontmatter.
• Subagent Runtime: context: fork runs a skill in a subagent.
• Subagent Frontmatter: the skills key preloads skills into an agent.
• Environment Variables: the full variable list.

Source: Extend Claude with Skills, Settings Reference, and the program (the skill loader and the loadedFrom tags).