Create your own slash commands in Claude Code with a single Markdown file
Define /review or /commit as a skill in .claude/skills/, how that differs from .claude/commands/, passing arguments with $ARGUMENTS and $1, and embedding Bash output in the prompt.
Contents
If you keep typing the same long instruction — "review this against our project rules," "write a commit message in Conventional Commits format" — that instruction is a candidate for a slash command.
In Claude Code, one Markdown file gives you your own /review or /commit. This article covers the skill form, which is the current recommendation, how it relates to the older commands form, arguments, and sharing with a team.
KEY POINT
What you will learn
- The difference between a skill (
SKILL.md) and a command (commands/*.md), and when to use each - Arguments, frontmatter options, and embedding Bash output
- Ready-to-use examples: review, commit, test generation
Two forms: skills and commands
| Form | Location | Invocation | Character |
|---|---|---|---|
| Skill | .claude/skills/<name>/SKILL.md | /<name>, or Claude loads it on its own | Can ship supporting files (scripts, templates) in the same folder |
| Command | .claude/commands/<name>.md | /<name> | One self-contained file; the older form |
The skill form is what to reach for now. Write "when to use this" in the description and Claude loads it when the situation calls for it, without you typing /name. If you only ever invoke it explicitly, both forms behave the same.
For something you want in every project, put it in ~/.claude/skills/ or ~/.claude/commands/. When a project and your user directory define the same name, they are shown with a prefix to distinguish them.
The smallest useful skill
mkdir -p .claude/skills/review.claude/skills/review/SKILL.md:
---
name: review
description: Review work-in-progress code against this project's conventions. Also use when the user says "review this".
---
Review the current git diff on these points:
1. Violations of CLAUDE.md conventions (types, naming, banned libraries)
2. Missing error handling
3. Whether tests were added or updated
4. Security concerns (input validation, hardcoded secrets)
Classify each finding as critical, suggested or minor, with the file name and line number.
For a point with nothing to report, write "no issues" on one line.Save it and type /review in a session. If a newly added command doesn't show up in the list, restart the session.
用語解説
Frontmatter: the block fenced by --- at the top of the file. Besides name and description, it takes allowed-tools, argument-hint, model and others described below.
Take arguments
$ARGUMENTS is replaced by the whole argument string; $1, $2 and so on by individual whitespace-separated arguments.
.claude/skills/fix-issue/SKILL.md:
---
name: fix-issue
description: Takes a GitHub issue number, reads it, and fixes what it describes
argument-hint: <issue-number>
---
Read GitHub issue #$1 with `gh issue view $1`, then:
1. Work out the reproduction steps, and write a failing test first if one applies
2. Find the cause and fix it
3. Run the tests and report the result
4. Format the commit message as "fix: <summary> (#$1)"Invoke it as /fix-issue 123. argument-hint is the hint shown during completion.
Embed Bash output in the prompt
A line beginning with ! runs that shell command before the prompt is assembled, and its output is embedded in the instruction. Restrict what may run with allowed-tools.
.claude/skills/commit/SKILL.md:
---
name: commit
description: Build a Conventional Commits message from the staged changes and commit
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git diff:*), Bash(git commit:*)
---
## Current state
- Status: !`git status --short`
- Staged diff: !`git diff --cached`
## Instructions
From the diff above, write a Conventional Commits message (feat / fix / docs / refactor / test / chore) and commit.
Keep the first line under 50 characters, and explain *why* in the body.Because the diff is already in the instruction, Claude doesn't spend a tool call fetching it.
Frontmatter options worth knowing
| Key | Meaning |
|---|---|
name | The command name (required in a skill; defaults to the folder name) |
description | What it does; this is what Claude judges automatic loading on |
argument-hint | The argument hint shown during completion |
allowed-tools | Tools usable without a prompt inside this command |
model | The model to run this command on, for example claude-sonnet-5-5 |
Check the official documentation for exact key names and newer options.
Ship supporting files (the reason to prefer skills)
A skill folder can hold templates and scripts next to the instruction:
.claude/skills/new-component/
├── SKILL.md
├── template.tsx
└── template.test.tsxHave SKILL.md say "copy template.tsx and replace the names" and every component starts from the same scaffold. A real file as the template produces more consistent results than a long description of one in the prompt.
Operating notes
- Split the work with CLAUDE.md. Rules that always apply belong in CLAUDE.md; a specific procedure belongs in a skill. Putting everything in CLAUDE.md crowds your context — see How to write CLAUDE.md.
- To suppress automatic invocation, say in the
descriptionthat it should be used only when the user types the command explicitly. - Combine with subagents. Having a skill delegate a long review to a subagent keeps the output out of your main context — see Create subagents in Claude Code.
Summary
- A
.claude/skills/<name>/SKILL.mdfile is all it takes to get a/<name>command $ARGUMENTSand$1take arguments;!`command`embeds Bash output in the promptallowed-toolslimits what runs without a prompt inside the command- Keep always-on rules in CLAUDE.md and procedures in skills
FAQ
- Should I use a skill or a command file?
- Prefer a skill. A skill folder can ship supporting files such as templates and scripts, and a good description lets Claude load it on its own. For explicit invocation only, both behave the same.
- My new command doesn't appear in the list.
- Restart the session. Commands and skills are picked up at startup.
- How do I keep a skill from being invoked automatically?
- Write the description to say it should be used only when the user types the command explicitly. That reduces unintended automatic loading.
Questions & answers
Q. Can I reload plugins, skills and slash commands inside an open session? I enabled the plugin in settings and ran reload, but no slash commands show up.
You can. The command is /reload-plugins, and it reloads plugins, skills, agents, hooks, plugin MCP servers and plugin LSP servers together. Starting a new project is not required.
If slash commands still do not appear, the documentation names three causes.
1. The change is pending because of the prompt cache
Closing the /plugin menu makes Claude Code run /reload-plugins for you — but if the reload would invalidate the prompt cache, it warns and leaves the changes pending instead. Apply them anyway with:
/reload-plugins --forceThe same applies when the install summary said Run /reload-plugins to activate.
2. You did not type it into the session directly
/reload-plugins does run in sessions without an interactive terminal — the desktop app, the Agent SDK, and -p — as of v2.1.260. But it runs only when you type it directly into that session. Sent over a remote connection, such as Remote Control or a relayed chat message, the command declines without reloading anything. In the desktop app, type it into the prompt box yourself.
3. A stale cache
The official troubleshooting entry for plugin skills not appearing is to clear the cache:
rm -rf ~/.claude/plugins/cacheThen restart Claude Code and reinstall the plugin.
One limit to know about: in a session without an interactive terminal, the reload does not connect or disconnect plugin MCP servers. Those changes take effect in your next session. Plugins enabled on your claude.ai account sync into terminal sessions on v2.1.273 or later.
Primary sources
This article was drafted by AI from official documentation and reviewed by the site operator before publishing. Found a mistake? Let us know via the contact page.