How to Add Custom Slash Commands to Claude Code (Arguments + Frontmatter)

Write project-specific slash commands that run a prepared instruction with one keystroke, pass arguments, and pre-approve tools with frontmatter.

7 minBeginner

Visit Claude Code

If you type the same prompt every day — run the test suite, write a changelog entry, deploy to staging — you can turn it into a slash command that lives in your repo alongside the code. Everyone on the team gets the same command automatically when they pull.

What you need

Claude Code installed and authenticated
A git repo with a .claude/ folder (or create one)
About 5 minutes

Step 1: Create the commands folder

bash

$mkdir -p .claude/commands

One markdown file per command goes in here

Step 2: Write a command file

Create a Markdown file. The filename becomes the command name. The file content is the instruction Claude runs when you type the command. Keep it specific: vague instructions produce vague output.

.claude/commands/changelog.md

Read the git diff since the last tag and write a changelog entry in CHANGELOG.md.
Format: ## [version] - [today's date], then a bullet list grouped by Added, Changed, Fixed.
Do not include internal refactors or test changes.

Step 3: Pass arguments

Use $ARGUMENTS to drop everything typed after the command into the prompt. For separate values, use positional placeholders: $1 is the first argument, $2 the second. This command takes an issue number and a target branch.

.claude/commands/fix-issue.md

Fix issue #$1 and open a pull request against the $2 branch.
Read the issue, reproduce it, write a failing test, then make it pass.
Keep the change minimal and describe it in the PR body.

Claude Code

$/fix-issue 412 main

Reading issue #412... reproducing... writing test... opening PR against main.

Step 4: Add frontmatter (optional)

A YAML frontmatter block at the top of the file tunes how the command behaves. The most useful fields are argument-hint (shown in autocomplete), allowed-tools (pre-approve tools so the command runs without permission prompts), and model (run this command on a specific model).

.claude/commands/review-security.md

---
argument-hint: [file]
allowed-tools: Read, Grep
description: Scan a file for auth, injection, and secret-leaking issues
---
Scan $ARGUMENTS for authentication, injection, and secret-leaking issues.
Group findings by severity. Suggest a concrete fix for each.
Do not edit any files; only report.

Commands are now skills

In current versions, custom commands have merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and support the same frontmatter. Skills add a folder for supporting files and can let Claude load them automatically. Your existing .claude/commands/ files keep working with no changes.

Useful command ideas

/deploy — run your deploy script and summarize what changed
/review-security — scan the current diff for auth, injection, and secret-leaking issues
/docstring — add a one-line docstring to every exported function in the current file
/pr-description — write a pull request description from the current branch diff
/todos — list every TODO comment in the repo with file and line number

Commit the commands folder

Add .claude/commands/ (or .claude/skills/) to git so the whole team inherits your commands on pull. Only gitignore .claude/ if the folder also holds secrets; the commands themselves have no credentials.

FAQ

Where do personal commands go?

Put them in ~/.claude/commands/ (or ~/.claude/skills/<name>/SKILL.md) instead of the project folder. Personal commands follow you across every project and are not committed to any repo.

How do I pass multiple arguments?

Use positional placeholders. $1 is the first word after the command, $2 the second, and so on. $ARGUMENTS holds everything at once. Declare an argument-hint in frontmatter so autocomplete shows what the command expects.