How to Create Custom Slash Commands in Claude Code with Examples

Posted on June 21, 2025

This article was written manually. AI was only used for typo detection.
Based on Claude Code v1.0.31.

I’m Oikon, an IT engineer at a foreign company.

Since Anthropic’s announcement for engineers on May 22nd, Claude Code has been gaining a lot of attention. I personally feel we’re in a transitional period where many people are experimenting with how to use Claude Code.

In this article, I’d like to share my personal experimentation with Custom Slash Commands. This is an expanded version of the custom slash commands I recently posted on 𝕏.

@tweet

I also received some replies and quote posts where others shared their custom slash commands, so I’ll introduce those as well.

About Custom Slash Commands

Slash Command Overview

Claude Code has Slash Commands that execute pre-assigned operations when you type /(slash) during input.

Here are some commonly used examples:

/init: Create CLAUDE.md
/clear: Reset the context window
/model: Switch models
/resume: Restore conversation history (recently added)
/release-note: Display release notes

I’ve covered each slash command in detail in the following article (note: this is based on v1.0.6):

Claude Codeの/ (スラッシュ)コマンドを全部試したので解説する

zenn.dev

You can also create your own custom commands, which are called Custom Slash Commands.

How to Create Custom Slash Commands

Creating custom slash commands is incredibly simple. Really easy.

Create directory .claude/commands/ or ~/.claude/commands/
Create $COMMAND_NAME.md (name it yourself)
Write instructions in the md file

That’s it! Simple!

The difference in the commands/ directory path determines whether it’s a Project command or Personal command:

.claude/commands/: Project-specific commands (project)
~/.claude/commands/: Personal commands. Applied to all projects (user)

Each will display (project) or (user) in the description.

Official Command Samples

Here are some custom slash command samples from the official documentation:

optimize.md:

"Analyze this code for performance issues and suggest optimizations:"

security-review.md:

"Review this code for security vulnerabilities:"

Custom slash commands can take arguments using $ARGUMENTS:

fix-issue.md

Fix issue #$ARGUMENTS following our coding standards

A fix-issue.md like the above can be invoked by specifying the issue number at command execution:

/fix-issue 123

Here’s the official documentation. Note that the content is slightly outdated and prefix doesn’t exist in v1.0.31:

Extend Claude with skills - Claude Code Docs

Create, manage, and share skills to extend Claude's capabilities in Claude Code. Includes custom slash commands.

docs.anthropic.com

As a complete aside (and I don’t necessarily recommend it), you can create custom slash commands with Japanese names. The command content itself can be in Japanese too.

Oikon’s Custom Slash Command Examples

From here, let’s dive deeper into custom slash commands with several examples.

/bugfix

A command for bug fixes. Pass the bug details as an argument and have Claude attempt to resolve it.

Reproduce the issue and analyze the cause
Have multiple sub-agents execute MCP servers and Web Search to get the latest information about the error and solve the problem
If the error isn’t fixed, repeat steps 1 and 2
Write a bug report

# Fix bug from user provided bug description: $ARGUMENTS

## Goal

Recreate the issue and fix the bug

## Steps (obey strictly)

Bug description user provided: $ARGUMENTS

Step 1: Understand the bug description and think the root cause. Try to recreate the issue.
Step 2: Fix the error. Use `context7` and `brave-search` MCP tools to understand the error.
These MCP tool search should be done by multiple subagents. Also use native Web search subagent for issue investigation.
Step 3: If there is another error, always repeat this debugging process from Step 1 and Step 2.
Step 4: Report root cause and the solution.

/explain-project

Recently, I’ve been cloning OSS projects and asking Claude Code about their contents more often, so I’ve prepared a command for project overview explanations.

I explicitly assign the architect role to explain the project.

Repository analysis
Create project overview
Output to Markdown file

Specifying Mermaid graph TD will generate diagrams.

# Explain project high-level architecture

