The Complete Guide to Claude Code Custom Slash Commands: Build Your Own Command Library

<!-- .claude/commands/your-command.md -->
 
## Context
[Tell Claude about the project background and tech stack]
 
## Task
[Define exactly what to do]
 
## Constraints
[List rules that must be followed]
 
## Output Format
[Describe the expected output]

Help me write tests

Write unit tests for $ARGUMENTS.
 
Tech stack:
- Test framework: vitest
- Assertions: vitest built-in
- Mocking: vi.mock()
 
Requirements:
1. Cover happy paths, edge cases, and error paths
2. Organize with describe/it blocks, use descriptive names
3. Mock all external dependencies (API calls, filesystem, database)
4. Place test files in __tests__/ under the same directory, named [filename].test.ts
5. Don't test implementation details — only test public interface behavior
 
Read the target file first to understand its public interface, then write tests.

Read the following files to understand project conventions:
- CLAUDE.md
- src/types/index.ts
- src/lib/constants.ts
 
Then generate code for $ARGUMENTS that follows project conventions.

Perform a security audit on $ARGUMENTS, following these steps:
 
### Step 1: Static Analysis
Read the code and check for:
- SQL injection
- XSS (Cross-Site Scripting)
- Command injection
- Path traversal
- Insecure deserialization
 
### Step 2: Dependency Check
Check package.json dependencies for known vulnerabilities.
 
### Step 3: Output Report
Use this format:
 
| Severity | Issue | Location | Suggested Fix |
|----------|-------|----------|---------------|
| High/Med/Low | Description | file:line | Fix approach |
 
If no issues are found, explicitly state "No security issues found."

<!-- .claude/commands/compare.md -->
Compare two files and provide optimization suggestions.
 
Argument format: `fileA fileB`
 
Example usage: `/compare src/old-api.ts src/new-api.ts`
 
Read both files from $ARGUMENTS, then:
1. List the major differences
2. Analyze the pros and cons of each
3. Suggest how to merge or optimize

<!-- .claude/commands/doc.md -->
Generate JSDoc documentation for $ARGUMENTS.
 
Requirements:
- Add JSDoc to all exported functions, classes, and interfaces
- Include @param, @returns, @throws, @example
- Example code should be runnable
- Don't modify function implementations — only add comments
 
Read the file first to understand each export's purpose, then add documentation.

<!-- .claude/commands/commit-msg.md -->
Generate a commit message based on the current git diff --staged.
 
Format:
- type: short description (under 50 characters)
- Types: feat, fix, refactor, docs, test, chore
- Description in English
 
$ARGUMENTS
 
If additional context is provided above, incorporate it. Otherwise, infer from the diff content.

<!-- .claude/commands/review.md -->
Code review the changes in git diff --staged.
 
Review dimensions:
1. **Security** — XSS, injection, sensitive data exposure, insecure dependencies
2. **Performance** — unnecessary re-renders, memory leaks, N+1 queries, expensive loops
3. **Maintainability** — naming clarity, function length, single responsibility
4. **Edge cases** — null handling, error handling, concurrency safety
 
Output format:
- Tag each issue with severity (🔴 High / 🟡 Medium / 🟢 Low)
- Provide specific fix suggestions with code examples
- End with an overall assessment
 
If the code quality is good, say so explicitly.

<!-- .claude/commands/refactor.md -->
Analyze $ARGUMENTS and suggest refactoring improvements.
 
Analysis dimensions:
1. Is there duplicate code that can be extracted?
2. Are functions too long and need splitting?
3. Are there better design patterns to apply?
4. Can type definitions be improved?
 
Requirements:
- Only suggest refactoring with real value — don't refactor for the sake of it
- Show before/after code comparisons for each suggestion
- Assess the risk and benefit of each refactoring

<!-- .claude/commands/test.md -->
Write unit tests for $ARGUMENTS.
 
