Creating Reusable Shortcuts with Custom Slash Commands

In the previous lesson, you learned how the CLAUDE.md file creates persistent context for Claude Code. Each time you start a session, Claude reads that file and automatically knows your project's color schemes, coding conventions, and quality standards. But what about tasks that you perform repeatedly — like checking color consistency or auditing chart styling? Even with great context, you would still need to type detailed instructions every time.

This is where custom slash commands come in. In this lesson, you will learn how to package common prompts into reusable commands stored in the .claude/commands/ directory. By the end, you will type something as simple as /review-colors penguin_scatter.py and have Claude instantly audit your visualization for color consistency — no lengthy prompts required.

Custom slash commands are reusable prompt templates that you invoke by typing a slash followed by the command name. Instead of writing a detailed prompt every time that you want Claude to perform a specific task, you write the prompt once, save it as a command, and trigger it whenever needed.

These commands live in a special directory: .claude/commands/ within your project folder. When Claude Code starts, it scans this directory and registers any command files that it finds. Each file becomes an available slash command that you can use during your session.

Here is how the discovery process works:

1. You create a Markdown file in .claude/commands/ (for example, review-colors.md).
2. Claude Code detects this file when you start a session or use the / menu.
3. The command becomes available as /review-colors.
4. When you type that command, Claude reads the file contents and executes them as a prompt.

Commands stored in your project's .claude/commands/ folder are project-specific and available when working in that project. You can also create user-level commands in ~/.claude/commands/ that apply across all projects. For visualization workflows tied to a specific dataset and style guide, project-level commands are typically what you want.

Before creating your first command, you need the directory structure in place. Custom commands must be stored in a specific folder so Claude can discover them.

Here is how your project should be organized to support custom commands:

your-project/
├── .claude/
│   └── commands/
│       ├── review-colors.md      # Invoked as /review-colors
│       ├── check-chart.md        # Invoked as /check-chart
│       └── export-highres.md     # Invoked as /export-highres
├── CLAUDE.md                     # Project-wide context
├── penguins.csv                  # Your dataset
└── penguin_scatter.py            # Your visualization script

If the .claude/commands/ directory does not exist, you can create it with a single terminal command: mkdir -p .claude/commands. The -p flag creates both the .claude parent directory and the commands subdirectory in one step. Once this structure exists, any Markdown file you place inside will be registered as a new command the next time you start a session.

A command file is simply a Markdown file with a .md extension. The filename determines the command name, and the file contents become the prompt that Claude executes.

Here is how filenames map to command names:

Notice that hyphens in the filename become hyphens in the command name. Use lowercase letters and hyphens for readability. Avoid spaces or special characters in filenames.

Command files can include optional YAML frontmatter at the top to provide metadata and constraints. Frontmatter is enclosed between triple dashes (---) and appears before your prompt content.

Two useful frontmatter fields are:

• description: A short summary that appears when browsing available commands in the / menu. This helps you and your team quickly understand what each command does.
• allowed-tools: Restricts which tools Claude can use when executing the command. This is useful for safety — for example, limiting a review command to only read files without making changes.

Frontmatter is entirely optional. If you omit it, your command will still work — Claude will simply have access to all its default tools and the command won't have a description in the menu. However, adding frontmatter makes your commands more discoverable and predictable.

Many commands benefit from accepting dynamic input at runtime. Rather than hardcoding a specific filename, you can pass the target file when you invoke the command. The $ARGUMENTS placeholder lets you specify exactly where this input should appear in your prompt.

When you include $ARGUMENTS in your command file, Claude replaces it with whatever text you type after the command name. For example, if your command contains Review the file $ARGUMENTS and you type /review-colors penguin_scatter.py, Claude sees Review the file penguin_scatter.py.

You can also pass multiple arguments after the command name. In that case, $ARGUMENTS contains the full text you entered (for example, filenames, options, or labels separated by spaces). If you want to refer to individual arguments, you can use positional placeholders like $0, $1, $2 (or $ARGUMENTS[0], $ARGUMENTS[1], and so on).

This makes a single command flexible enough to work with different files, chart types, or any other variable input. The placeholder acts like a fill-in-the-blank spot in your prompt template.

When should you use arguments versus keeping commands simple? Use arguments when the same logic applies to different targets (files, chart types, species names). Keep commands argument-free when they should always operate the same way (like auditing the entire project at once).

Let's create a practical command that checks whether your visualization scripts use the approved color palette. As a reminder from the previous lesson, your CLAUDE.md defined species colors: Adelie (#FF6B6B), Chinstrap (#4ECDC4), and Gentoo (#95E1D3).

Create a file named review-colors.md inside the .claude/commands/ directory with the following content:

---
description: Check if a visualization uses the standard penguin species color scheme
allowed-tools: Read
---

Review the file $ARGUMENTS and verify it uses our standard species colors:
- Adelie: #FF6B6B (coral red)
- Chinstrap: #4ECDC4 (teal)
- Gentoo: #95E1D3 (mint green)

If the file is a Python script, check the code for color definitions.
If the file is an image, analyze the colors used in the visualization.

Report:
1. Whether colors match our standards
2. Any deviations found
3. Suggested fixes (with exact code snippets if it's a .py file)

This command includes frontmatter that describes its purpose and restricts Claude to only reading files — it cannot modify anything. The $ARGUMENTS placeholder on the first line of the prompt will be replaced with whatever filename you specify when running the command.

With the command file in place, you can now invoke it by typing /review-colors followed by the file you want to check. Claude reads the command file, replaces $ARGUMENTS with your input, applies the constraints from the frontmatter, and executes the prompt.

Here is what the interaction looks like when checking a Python script:

> /review-colors penguin_scatter.py 

● I'll review the penguin_scatter.py file to check if it uses the standard species color scheme.

● Read(penguin_scatter.py)
  ⎿  Read 32 lines

● Color Review Report

  Status: ❌ Color deviation found

  Deviations:

  1. Gentoo species (line 9): Uses #9B59B6 (purple) instead of the standard #95E1D3 (mint green)

  Correct Colors:

  - ✅ Adelie: #FF6B6B (coral red) - matches standard
  - ✅ Chinstrap: #4ECDC4 (teal) - matches standard
  - ❌ Gentoo: #9B59B6 (purple) - should be #95E1D3 (mint green)

  Suggested Fix:

  Replace line 9 in penguin_scatter.py:

  'Gentoo': '#95E1D3'

  Complete corrected color dictionary:
  species_colors = {
      'Adelie': '#FF6B6B',
      'Chinstrap': '#4ECDC4',
      'Gentoo': '#95E1D3'
  }

  The script correctly applies these colors to the scatter plot visualization. Once the Gentoo color is updated, all species will use the standard color scheme.

With a single command, Claude read your visualization script, compared colors against your standards, and provided actionable recommendations with exact code snippets. Notice that Claude only used the Read tool — the allowed-tools constraint in the frontmatter prevented it from making direct modifications to your file.

The same command works on exported visualization images. Claude can analyze the actual colors rendered in a PNG file, which is useful for verifying that your final output matches expectations — even if you don't have access to the source code.

Here is the visualization we want to check:

Running the same /review-colors command on this image:

> /review-colors penguin_bills.png 

● I'll analyze the penguin_bills.png image to verify if it uses the standard species color scheme.

● Read(penguin_bills.png)
  ⎿  Read image (157.1KB)

● Color Review Report

  Status: ❌ COLORS DO NOT MATCH STANDARDS

  Analysis

  The visualization uses the following colors:
  - Adelie: Coral/salmon red - appears to match ✓
  - Chinstrap: Teal/turquoise - appears to match ✓
  - Gentoo: Purple/violet - DOES NOT MATCH ❌

  Deviations Found

  Gentoo species color is incorrect:
  - Current: Purple/violet color (appears to be around #9370DB or similar)
  - Standard: #95E1D3 (mint green)

Claude analyzed the image pixels directly and identified the same color deviation. This flexibility makes your command useful for auditing both source code and final outputs — catching issues regardless of where they appear in your workflow.

Your command library now works in harmony with the CLAUDE.md file that you created in the previous lesson. These two customization tools serve complementary purposes.

The CLAUDE.md file establishes what Claude should always know: color palettes, typography standards, coding conventions, and quality checklists. This context loads automatically at the start of every session. Slash commands define what Claude should do on demand: audit colors, check individual charts, export files, or suggest improvements. Each command can reference the standards in CLAUDE.md without repeating them.

For team workflows, commands ensure that everyone uses the same quality checks and processes. For solo work, they save you from typing the same detailed prompts across sessions. Either way, the combination of persistent context and active shortcuts creates a powerful, repeatable workflow.

You have learned how to extend Claude Code's customization from passive context into active, triggerable workflows. The key concepts are:

• Command files are Markdown files in .claude/commands/ that become slash commands
• Frontmatter (optional) adds descriptions and tool restrictions using YAML between --- markers
• $ARGUMENTS placeholder inserts user input (like filenames) into your prompt template
• Commands work on multiple file types — the same command can analyze Python scripts and images

In the upcoming practice exercises, you will create your own command library for visualization workflows. You will write commands that audit styling, check individual charts, and verify color compliance — all triggered with a simple slash. Get ready to build the shortcuts that will make your visualization work faster and more consistent.