Claude Code custom slash commands and skills (SKILL.md)
How do I create custom slash commands and skills in Claude Code?
Create a SKILL.md file in .claude/skills/SKILL-NAME/ for one project, or in ~/.claude/skills/SKILL-NAME/ for all your projects. You run it with /skill-name, and Claude can also load it on its own when your request matches its description. Custom commands have been merged into skills, so existing .claude/commands/*.md files still work and create the same kind of /name command.
Compare: Agent Skills (SKILL.md) in every AI coding agent →
Compare: custom slash commands in every AI coding agent →
Where skills live and how commands relate
- Personal: ~/.claude/skills/SKILL-NAME/SKILL.md loads in all your projects on this machine.
- Project: .claude/skills/SKILL-NAME/SKILL.md loads in sessions in this repository. Commit it so your team gets it too.
- Plugin: PLUGIN/skills/SKILL-NAME/SKILL.md is invoked as /plugin-name:skill-name.
- Legacy commands: .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy. A file at .claude/commands/frontend/component.md becomes /frontend:component.
- If a skill and a .claude/commands/ file share a name, the skill wins. With the same name at more than one level, enterprise beats personal, and personal beats project.
Command files accept the same frontmatter as skills except name and paths. For new work, use skills, since they also support a folder of supporting files.
Frontmatter fields
Frontmatter is YAML between --- markers at the top of SKILL.md. Every field is optional, but description is recommended so Claude knows when to use the skill. Unknown fields are ignored.
- name: the command name shown in the / menu. Defaults to the directory name.
- description: what the skill does and when to use it. If omitted, Claude uses the first non-empty line of the content.
- when_to_use: extra trigger context appended to the description.
- argument-hint and arguments: an autocomplete hint, and named positional arguments.
- disable-model-invocation: true means only you can invoke the skill.
- user-invocable: false means only Claude can invoke it.
- allowed-tools and disallowed-tools: tools pre-approved for, or removed from, the turn that invokes the skill.
- Also available: model, effort, context: fork, agent, hooks, paths and more; see the official reference table.
.claude/skills/deploy/SKILL.md
--- name: deploy description: Deploy the application to production disable-model-invocation: true --- Deploy $ARGUMENTS to production: 1. Run the test suite 2. Build the application 3. Push to the deployment target 4. Verify the deployment succeeded
Passing arguments
Whatever you type after the skill name replaces $ARGUMENTS. Use $ARGUMENTS[N] or the shorthand $N (counting from 0) for single positional arguments. Wrap a multi-word value in quotes to pass it as one argument. If no placeholder receives your input, Claude Code appends it to the end of the skill content.
.claude/skills/migrate-component/SKILL.md
--- name: migrate-component description: Migrate a component from one language to another argument-hint: [component] [from] [to] --- Migrate the $0 component from $1 to $2. Preserve all existing behavior and tests.
Invocation
/migrate-component SearchBar JavaScript TypeScript
When Claude invokes a skill on its own
By default both you and Claude can invoke any skill. Start your message with /skill-name to run it directly. Skill descriptions stay in context so Claude can load the full skill when your request matches; the full content only loads when the skill is invoked.
- disable-model-invocation: true keeps the description out of context, so Claude can't invoke it on its own. Use this for actions with side effects, like deploys or commits.
- user-invocable: false hides the skill from the / menu but still lets Claude load it as background knowledge.
- paths limits automatic loading to when Claude works with files matching the glob patterns.
- If a skill never triggers, add the words people would naturally say to its description, or call it directly with /skill-name.
Sources
More Claude Code guides
- How to allow Claude Code to run all commands: permission modes, allow rules and skip permissions
- Claude Code permissions: allow, ask and deny rules, rule syntax and allowed tools
- Claude Code telemetry and data retention: what is sent and how to turn it off
- CLAUDE.md: where it goes, how it loads, and how it works with AGENTS.md
- Claude Code hooks: all events, exit codes, PreToolUse and PermissionRequest JSON, examples
- Claude Code subagents: create one, limit its tools, and call it
- Add MCP servers to Claude Code (claude mcp add, .mcp.json, scopes)
- Claude Code settings.json: file locations, precedence, and key settings
- Claude Code plugins and marketplaces: install, create, and share
- Claude Code headless mode: claude -p, --output-format json, --bare and CI flags
- Claude Code statusline: custom status bar in settings.json with context %, cost and git branch
- Claude Code /model: switch models, aliases (opus, sonnet, haiku, opusplan), ANTHROPIC_MODEL and effort
- Claude Code /cost and /usage: check token spend, usage limits and reduce costs
- Claude Code VS Code extension: install, shortcuts, settings and /ide (works in Cursor too)
- MCP 2026-07-28 Migration Guide: Stateless Protocol, No Sessions, server/discover, MRTR, and SDK v2 Upgrade
- Subagents and Custom Agents Compared: Claude Code vs Codex vs Cursor vs Gemini CLI vs GitHub Copilot (2026)
- Allow all commands in any AI coding agent: Cursor, Claude Code, Codex, Gemini CLI, Copilot CLI and 7 more (2026)
- How to deploy a remote MCP server (Streamable HTTP): Cloudflare Workers, Vercel, Railway and more (2026)
- Claude Code sandbox: /sandbox, sandbox.enabled, allowedDomains, excludedCommands and strict mode
Reviewed Oct 18, 2026. Settings change often; the linked vendor docs are the source of truth.
Built an MCP server? Get it listed everywhere →
Shipping an Android app? Google Play needs 12 testers for 14 days first. Get them with Tester Exchange →