Framework: vitest
Rules:
1. Cover happy paths, edge cases, error paths
2. Use describe/it structure with descriptive names
3. Mock external dependencies
4. Test file: __tests__/[filename].test.ts in the same directory
5. Only test public interfaces, not implementation details
 
Read the target file to understand its interface first, then write tests.

<!-- .claude/commands/test-edge.md -->
Read the existing tests for $ARGUMENTS and add missing edge case coverage.
 
Focus on:
- null / undefined / empty values
- Empty arrays / empty strings
- Very large inputs
- Concurrent calls
- Type boundaries (e.g., Number.MAX_SAFE_INTEGER)
- Special characters and Unicode
 
Don't duplicate existing test cases.

<!-- .claude/commands/doc.md -->
Add documentation comments to all exports in $ARGUMENTS.
 
Format: JSDoc / TSDoc
Include: @param, @returns, @throws, @example
Requirements:
- Example code should be runnable
- Don't modify implementation code
- Add @remarks for complex logic to explain design intent

<!-- .claude/commands/changelog.md -->
Generate CHANGELOG entries based on recent git log.
 
$ARGUMENTS
 
If a version number is specified, use it; otherwise use the date.
 
Format:
## [version/date]
 
### New Features
- description
 
### Fixes
- description
 
### Changes
- description
 
Only include user-facing changes. Ignore internal refactoring and style changes.

<!-- .claude/commands/commit-msg.md -->
Generate a commit message based on git diff --staged.
 
Format: type: description
Types: feat / fix / refactor / docs / test / chore / perf
Description: English, under 50 characters
For larger changes, add a blank line followed by detailed explanation.
 
$ARGUMENTS

<!-- .claude/commands/pr-desc.md -->
Generate a Pull Request description based on the diff between the current branch and main.
 
Run git log main..HEAD and git diff main...HEAD to get the changes.
 
Format:
## Summary
One sentence describing what this PR does.
 
## Changes
- List the major changes
 
## Testing
- Describe how to test these changes
 
## Screenshots (if applicable)
Note whether screenshots are needed.

<!-- .claude/commands/debug.md -->
Diagnose the following issue:
 
$ARGUMENTS
 
Steps:
1. Understand the problem description
2. Locate potentially related code
3. Analyze possible causes (list at least 3)
4. Provide the most likely cause and fix
5. If more information is needed, specify what
 
Don't modify code directly — provide analysis first.

<!-- .claude/commands/explain.md -->
Explain the code logic in $ARGUMENTS.
 
Requirements:
- Start with a one-sentence summary of the file/function's purpose
- Then explain key logic section by section
- Flag complex or non-obvious parts
- Point out potential issues if any
- Use analogies to help explain complex concepts

# 1. Build the feature
> Implement a user favorites feature, store data in localStorage
 
# 2. Review the code
> /review
 
# 3. Generate tests
> /test src/lib/favorites.ts
 
# 4. Generate documentation
> /doc src/lib/favorites.ts
 
# 5. Generate commit message
> /commit-msg

<!-- .claude/commands/ship.md -->
Run the following pre-commit checklist:
 
1. Run git diff --staged to see pending changes
2. Code review the changes (check security, performance, maintainability)
3. If issues are found, list them but don't auto-fix
4. If no issues, generate a commit message (format: type: description)
5. Output the final git commit command for my confirmation
 
Do NOT execute git commit automatically — only output the command.

git add .claude/commands/
git commit -m "feat: add team-shared Claude commands"

## Available Claude Commands
 
| Command | Purpose | Example |
|---------|---------|---------|
| `/review` | Code review | `/review` |
| `/test` | Generate tests | `/test src/lib/posts.ts` |
| `/gen-component` | Generate component | `/gen-component UserProfile` |
| `/commit-msg` | Generate commit message | `/commit-msg` |
| `/pr-desc` | Generate PR description | `/pr-desc` |

<!--
  Author: @jimmy
  Purpose: Generate React components following project conventions
  Updated: 2026-03-15
-->
Generate a React component for $ARGUMENTS...

