Custom Slash Commands & Skills

You have already written the perfect prompt three times this week — "look at the git diff, review it for security issues, and use only read-only tools." A custom slash command is that prompt, saved to a file, replayed with /name. Nothing more mysterious than a snippet.

But a Claude Code command is richer than a text snippet, because it can carry three things a bare prompt can't:

1. Tool permissions — declare exactly which tools the command may use, so it runs without prompting you.
2. Live context — splice in the output of a shell command, or the contents of a file, at the moment you invoke it.
3. Arguments — pass values on the command line (/fix-issue 123 high) and slot them into the prompt.

The file is just Markdown — a body (the prompt Claude receives) and an optional YAML frontmatter block at the top (the configuration). That's the whole format.

The one idea to hold onto before the details: a command is a prompt you trigger by typing /name. A skill is the same file in a slightly different place that Claude can also trigger on its own when the task fits. Same content, same /name invocation — the difference is who gets to fire it. We'll return to that distinction at the end; everything in between applies to both.

There are two formats and two scopes. The format determines whether Claude can invoke it autonomously; the scope determines who can see it.

The official guidance is explicit: .claude/commands/ is the legacy format; the recommended format is .claude/skills/<name>/SKILL.md, which supports the same /name invocation plus autonomous invocation by Claude. The CLI still fully supports both, so you'll see plenty of commands/ directories in the wild.

How the name is derived:

• For a legacy command, the filename minus .md becomes the command name. .claude/commands/refactor.md → /refactor.
• For a skill, the directory name is the command name. .claude/skills/refactor/SKILL.md → /refactor. (The file inside is always literally SKILL.md.)

Project-scoped files (under ./.claude/) are checked into git, so the whole team gets them. Personal files (under ~/.claude/) follow you across every project on your machine.

Subdirectories organize, but do NOT namespace. As your library grows you'll want folders, and custom commands support them:

.claude/commands/
├── frontend/
│   ├── component.md      # Creates /component (project:frontend)
│   └── style-check.md    # Creates /style-check (project:frontend)
├── backend/
│   ├── api-test.md       # Creates /api-test (project:backend)
│   └── db-migrate.md     # Creates /db-migrate (project:backend)
└── review.md             # Creates /review (project)

Here is the gotcha that trips people up: the subdirectory appears in the command's description, but it does NOT become part of the command name. .claude/commands/backend/api-test.md is invoked as /api-test, not /backend/api-test or /backend:api-test. The backend/ folder surfaces as context in the description (handy when scanning / autocomplete) but the name comes from the filename alone. The practical consequence: folders organize, they don't disambiguate. frontend/test.md and backend/test.md both want to be /test — and collide. Keep leaf filenames unique within a scope.

The body of the file is the prompt. The optional YAML frontmatter at the top — fenced by --- lines — configures the command. Four keys matter:

A fully-configured command looks like this:

---
allowed-tools: Read, Grep, Glob
description: Run security vulnerability scan
model: claude-opus-4-7
---

Analyze the codebase for security vulnerabilities including:
- SQL injection risks
- XSS vulnerabilities
- Exposed credentials
- Insecure configurations

Two things deserve emphasis. First, allowed-tools uses permission-rule syntax, the same scoping you'd write in a permissions rule — so Bash(git status *) permits only git status ..., not arbitrary shell. Scope it tightly; a command that needs to read and diff doesn't need write access. Second, description is load-bearing for skills: it's the text Claude reads when deciding, on its own, whether this skill fits the task at hand. A vague description means a skill that never fires (or fires at the wrong time). Write it like a trigger sentence.

A static prompt is useful; a parameterized one is reusable. Custom commands support two placeholder styles, and you'll often combine them.

$ARGUMENTS — everything you type after the command name, as one string. Good when the argument is free-form:

---
argument-hint: [test-pattern]
description: Run tests with optional pattern
---

Run tests matching pattern: $ARGUMENTS

1. Detect the test framework (Jest, pytest, etc.)
2. Run the matching tests
3. If they fail, analyze, fix, and re-run to verify

