Short answer: a custom slash command is a Markdown file whose name becomes the command: ~/.claude/commands/review.md gives you /review in every project, .claude/commands/review.md gives it to everyone in the repository. For new commands, a skill is now the better choice, because Claude can also start it on its own when the task fits.
If you type the same instructions into Claude Code every week ("review this branch, check the tests, list what would break"), that text belongs in a slash command. You write it once, and /review sends it for you.
Where does a command file go?
A command is a Markdown file. The file name is the command.
| File | Command | Who gets it |
|---|---|---|
~/.claude/commands/review.md | /review | You, in every project |
.claude/commands/review.md | /review | Everyone in the repository, once committed |
.claude/commands/db/migrate.md | /db:migrate | A subfolder becomes a namespace |
Names are lowercase with hyphens. Do not put a colon in the name yourself: the colon is how namespaces and plugins are written, so review:deep.md will not resolve to your file.
What does a first command look like?
---
description: Review the current branch and list anything that would break
argument-hint: [focus area]
---
Review the changes on this branch against main.
List bugs first, then missing tests, then risky changes.
Focus especially on: $ARGUMENTSThe body is what gets sent when you type the command. $ARGUMENTS is replaced by whatever you type after it, so /review the auth module focuses the review there. The argument-hint is shown while you type.
Which fields does a command accept?
| Field | What it does |
|---|---|
description | Shown in the slash menu |
argument-hint | Shown while you type the command |
allowed-tools | Needed if the body runs a shell command with backticks |
disallowed-tools | Removed while the command is active, restored on your next message |
model | Overrides the session model for this command |
effort | How much thinking the turn it starts gets |
disable-model-invocation | Stops Claude running it on its own; use it for anything with a side effect |
user-invocable | Off makes it something only Claude reaches for |
shell | Which shell runs the shell blocks (an exclamation mark before a backticked command) in the body |
Should you write a command or a skill?
This is the part older guides miss. Custom commands have been merged into skills: a file in commands/ and a skill with the same name both create the same slash command, and if both exist the skill wins. Existing command files keep working.
For anything new, a skill is the better choice:
- A skill is a folder (
.claude/skills/review/SKILL.md), so it can carry supporting files: a checklist, a script, a template - A skill's body is loaded only when it is used, so a long one costs nothing until then
- Claude can load a skill on its own when your request matches its description, unless you set
disable-model-invocation
A plain command file is still fine for a one-paragraph prompt you only ever type yourself.
Which should I use: a command, a skill or a subagent?
- Command: a fixed prompt you type
- Skill: a prompt plus files, that you type or Claude loads when it fits
- Subagent: a separate worker with its own context that reports back. See Claude Code subagents
Where can you check this?
Can you make one in the browser?
Config Studio for Claude Code has editors for Commands and Skills with every field above, and writes the file to the right folder for you. Its Will this name resolve? check catches a name that will never match before you need it. More on skills in Claude Code skills explained.