<!-- .claude/commands/gen-component.md -->
Generate a React component named $ARGUMENTS.
 
Project tech stack:
- Next.js 16 (App Router) + TypeScript
- Tailwind CSS v4
- next-intl for i18n
 
Rules:
1. Default to Server Component unless the name contains "Client" or it needs interactivity
2. Place in the components/ directory
3. Use Tailwind CSS for styling, not CSS Modules
4. If the component needs text, use next-intl's useTranslations
5. Add necessary aria attributes for accessibility
6. Define Props with an interface named [ComponentName]Props
 
Check if a component with the same name already exists in components/ first.

<!-- .claude/commands/i18n-check.md -->
Check the project's internationalization completeness.
 
Steps:
1. Read messages/zh.json and messages/en.json
2. Compare key structures and find:
   - Keys in zh but missing from en
   - Keys in en but missing from zh
   - Keys with empty string values
3. Scan components/ and app/ for hardcoded Chinese or English text
4. Check for i18n keys used in code but not defined in message files
 
Output format:
- Missing keys list (note which file is missing them)
- Hardcoded text list (with file and line number)
- Undefined keys list

<!-- .claude/commands/gen-post.md -->
Create a new blog post scaffold.
 
Argument format: slug title
Example: /gen-post my-new-post My New Post
 
Based on $ARGUMENTS, create:
1. content/zh/[slug].mdx — Chinese version with frontmatter
2. content/en/[slug].mdx — English version with frontmatter
 
Frontmatter template:
---
title: "Title"
date: "current date YYYY-MM-DD"
description: TBD
tags: ["Uncategorized"]
---
 
## Introduction
 
[Start writing here]
 
After creating both files, remind me to fill in description and tags.

<!-- .claude/commands/a11y-audit.md -->
Perform an accessibility audit on $ARGUMENTS.
 
Checklist:
1. **Semantic HTML** — correct elements used (button vs div, nav vs div)
2. **ARIA attributes** — necessary aria-label, aria-describedby, role
3. **Keyboard navigation** — all interactive elements keyboard-accessible
4. **Focus management** — modals and dropdowns have focus traps
5. **Color contrast** — sufficient contrast between text and background
6. **Image alt text** — img has alt, decorative images have aria-hidden
7. **Dynamic content** — dynamically updated content has aria-live
 
Output each issue's location and fix suggestion.

# 1. Generate component scaffold
> /gen-component ReadingProgress
 
# Claude generates components/ReadingProgress.tsx
# with scroll listener, progress calculation, Tailwind styles
 
# 2. Check accessibility
> /a11y-audit components/ReadingProgress.tsx
 
# Claude flags: needs role="progressbar" and aria-valuenow
 
# 3. Generate tests
> /test components/ReadingProgress.tsx
 
# 4. Check i18n (if the component has text)
> /i18n-check
 
# 5. Review and commit
> /review
> /commit-msg

<!-- .claude/commands/flutter-feature.md -->
Create a complete directory structure for a new Flutter feature module.
 
Feature name: $ARGUMENTS
 
Create the following directories and files:
 
lib/features/[feature_name]/
  data/
    models/[feature_name]_model.dart
    repositories/[feature_name]_repository_impl.dart
    datasources/[feature_name]_remote_datasource.dart
  domain/
    entities/[feature_name].dart
    repositories/[feature_name]_repository.dart
    usecases/get_[feature_name].dart
  presentation/
    cubits/[feature_name]_cubit.dart
    cubits/[feature_name]_state.dart
    pages/[feature_name]_page.dart
    widgets/
 
Each file should contain only the basic skeleton (class definitions, necessary imports),
not full implementations.
 
Reference existing feature modules (e.g., lib/features/auth/) for code style.
Use snake_case for feature names.

<!-- .claude/commands/flutter-bloc.md -->
Generate Cubit and State classes for $ARGUMENTS.
 
Argument format: feature_name state_list
Example: /flutter-bloc favorites Initial,Loading,Loaded,Error
 
