Claude Code Slash Commands — How to Create Custom Skills

6 min read · Claude Code configuration · Updated April 2026

Claude Code lets you define custom slash commands — type /debug, /code-review, or /plan and Claude runs a predefined workflow. Anthropic has merged the earlier .claude/commands/ flat-file format and the newer .claude/skills/ directory format into one system, so a slash command is a skill. You define the workflow once, install it, and reuse it across every project.

Where Claude Code looks for slash commands

Claude Code checks four scopes, higher-priority scopes winning when names overlap:

• Enterprise — managed settings deployed by IT (organisation-wide)
• Personal — ~/.claude/skills/<name>/SKILL.md or the legacy ~/.claude/commands/<name>.md, available in every project. Anthropic's docs call this scope "Personal"; older guides may call it "User" — they refer to the same location.
• Project — .claude/skills/<name>/SKILL.md or .claude/commands/<name>.md inside the repo, committed with your team
• Plugin — <plugin>/skills/<name>/SKILL.md, namespaced as plugin-name:skill-name so plugin skills cannot collide with the rest

Precedence runs enterprise > personal > project. If a skill and a legacy command share a name at the same scope, the skill wins. Adding, editing, or removing a skill inside a watched directory takes effect during the current session without restarting; creating a brand-new top-level skills directory requires a Claude Code restart so the filesystem watcher can pick it up.

Creating your first slash command

The skill directory form is the recommended shape. Create the directory and a SKILL.md inside it — the directory name becomes the command:

mkdir -p ~/.claude/skills/code-review
$EDITOR ~/.claude/skills/code-review/SKILL.md

Then put this inside SKILL.md:

---
name: code-review
description: Review staged changes for security issues, bugs, and quality problems.
---

Review the current code changes for:

**Security (check first)**
- SQL injection, XSS, CSRF, path traversal
- Hardcoded secrets or API keys
- Improper input validation

**Correctness**
- Logic errors and edge cases not handled
- Null/undefined handling gaps
- Async misuse or race conditions

**Quality**
- Functions doing more than one thing
- Misleading variable or function names

Output format:
🔴 CRITICAL — [issue] at [file:line] — [fix]
🟡 WARNING — [issue] at [file:line] — [fix]
🔵 NOTE — [suggestion]

End with: APPROVE / APPROVE WITH FIXES / BLOCK

Now type /code-review in any Claude Code session and Claude runs this exact workflow.

Useful frontmatter fields

All frontmatter is optional, but a good description: is what lets Claude decide to invoke a skill automatically when it matches your request. Fields worth knowing:

• description: — one or two sentences covering what the skill does and when to use it
• when_to_use: — extra trigger phrases or example requests; appended to description in the skill listing so Claude matches the skill to your wording
• disable-model-invocation: true — only you can invoke; Claude never auto-triggers it (use for /deploy, /commit, anything with side effects)
• user-invocable: false — hide the skill from the / menu (useful for background knowledge like legacy-system-context). Menu visibility only — it does not block programmatic invocation via the Skill tool. To actually restrict Claude from loading a skill, use disable-model-invocation: true or a Skill(name) deny rule in your /permissions settings.
• allowed-tools: — list of tools (e.g. Bash(git commit *)) that don't need per-use approval while the skill is active
• argument-hint: — hint shown during autocomplete (e.g. [issue-number])
• context: fork — run the skill inside a subagent with its own isolated context
• agent: — which subagent type to use when context: fork is set (e.g. Explore, Plan, general-purpose, or a custom type from .claude/agents/)
• model: and effort: — override the session model and reasoning effort for this skill only
• paths: — glob patterns that auto-load the skill when you're working on matching files

The allowed-tools list composes with your settings.json permissions: tools you pre-approve here are granted only while the skill is active. Everything else still goes through your active permission settings across all four scopes — managed, personal (~/.claude/settings.json), project (.claude/settings.json), and local (.claude/settings.local.json) — following Claude Code's precedence rules (managed wins, then CLI args, then local, then project, then personal).

Legacy flat-file form

If you prefer the shorter .claude/commands/<name>.md form, it still works and supports the same frontmatter fields — no directory or SKILL.md needed. Skills just give you a folder for supporting files and a few extra features.

10 slash commands worth having

Tips for writing effective skills

Be specific about output format

Vague instructions get vague results. If you want a bulleted list of findings with severity ratings, describe exactly that format in the skill body.

Include what NOT to do

A /refactor skill that doesn't say "zero behavior change" will have Claude accidentally changing logic. Constraints are as important as instructions.

Keep each skill to one job

A /review-and-fix skill that both reviews and applies fixes is harder to control than /code-review followed by targeted edits. Single responsibility applies to skills too.

Frequently asked questions

Using GitHub Copilot? Copilot's closest equivalent to slash commands is reusable .prompt.md prompt files — see the Copilot Customization Starter Kit for 5 ready-made prompt files (code review, debug, refactor, write-tests, security-check).