How to Save Reusable Prompts as Claude Code Slash Commands

To save a reusable prompt as a Claude Code slash command, place a Markdown file at ~/.claude/commands/my-command.md for personal use or .claude/commands/my-command.md for a project. The filename becomes the slash command name — so refactor.md becomes /refactor. For more power, use the newer Skills approach: create a directory under ~/.claude/skills/ containing a SKILL.md file with YAML frontmatter, which unlocks argument passing, bundled supporting files, and automatic invocation by Claude.

What Are Claude Code Slash Commands?

Slash commands are special directives typed directly into the Claude Code terminal interface, each prefixed with a forward slash (/). They give developers a fast, deterministic way to control session behavior — things like compressing context, switching models, clearing history, or running diagnostic checks — without needing to phrase requests in natural language.

Two categories exist:

• Built-in commands — bundled with Claude Code and cover common session management tasks (e.g., /compact, /clear, /doctor).
• Custom commands — Markdown files you write that encode repeatable workflows like code reviews, security scans, or refactors. Claude follows them like a playbook.

Typing / in a Claude Code session opens an autocomplete menu showing all available built-in and custom commands. You can also access available slash commands programmatically through the Claude Agent SDK, where they are listed in the system initialization message.

How Do You Create a Custom Slash Command? (Two Approaches)

Approach 1: The Skills Method (Recommended for New Commands)

The Skills approach is the newer method and supports the most features. Here is how it works:

1. Create a directory for your skill: mkdir -p ~/.claude/skills/refactor
2. Inside that directory, create a SKILL.md file.
3. Add YAML frontmatter at the top of the file with at minimum a name, description, and allowed-tools field. The value of the name field becomes the slash command.
4. Below the frontmatter, write your Markdown instructions — this is the prompt Claude will follow.
5. Start or restart a Claude Code session: claude
6. Invoke your command: /refactor src/auth/login.ts

A minimal SKILL.md looks like this:

---
name: refactor
description: Reads a TypeScript file, applies clean-code principles, runs tests, and reports results
allowed-tools: [Read, Edit, Bash]
---

Read the file at $ARGUMENTS. Identify and fix: magic strings, duplicated logic, and missing error types.
Extract constants, consolidate validators, add typed error handling.
Run the test suite and report pass/fail counts.

Notice the $ARGUMENTS placeholder — whatever you type after the command name at invocation time is substituted in. Running /refactor src/auth/login.ts passes src/auth/login.ts as the argument. Make sure to spell it exactly as $ARGUMENTS (all caps) or it will appear literally in the output.

Approach 2: The Legacy Method (Still Fully Supported)

The legacy approach stores plain Markdown files in a commands directory. No YAML frontmatter is required — the filename becomes the command name.

• Personal scope (all projects): ~/.claude/commands/refactor.md
• Project scope (shared via version control): .claude/commands/refactor.md

Legacy commands still work and are a fine choice for simple, argument-free workflows. They do not support automatic invocation by Claude or bundled supporting files.

How Do You Choose Between Project-Scoped and Personal Commands?

The right scope depends on who should have access to the command:

A practical example: a /security-scan command that checks for SQL injection, exposed credentials, and insecure configs belongs in .claude/commands/ so every developer on the team can run it pre-commit without remembering the full prompt.

What Are the Most Useful Built-In Slash Commands?

Before building custom commands, it is worth knowing what comes built-in:

• /compact — Summarizes conversation history to free up context while preserving key decisions. Use this instead of /clear for routine context management.
• /clear — Wipes all conversation history for a completely fresh start. Reserve this for pivoting to an unrelated task.
• /doctor — Checks environment setup, surfaces misconfigured paths or missing dependencies, and reports what is and is not working.
• /help — Lists all available commands with descriptions.

For example, running /compact keep the database schema constraints and authentication patterns tells Claude to summarize history while explicitly retaining the details you specify — a much safer option than losing everything with /clear.

How Do You Avoid Common Pitfalls When Creating Custom Commands?

Command not appearing in autocomplete

Verify the file is in the correct directory. For Skills, confirm the directory is under ~/.claude/skills/ or .claude/skills/ and contains a SKILL.md file with a valid name field in the frontmatter. After creating new files, restart the Claude Code session by running exit then claude.

Skill description gets truncated

Each skill's combined name and description text is subject to a character budget — by default 1% of the context window, with a fallback of 8,000 characters. If you have many skills loaded and some stop appearing or auto-invoking, front-load the most important keywords in the description field. You can also raise the budget before starting Claude Code:

export SLASH_COMMAND_TOOL_CHAR_BUDGET=16000
claude

Write descriptions as keyword-dense phrases rather than full sentences. Claude matches your query against the description to decide whether to auto-load a skill; burying keywords in long prose reduces match accuracy and wastes the character budget. See the official character budget documentation for more detail.

$ARGUMENTS appears literally in output

Confirm the placeholder is spelled exactly as $ARGUMENTS (all caps) in the SKILL.md body. Also ensure you are passing arguments at invocation time — for example, /batch-test auth rather than /batch-test with no arguments.

When Should You Use Custom Slash Commands vs. Ad-Hoc Prompts?

Custom slash commands pay off when a workflow is repeatable, multi-step, and shared. If you find yourself typing the same long instruction prompt more than a few times — or if teammates need to run the same check consistently — encoding it as a slash command saves time and enforces standards.

For one-off tasks that are unlikely to be repeated, a natural-language prompt is faster and perfectly appropriate. The overhead of creating a SKILL.md file is only worth it when the workflow has staying power.

Is There a Way to Share Slash Commands Across a Whole Team at Once?

Yes. Plugins, which launched in public beta, let you package a collection of slash commands, MCP servers, and hooks as an installable bundle. Any developer can install the entire collection with a single /plugin install command inside Claude Code, eliminating manual filesystem setup. This is the most efficient path for distributing shared command libraries across many developer machines.

For programmatic access, developers on Pro, Max, Team, and Enterprise plans can inspect available slash commands via the Agent SDK by examining the slash_commands field on the system init message in the SDK response stream. Refer to the official slash commands documentation for the full reference.