Claude Code custom slash commands: how to create them (with examples)

Originally published on Homingo Learn.

Custom slash commands in Claude Code turn a prompt you type every day into a one-word command, with arguments and live project context filled in before Claude reads it.

Custom commands and skills: the same thing now

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 behave the same way; existing command files keep working. Claude can also run either one by itself when its description matches the task, unless you set disable-model-invocation: true. The single-file command is the quickest to write. Choose the skill folder when the command needs reference files or scripts next to it (see how to write a SKILL.md). If both exist with the same name, the skill wins.

How to create a custom slash command (.claude/commands)

The file name becomes the command name. Subfolders become a namespace: .claude/commands/video/qa.md is /video:qa. Commit .claude/commands/ to share commands with the team; personal ones go in your home folder as skills (~/.claude/skills/<name>/SKILL.md).

.claude/commands/explain-error.md

---
description: "Explain an error message and propose the smallest fix"
argument-hint: "[error text]"
---

Explain this error in two sentences, find where it comes from in this repository,
and propose the smallest change that fixes it. Do not edit files until I agree.

Error: $ARGUMENTS

Type /explain-error TypeError: cannot read properties of undefined and everything after the command name replaces $ARGUMENTS. If a command has no placeholder, Claude Code appends the arguments at the end as ARGUMENTS: ....

Arguments: $ARGUMENTS, $0 and named arguments

• $ARGUMENTS: everything typed after the command.
• $0, $1 … (or $ARGUMENTS[0]): single arguments, counted from zero (older guides start at $1, so check old command files). Quote an argument that has spaces: /new-episode ep05 "a lighthouse keeper hears knocking" gives $0 = ep05 and $1 = the whole premise.
• Named arguments: list them in the frontmatter (arguments: [id, premise]) and write $id and $premise in the body. Easier to read than positions.
• A literal dollar sign needs a backslash: \$1.00.

.claude/commands/new-episode.md

---
description: Start a new episode spec from the template
argument-hint: "[episode-id] [premise]"
arguments: [id, premise]
---

Create episodes/$id/spec.json from episodes/_template/spec.json.

Premise: $premise

1. Write the hook shot first: frame 0 must show a situation that raises a question.
2. Fill the remaining shots so each one adds information or raises a new question.
3. Write one caption per shot, at most 7 words.
4. Run `npm test` and fix every spec error before you stop.

Run shell commands in a slash command (! syntax)

Write ! followed by a command in backticks, at the start of a line or after a space: the command runs before the prompt is sent, and its output replaces the placeholder. For several commands, use a fenced code block whose opening fence is followed by !. Claude reads the current state instead of spending turns finding it. These commands are checked against your permission rules and do not prompt, so pre-approve them with allowed-tools; if one fails, the whole command is aborted.

.claude/commands/review-changes.md

---
description: Review my uncommitted changes against the project rules
allowed-tools: Bash(git status *) Bash(git diff *)
---

## Changed files
!`git status --short`

## Diff
!`git diff HEAD`

Review the diff above against CLAUDE.md. List every problem as
file:line, what is wrong, and the fix. Nothing else.

New untracked files show in git status but not in the diff; run git add -N on them first if the review should read them. In a repository with no commits yet, use git diff instead of git diff HEAD.

Frontmatter fields worth knowing

• description: shown in the / menu. Without it, the first line of the body is used.
• argument-hint: the hint shown while you type, such as [episode-id].
• allowed-tools: tools Claude may use without asking during this command, for example Bash(ffprobe *). Deny rules still win.
• model and effort: run a routine command on a smaller model or lower effort.
• disable-model-invocation: true: only you can trigger it. Use it for anything with side effects, such as a deploy or a publish.
• user-invocable: false: the opposite; hidden from the / menu, for background knowledge only Claude should load.
• context: fork (with agent to pick the type): run the command in a subagent with its own context.

Field names must match exactly: Claude Code ignores an unknown field without an error, so a typo silently does nothing.

.claude/commands/video/qa.md (run as /video:qa ep05)

---
description: Technical QA of a rendered episode before posting
argument-hint: "[episode-id]"
allowed-tools: Bash(ffprobe *)
model: haiku
disable-model-invocation: true
---

Run ffprobe on out/$0.mp4 and report width, height, frame rate, duration and
whether an audio stream exists. PASS only if it is 1080x1920, r_frame_rate is exactly
30/1, and it is between 15 and 90 seconds long. One line per check, then PASS or FAIL.

Commands, skills, subagents or hooks?

• A command when you start the job yourself and the prompt is the same each time.
• A skill when the method is longer or needs files beside it.
• A subagent when the work would fill your main conversation with file reads, or needs a reviewer that did not write it. Define one first (a file-qa agent, say), then the command can simply say “use the file-qa subagent on out/$0.mp4”, or set context: fork to run the command itself in a subagent.
• A hook when something must happen every time, with no prompt at all.

Command not showing up?

• Type / and look for the name: the menu lists every command, and every skill not marked user-invocable: false.
• Check the folder: .claude/commands/ in the project you started Claude in (or a skill folder with a SKILL.md inside).
• Check for a clash: a skill with the same name wins over a command file.
• Check the frontmatter: it must open and close with --- and be valid YAML.

Common mistakes

• A shell line missing from allowed-tools. Add the exact pattern.
• Unquoted multi-word arguments. Without quotes, each word is its own $N.
• Side effects Claude can trigger. Add disable-model-invocation: true to deploys and publishes.
• Rules copied into every command. Shared rules belong in CLAUDE.md; the command keeps only its own task.

If you make short vertical videos with Claude Code, the skill below packages a complete spec-first workflow like the one behind the episode commands above.

Fields and syntax follow the official skills and commands documentation as of November 2026.

Animated horror reels skill: Our whole playbook as a Claude Code agent skill: the hook-first story method, the episode spec template, the camera, light and grade system with a palette builder, a render-ready Remotion starter and the QA checks before you post. Make reels like ours. See the skill

---

Disclosure: this guide is by Homingo, the team behind the skill linked above. Everything in it works without it.