You are a senior software architect and technical writer. You can use multiple subagents to analyze the repository.
You should not run the project but get/read it.

## Goal

Produce a thorough explanation of how this project works and its high‑level architecture.

## Generation steps (obey strictly)

Step 1. Analyse the repository to capture:
   - project name & purpose
   - runtime entry points
   - primary modules/services
   - data flow
   - external dependencies
   - infrastructure
   - deployment specifics

Step 2. Create Markdown with these sections exactly in order:

   1. Project Name – bold text
   2. Overview – concise paragraph (≤ 160 words)
   3. Architecture Diagram – Mermaid `graph TD` block covering major components and their interactions
   4. Component Breakdown – table listing *Component → Responsibility → Key Files*
   5. Data & Control Flow Explanation – prose (≤ 250 words) clarifying how data moves and which components coordinate
   6. Tech Stacks – bullets on build, provide the tech stacks overview

Step 3. No hard word limit, but keep writing purposeful; avoid fluff.

Step 4. Output Markdown only, no extra commentary beyond the sections above.

/feature-log

A command to create logs after implementing features. I created this for documentation and to later feed into Context.

If you specify ./log/feature/, all logs will be recorded there when the command runs. I’ve also added instructions to create the directory if it doesn’t exist.

A notable feature is that you can include Markdown formatting for the log format within the Markdown itself. (Using ”“” notation due to Zenn formatting)

# Create log file for feature, feature description: $ARGUMENTS

You are a meticulous release engineer.

## Goal

Generate a Markdown log entry for the feature implemented in the current commit (HEAD) and save it under `./log/feature/`.

## Behaviour specification (follow in order)

Step 1. Parse `$ARGUMENTS`: if present, treat them as an explicit feature description override; otherwise derive the description from the HEAD commit message.
Step 2. Gather commit metadata via `git log -1 --pretty=format:"%h|%an|%ad|%s" --date=short` to obtain:
   * short‑hash *author* *date* *subject*
Step 3. Identify changed files with `git diff-tree --no-commit-id --name-only -r HEAD`.
Step 4. Ensure the folder `./log/feature/` exists (create if missing).
Step 5. Create the log file `./log/feature/<date>-<feature>.md` (e.g. `2025-06-18-create-button.md`).
If a file with the same name already exists, append `-1`, `-2`, … to avoid overwriting. `<feature>` should be less than 20 characters.
6. Write Markdown content as follows:

   ``markdown
   # <subject or $ARGUMENTS>

   Commit: `<hash>`
   Author: <author>
   Date: <date>

   ## Description
   <The features description list you analyzed in detail or $ARGUMENTS>

   ## Modified Files
   - file/path/one
   - file/path/two
   ...
   ``

7. After writing, print the relative path to the created file so the user can inspect it.

/plan-to-checklist

A command to convert Plan mode content into a checklist.

I created this command when Plan mode was introduced because I wanted to further modify the Plan myself by converting it to a checklist. You can specify the filename as an argument.

I explicitly have it use Step and checklist [ ] syntax, so this document can be used as a TODO list.

# Convert Plan to Checklist document, document title: $ARGUMENTS

Step 1: Check the plan you created and convert it into a checklist in Markdown format. Copy it exactly.
Step 2: The task list should use checklist syntax `[ ]`. Begin each task phase with the word "Step."
Step 3: Save the file to `./docs/plan/` with the filename `<$ARGUMENTS>.md`. If $ARGUMENTS is not provided, choose a filename you recommend that is fewer than 15 characters.

/test-report

A command to run tests and create test reports.

It outputs a text file with error logs and a summary Markdown file to ./log/test.

It’s a bit verbose, so I think it might be more user-friendly if simplified further.

# Run test and create report in ./log/test/

You are a senior test‑automation engineer.

## Goal

Execute the project's entire test suite, collect coverage metrics, and save a concise, human‑readable report under `./log/test/`.

## Behaviour specification (follow strictly)