Rules:
1. Use flutter_bloc's Cubit (not Bloc, unless explicitly requested)
2. State uses sealed class (Dart 3)
3. Loaded state includes relevant data fields
4. Error state includes a String message field
5. Cubit methods: define signatures only, use TODO comments for bodies
6. Add equatable support
 
Files:
- lib/features/[feature_name]/presentation/cubits/[feature_name]_cubit.dart
- lib/features/[feature_name]/presentation/cubits/[feature_name]_state.dart
 
Reference existing Cubit implementations in the project for style.

<!-- .claude/commands/flutter-model.md -->
Generate Flutter data models based on the description.
 
$ARGUMENTS
 
Requirements:
1. Entity (domain layer): pure Dart class, no package dependencies
2. Model (data layer): extends Entity, adds fromJson/toJson
3. Use freezed or hand-written, depending on existing project style
4. If using Hive, add TypeAdapter
5. Include copyWith method
 
Check existing Model implementations in the project first for consistency.

<!-- .claude/commands/flutter-test.md -->
Generate tests for $ARGUMENTS.
 
Auto-detect test type:
- domain/usecases/ → unit test, mock Repository
- data/repositories/ → unit test, mock DataSource
- presentation/cubits/ → bloc_test, mock UseCase
- presentation/pages/ → widget test, mock Cubit
- presentation/widgets/ → widget test
 
Rules:
1. Use mocktail for mocking
2. Cubit tests use the bloc_test package
3. Widget tests use BlocProvider.value to inject mock Cubit
4. Test files mirror lib/ directory structure under test/
5. Organize with group/test blocks
 
Read the target file to understand dependencies first, then write tests.

<!-- .claude/commands/flutter-review.md -->
Code review the current git diff --staged with Flutter-specific checks.
 
In addition to general review (security, performance, maintainability), check:
 
1. **Architecture compliance** — Does it follow Clean Architecture dependency rules?
   - Domain layer must not depend on data or presentation layers
   - Data layer must not depend on presentation layer
2. **State management** — Is Cubit/Bloc used correctly?
   - Is State immutable?
   - Is data being manipulated directly in Widgets? (should go through Cubit)
3. **Widget optimization**
   - Unnecessary rebuilds (missing const, BlocSelector)?
   - Deeply nested Widget trees (suggest extraction)?
4. **Dart conventions**
   - Using Dart 3 features (patterns, sealed classes)?
   - Naming follows Dart conventions (lowerCamelCase, UpperCamelCase)?
5. **Dependency injection** — Properly registered in get_it?

# Step 1: Create the feature module skeleton
> /flutter-feature favorites
 
# Claude creates the full directory structure:
# lib/features/favorites/data/models/favorites_model.dart
# lib/features/favorites/data/repositories/favorites_repository_impl.dart
# lib/features/favorites/domain/entities/favorites.dart
# lib/features/favorites/domain/repositories/favorites_repository.dart
# lib/features/favorites/domain/usecases/get_favorites.dart
# lib/features/favorites/presentation/cubits/favorites_cubit.dart
# lib/features/favorites/presentation/cubits/favorites_state.dart
# lib/features/favorites/presentation/pages/favorites_page.dart
 
# Step 2: Generate data models
> /flutter-model Favorite entity: id(String), itemId(String),
  itemType(enum: article/video/podcast), createdAt(DateTime),
  userId(String). Use Hive for storage.
 
# Step 3: Generate Cubit
> /flutter-bloc favorites Initial,Loading,Loaded,Error
 
# Step 4: Implement business logic
> Implement the favorites UseCases:
  - AddFavorite: add to favorites, check if already favorited
  - RemoveFavorite: remove from favorites
  - GetFavorites: get favorites list with pagination
  - CheckFavorite: check if an item is favorited
 
# Step 5: Generate tests
> /flutter-test lib/features/favorites/domain/usecases/
> /flutter-test lib/features/favorites/presentation/cubits/favorites_cubit.dart
 
# Step 6: Code review
> /flutter-review