Invoke with /test auth and $ARGUMENTS becomes auth.

Positional $0, $1, $2, … — individual arguments by index, split on spaces. Good when arguments have distinct roles:

---
argument-hint: [issue-number] [priority]
description: Fix a GitHub issue
---

Fix issue #$0 with priority $1.
Check the issue description and implement the necessary changes.

Invoke with /fix-issue 123 high and the prompt resolves to "Fix issue #123 with priority high." — $0 is 123, $1 is high.

The two styles answer different questions. Use $ARGUMENTS when you want the whole tail (a search query, a free-text description). Use positional when each slot means something specific and you want to phrase them differently in the prompt. The argument-hint frontmatter is purely a UX nicety — it shows the expected shape in autocomplete but enforces nothing.

The most powerful feature is injecting fresh context at invocation time, so Claude starts the task already holding the relevant state. Two mechanisms:

Backtick-bang — !`command` — runs a shell command and inlines its stdout into the prompt before Claude sees it. This is how you hand Claude the current git status or diff without it having to go fetch them:

---
allowed-tools: Bash(git add *), Bash(git status *), Bash(git commit *)
description: Create a git commit
---

## Context

- Current status: !`git status`
- Current diff: !`git diff HEAD`

## Task

Create a git commit with an appropriate message based on the changes above.

When you type /git-commit, the !`git status` and !`git diff HEAD` run first; their output is spliced into the text, and Claude receives a prompt that already contains the live diff. Note the frontmatter — for the backtick-bang commands to run without prompting, the relevant Bash(...) rules must be in allowed-tools.

@path embeds a file's contents directly into the prompt:

---
description: Review configuration files
---

Review the following configuration files for issues:
- Package config: @package.json
- TypeScript config: @tsconfig.json

Check for security issues, outdated dependencies, and misconfigurations.

Here @package.json and @tsconfig.json are replaced by the actual file contents at invocation. The distinction is worth keeping straight: ! runs a command and inlines its output; @ reads a file and inlines its text. Both happen before Claude reasons, which is exactly what makes the command feel like it already understands your situation.

Now the distinction we deferred. Mechanically, skills and commands share everything — frontmatter, arguments, interpolation. The difference is invocation authority.

• A legacy command (.claude/commands/*.md) fires only when you type /name. It's a macro you trigger by hand.
• A skill (.claude/skills/<name>/SKILL.md) can also be invoked by Claude autonomously — when a task matches the skill's description, Claude can reach for it on its own, no typing required. You can still trigger it manually with /name too.

This is why the recommended format is a skill: a well-described skill is a capability Claude discovers and applies exactly when it's relevant, instead of a command you have to remember to run.

Sometimes that autonomy is unwanted — a deploy command, a destructive cleanup, anything you want a human firmly in the loop for. To keep a skill manual-only, set disable-model-invocation: true in its frontmatter:

---
description: Tear down and rebuild the local database
disable-model-invocation: true
---

Drop the dev database, re-run all migrations, and reseed.

With that flag, the skill is still listed and still works via /db-reset, but Claude will never invoke it on its own. The decision rule is simple: make it a model-invokable skill when you'd be happy for Claude to apply it automatically; make it a command (or a skill with disable-model-invocation: true) when a human must pull the trigger.

Two commands keep you in control of your library.

/skills lists every skill available in the session, with the tokens each one costs to keep loaded. Because skill definitions consume context, this is also a budgeting tool:

• Press t to sort by tokens — surface the heaviest skills, the ones worth trimming or making more on-demand.
• Press Space to hide a skill you don't want loaded in this session.

Use /skills whenever a command isn't showing up (did the file land in the right place?) or when /context says skills are eating more of your window than you expected.

/reload-plugins hot-reloads all active plugins to apply pending changes without restarting Claude Code — it reports counts for each reloaded component and flags any load errors. This closes the authoring loop: edit a skill file, run /reload-plugins, and try the updated /name immediately, no session restart, no lost context.

Together these two make iterating on a command tight: write the file, /reload-plugins, test, adjust, repeat — and use /skills t to keep the whole set lean.