Claude Code Slash Commands

Guide Claude through creating and configuring custom slash commands for Claude Code.

Purpose

Slash commands let users define frequently-used prompts as Markdown files that Claude can execute on demand. This skill helps create well-structured slash commands with proper frontmatter, arguments, bash execution, and other advanced features.

When to Use This Skill

Use this skill when:

• Creating new custom slash commands (project or personal)
• Adding arguments, bash execution, or file references to commands
• Configuring frontmatter options (allowed-tools, model, argument-hint, etc.)
• Troubleshooting slash command issues

Command Types

Project Commands

• Stored at: .claude/commands/
• Shared with the team (versioned in git)
• Shown as (project) in /help

Personal Commands

• Stored at: ~/.claude/commands/
• Available across all projects
• Shown as (user) in /help

Plugin Commands

• Stored at: commands/ in plugin root
• Distributed via plugin marketplaces
• Shown as (plugin:plugin-name) in /help
• Invoked with /plugin-name:command-name or just /command-name
• Support all features (arguments, frontmatter, bash, file references)

Creating Slash Commands

Quick Creation with Helper Script

Use the bundled creation script for fast, templated command setup:

# Create project command with basic template
scripts/create_slash_command.sh my-command --project

# Create personal command with advanced template
scripts/create_slash_command.sh my-command --user --template advanced

# Create plugin command (auto-detects plugin from current directory)
scripts/create_slash_command.sh my-command --plugin

# Create plugin command for specific plugin
scripts/create_slash_command.sh my-command --plugin my-plugin-name

# Available templates: basic, arguments, bash, advanced

The script is located at: scripts/create_slash_command.sh

Plugin command creation:

• Use --plugin to create commands in a plugin's commands/ directory
• Auto-detects plugin when run from within a plugin directory
• Or specify plugin name: --plugin my-plugin-name
• Reminds you to register the command in marketplace.json

Manual Creation

When creating commands manually, follow this structure:

1. Choose scope - Decide between:

   • Project: .claude/commands/
   • Personal: ~/.claude/commands/
   • Plugin: plugins/<plugin-name>/commands/

2. Create directory - Ensure the target directory exists:

   mkdir -p .claude/commands            # Project
   mkdir -p ~/.claude/commands          # Personal
   mkdir -p plugins/my-plugin/commands  # Plugin
   

3. Create file - Named command-name.md (the filename becomes the command)

4. Add frontmatter - Include at minimum a description field

5. Write instructions - Clear, actionable prompts for Claude

6. Register plugin commands - If creating a plugin command:

   • Open .claude-plugin/marketplace.json
   • Find the plugin's entry in the plugins array
   • Add "./commands/command-name.md" to the plugin's commands array

Available Templates

Four templates are provided in assets/ for common use cases:

Basic Template (template-basic.md)

Minimal slash command with just description and instructions.

Use when: Creating simple, straightforward prompts.

Arguments Template (template-with-arguments.md)

Shows how to use $ARGUMENTS, $1, $2, etc. for parameterized commands.

Use when: Commands need user-provided input or parameters.

Bash Template (template-with-bash.md)

Demonstrates bash command execution with the `!` prefix for gathering context.

Use when: Commands need git status, file listings, or other system context.

Advanced Template (template-advanced.md)

Full-featured template with all frontmatter options, bash execution, arguments, and file references.

Use when: Building complex workflows or need multiple features.

Frontmatter Options

All available frontmatter fields:

---
description: Brief description shown in /help
argument-hint: [arg1] [arg2]
allowed-tools: Bash(git:*), Read, Write, Edit
model: claude-sonnet-4-5-20250929
disable-model-invocation: false
---

Field Details

• description (required) - Brief description of what the command does
• argument-hint - Shown in autocomplete, helps users know what arguments to provide
• allowed-tools - Pre-approved tools the command can use (bypasses permission prompts)
• model - Specific model to use for this command (overrides conversation model)
• disable-model-invocation - Prevents SlashCommand tool from executing this command

Advanced Features

Arguments

Two ways to handle arguments:

1. Capture all as string:

Fix issue #$ARGUMENTS following our coding standards

Usage: /fix-issue 123 high-priority → $ARGUMENTS = "123 high-priority"

2. Individual positional arguments:

Review PR #$1 with priority $2 and assign to $3

Usage: /review-pr 456 high alice → $1="456", $2="high", $3="alice"

Bash Command Execution

Execute bash commands inline to gather context:

---
allowed-tools: Bash(git status:*), Bash(git diff:*)
---

## Context
- Current status: \`!\` `git status`
- Current diff: \`!\` `git diff HEAD`

Important: Commands prefixed with `!` run before the slash command is processed. Results are injected into the prompt.

File References

Reference files using `@` prefix:

Review the implementation in \@src/utils/helpers.js
Compare \@old-file.js with \@new-file.js

Extended Thinking Mode

Trigger extended thinking by including keywords:

• "think carefully"
• "analyze thoroughly"
• "consider all implications"

Workflow

When creating a new slash command:

1. Understand requirements - Ask user about:

   • Command purpose and when it should be used
   • Whether arguments are needed
   • What context (bash, files) should be gathered
   • Scope (project, personal, or plugin)

2. Choose template - Select the most appropriate template:

   • Basic for simple prompts
   • Arguments for parameterized commands
   • Bash for context-gathering commands
   • Advanced for complex workflows

3. Use creation script or manual approach:

   • Project: scripts/create_slash_command.sh <name> --project --template <type>
   • Personal: scripts/create_slash_command.sh <name> --user --template <type>
   • Plugin: scripts/create_slash_command.sh <name> --plugin [plugin-name] --template <type>
   • Manual: Create file in appropriate directory

4. Customize content:

   • Update frontmatter (especially description)
   • Write clear, actionable instructions
   • Add success criteria if applicable
   • Configure allowed-tools if using bash

5. Register plugin commands (plugin scope only):

   • Add command to .claude-plugin/marketplace.json
   • In the plugin's entry, add "./commands/<command-name>.md" to the commands array
   • The script will remind you of this step

6. Test and iterate:

   • Project/personal: Run with /command-name
   • Plugin: Run with /plugin-name:command-name
   • Verify it works as expected
   • Adjust based on results

Reference Documentation

For detailed information about slash commands, refer to references/slash-commands-reference.md, which contains:

• Complete frontmatter field reference
• Permission rules and SlashCommand tool details
• MCP slash command integration
• Plugin command structure
• Skills vs slash commands comparison

Load this reference when users need detailed technical information beyond the workflow guidance in this skill.

Best Practices

• Keep it focused - One command, one clear purpose
• Use descriptive names - Command names should indicate what they do
• Document arguments - Include argument-hint in frontmatter
• Specify allowed-tools - Pre-approve tools to avoid permission prompts
• Test thoroughly - Verify commands work before committing to project or publishing plugin
• Consider scope - Project for team workflows, personal for individual preferences, plugin for reusable/distributable commands
• Register plugin commands - Always update marketplace.json when creating plugin commands

Skills vs Slash Commands

Help users choose between creating a skill or a slash command:

Use Slash Commands when:

• Single file is sufficient
• Simple, repeatable prompts
• Manual invocation desired
• Quick setup needed

Use Skills when:

• Multiple files/scripts needed
• Complex workflows required
• Automatic triggering desired
• Bundled resources beneficial

Both can coexist; recommend the approach that best fits the use case.