Step 1. Detect tech stack by reading config files:
   • JavaScript/TypeScript → Jest
   • Python → pytest
Step 2. Derive the test command and coverage flags (e.g. `--coverage`, `pytest --cov`, `go test -cover`).
Step 3. Ensure the folder `./log/test/` exists (create if necessary).
Step 4. Run tests in a clean environment (no watch mode, no interactive prompts) and capture:
   - exit code
   - console output
   - coverage summary (lines %, branches %, functions % where available)
Step 5. Save artifacts:
   - Raw console output → `./log/test/<date>-<hash>.txt`
   - Markdown summary → `./log/test/<date>-<hash>.md`
Step 6. Markdown summary must contain sections in order:
   1. `# Test Report (<date> – <hash>)`
   2. Summary – total tests, passed, failed, skipped, duration
   3. What kinds of tests you run
   4. Coverage – table with metric → percentage (omit if unavailable)
   5. Failed Tests – collapsible list (`<details>` blocks) with name & error snippet (max 20 lines each)
   6. Next Steps – bullet suggestions (retry, refactor, increase coverage)
Step 7. After writing files, print the relative paths to both artifacts.

Custom Commands from Others

I asked about other people’s custom slash commands on 𝕏 (formerly Twitter), and received several examples, so I’d like to introduce them.

Comute: Blog Article Creation

@tweet

A /blog command that automatically generates technical blog articles.

I thought this was a very fitting custom command from Comute, who runs izanami.dev, a platform where indie developers can register their products and post technical articles!

The command contents were also made public, so I’ll share them in this article as well. (Using ”“” notation due to Zenn formatting)

# /blog

## Overview

Automatically generates technical blog articles based on recent implementation content and technical efforts.

## Execution Content

1. **Implementation History Analysis**

   - Check recent git commit history
   - Analyze implementation logs in `_docs/` directory
   - Investigate changed files and their contents

2. **Article Structure Generation**

   - Technical challenges and solutions
   - Implementation points and learnings
   - Code examples and best practices
   - Knowledge applicable to other developers

3. **Blog Article Creation**
   - Generate technical articles in Markdown format
   - SEO-conscious titles and structure
   - Practical content including actual code examples
   - Save to `_docs/blog/` directory

## Article Template

- **Title**: Generate an attractive title from implementation content
- **Overview**: What was solved, what was learned
- **Tech Stack**: Technologies and tools used
- **Implementation Details**: Specific implementation methods and code examples
- **Lessons Learned**: Learnings including failures and improvements
- **Summary**: Applicability for other developers

## Target Content

- React/Next.js component development
- Type-safe implementation with TypeScript
- Test-driven development (TDD) practice
- Performance optimization
- User experience improvements
- Development tool utilization

## Output Example

``
_docs/blog/2025-06-19_Jest Test Environment Setup and Comprehensive Test Suite.md
``

## Usage Example

``
/blog
``

akiramei: Improved fix-issue

@tweet

In addition to the official fix-issue, explicit instructions for ticket and branch creation are added.

Bug fix commands are indeed used frequently, so it makes sense to customize them.

Here’s the Markdown content:

Find and fix issue #$ARGUMENTS. Follow these steps:

1. **FIRST** check if issue is open: `gh issue view $ARGUMENTS --json state -q .state` (must be "OPEN")
2. **IMMEDIATELY** create branch: `git checkout -b fix-issue-$ARGUMENTS` (DO THIS BEFORE ANY OTHER WORK!)
3. Now read issue details: `gh issue view $ARGUMENTS` to understand the issue
4. Locate the relevant code in our codebase
5. Implement a solution that addresses the root cause
6. Add appropriate tests if needed
7. Commit changes with proper commit message
8. Push the branch and create a PR using `gh pr create`
9. Prepare a concise PR description explaining the fix

**CRITICAL**: Always create the branch (step 2) immediately after confirming the issue is open. This prevents accidental commits to main branch.