slash-command-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Slash Command Builder

斜杠命令构建器

Create effective custom slash commands for Claude Code with proper structure, dynamic features, and best practices.

遵循合理结构、动态特性与最佳实践，为Claude Code创建高效的自定义斜杠命令。

Quick Reference

快速参考

Command File Location:

Project (shared):
```
.claude/commands/name.md
```
Personal (individual):
```
~/.claude/commands/name.md
```

Dynamic Features:

Arguments:
```
$ARGUMENTS
```
(all) or
```
$1
```
,
```
$2
```
,
```
$3
```
(positional)
Bash execution: [execute: command] (requires
```
allowed-tools: Bash(...)
```
)
File references:
```
@path/to/file
```

Frontmatter: Optional YAML with

description

allowed-tools

argument-hint

model

命令文件位置:

项目级（共享）：
```
.claude/commands/name.md
```
个人级（独立）：
```
~/.claude/commands/name.md
```

动态特性:

参数：
```
$ARGUMENTS
```
（全部参数）或
```
$1
```
、
```
$2
```
、
```
$3
```
（位置参数）

Bash执行：

[execute: command]

（需配置

allowed-tools: Bash(...)

）

文件引用：
```
@path/to/file
```

前置配置（Frontmatter）：可选YAML配置，包含

description

、

allowed-tools

、

argument-hint

、

model

字段

The Slash Command Creation Workflow

斜杠命令创建流程

Phase 1: Requirements Gathering

阶段1：需求收集

Use AskUserQuestion to understand what they need:

What should the command do?
- What task or prompt does it automate?
- What's the expected outcome?
Who will use it?
- Just you (personal command)
- Your team (project command)
Does it need dynamic inputs?
- Fixed prompt (no arguments)
- User-provided values (arguments needed)
- Context from system (bash execution)
- File contents (file references)
What tools should it access?
- Read-only analysis (Read, Grep, Glob)
- Git operations (Bash(git:*))
- Full access (default, no restrictions)

通过询问用户问题明确需求：

该命令的功能是什么？
- 它要自动化执行什么任务或提示？
- 预期结果是什么？
谁会使用该命令？
- 仅你自己（个人命令）
- 你的团队（项目命令）
是否需要动态输入？
- 固定提示（无需参数）
- 用户提供的数值（需要参数）
- 系统上下文（Bash执行）
- 文件内容（文件引用）
需要访问哪些工具？
- 只读分析（Read、Grep、Glob）
- Git操作（Bash(git:*)）
- 完全访问（默认，无限制）

Phase 2: Choose Scope

阶段2：选择作用域

Personal Command (

~/.claude/commands/

Your individual shortcuts
Experimental commands
Personal workflow automation
Not shared with team

Project Command (

.claude/commands/

Team-shared commands
Standardized workflows
Committed to git
Available to all team members

个人命令（

~/.claude/commands/

）:

个人专属快捷命令
实验性命令
个人工作流自动化
不与团队共享

项目命令（

.claude/commands/

）:

团队共享命令
标准化工作流
提交至Git版本控制
所有团队成员均可使用

Phase 3: Design the Structure

阶段3：设计结构

Basic command structure:

markdown

---
description: Brief description for /help
allowed-tools: Optional tool restrictions
argument-hint: Optional argument guidance
---

[Your prompt here]

Decision tree:

Start with basic prompt
Add arguments if needed ($ARGUMENTS or $1/$2)
Add bash execution if context needed ([execute: command])
Add file references if analyzing files (@path)
Add frontmatter for description and restrictions

基础命令结构：

markdown

---
description: 显示在/help中的简短描述
allowed-tools: 可选工具限制
argument-hint: 可选参数指引
---

[你的提示内容]

决策树:

从基础提示开始
按需添加参数（$ARGUMENTS或$1/$2）
如需上下文则添加Bash执行（
```
[execute: command]
```
）
如需分析文件则添加文件引用（
```
@path
```
）
添加前置配置以补充描述与限制

Phase 4: Implementation

阶段4：实现

Step 1: Create the file

步骤1：创建文件

bash

undefined

bash

undefined

For project commands

项目命令

touch .claude/commands/your-command.md

For personal commands

个人命令

touch ~/.claude/commands/your-command.md


The filename (without .md) becomes the command name.

touch ~/.claude/commands/your-command.md


文件名（不含.md后缀）即为命令名称。

Step 2: Write the command

步骤2：编写命令

Use templates from templates/ directory:

basic-command.md - Simple prompt
with-arguments.md - With dynamic inputs
with-bash.md - With bash execution
with-files.md - With file references
complex-command.md - All features combined

使用templates/目录中的模板：

basic-command.md - 简单提示模板
with-arguments.md - 带动态输入的模板
with-bash.md - 带Bash执行的模板
with-files.md - 带文件引用的模板
complex-command.md - 包含所有特性的模板

Step 3: Add frontmatter (recommended)

步骤3：添加前置配置（推荐）

yaml

---
description: What this command does (appears in /help)
allowed-tools: Read, Grep, Glob  # Optional restrictions
argument-hint: [arg1] [arg2]     # Optional user guidance
---

yaml

---
description: 该命令的功能（会显示在/help中）
allowed-tools: Read, Grep, Glob  # 可选工具限制
argument-hint: [arg1] [arg2]     # 可选用户指引
---

Phase 5: Testing

阶段5：测试

Verify command appears:
```
/help
```
Look for your command in the list.
Test basic invocation:
```
/your-command
```
Test with arguments (if applicable):
```
/your-command arg1 arg2
```
Test bash execution (if applicable):
- Verify commands execute
- Check output appears in prompt
Test file references (if applicable):
- Verify files load correctly
- Check paths resolve
Team testing (for project commands):
- Have teammates try it
- Gather feedback
- Iterate based on usage

验证命令是否显示:
```
/help
```
在列表中查找你的命令。
测试基础调用:
```
/your-command
```
测试带参数的调用（如适用）:
```
/your-command arg1 arg2
```
测试Bash执行（如适用）:
- 验证命令是否执行
- 检查输出是否显示在提示中
测试文件引用（如适用）:
- 验证文件是否正确加载
- 检查路径是否解析正常
团队测试（针对项目命令）:
- 让团队成员试用
- 收集反馈
- 根据使用情况迭代优化

Phase 6: Iteration

阶段6：迭代优化

Start simple, add complexity incrementally:

First: Basic prompt without dynamic features
Test: Verify it works
Add: One feature (arguments OR bash OR files)
Test: Verify new feature works
Repeat: Add next feature if needed

Don't try to add all features at once. Build incrementally.

从简单版本开始，逐步增加复杂度：

初始版本：无动态特性的基础提示
测试：验证功能正常
添加特性：一次添加一个功能（参数、Bash或文件引用）
测试：验证新功能正常
重复：按需添加下一个功能

不要一次性添加所有功能，逐步构建。

Common Command Patterns

常见命令模式

Pattern 1: Code Analysis

模式1：代码分析

markdown

---
description: Analyze code for [specific criteria]
allowed-tools: Read, Grep, Glob
argument-hint: [file-or-directory]
---

Analyze @$1 for:
1. [Criterion 1]
2. [Criterion 2]
3. [Criterion 3]

Provide specific findings with examples.

markdown

---
description: 按[特定标准]分析代码
allowed-tools: Read, Grep, Glob
argument-hint: [文件或目录]
---

分析@$1，重点关注：
1. [标准1]
2. [标准2]
3. [标准3]

提供包含示例的具体结论。

Pattern 2: Git Workflow

模式2：Git工作流

markdown

---
description: [Git operation] with context
allowed-tools: Bash(git:*)
---

markdown

---
description: 带上下文的[Git操作]
allowed-tools: Bash(git:*)
---

Current State

当前状态

Branch: [execute: git branch --show-current] Status: [execute: git status --short]

分支：[execute: git branch --show-current] 状态：[execute: git status --short]

Task

任务

[What to do with this context]

undefined

[基于此上下文执行的操作]

undefined

Pattern 3: Code Generation

模式3：代码生成

markdown

---
description: Generate [artifact] following patterns
allowed-tools: Read, Grep, Glob, Write
argument-hint: [what-to-generate]
---

markdown

---
description: 遵循既定模式生成[产物]
allowed-tools: Read, Grep, Glob, Write
argument-hint: [要生成的内容]
---

Existing Patterns

现有模式

@[relevant examples]

@[相关示例文件]

Task

任务

Generate $ARGUMENTS following the patterns above.

undefined

遵循上述模式生成$ARGUMENTS指定的内容。

undefined

Pattern 4: Deep Analysis

模式4：深度分析

markdown

---
description: Deep analysis of [topic]
---

Think deeply about $ARGUMENTS considering:
1. [Aspect 1]
2. [Aspect 2]
3. [Aspect 3]

[Extended thinking triggered by keywords]

markdown

---
description: 对[主题]进行深度分析
---

结合以下维度深入思考$ARGUMENTS：
1. [维度1]
2. [维度2]
3. [维度3]

[由关键词触发的扩展思考]

Real-World Examples

实际案例

See examples/ for complete working examples:

git-workflows.md - Commit, PR, branch commands
code-analysis.md - Review, security, performance
code-generation.md - Tests, docs, boilerplate

查看examples/目录获取完整可用示例：

git-workflows.md - 提交、PR、分支相关命令
code-analysis.md - 代码评审、安全、性能分析
code-generation.md - 测试、文档、脚手架生成

Advanced Features

高级特性

Arguments: $ARGUMENTS vs $1/$2

参数：$ARGUMENTS vs $1/$2

Use
$ARGUMENTS
when:

You want all input as a single block
Free-form text (messages, descriptions)
Don't need to reference parts separately

Use
$1
,
$2
,
$3
when:

You need structured parameters
Different parts used in different places
Want to provide defaults for missing args

Example:

markdown

undefined

使用
$ARGUMENTS
的场景:

需要将所有输入作为单个块处理
自由格式文本（消息、描述）
无需单独引用各部分内容

使用
$1
、
$2
、
$3
的场景:

需要结构化参数
不同部分用于不同场景
可为缺失的参数提供默认值

示例:

markdown

undefined

$ARGUMENTS approach

$ARGUMENTS方式

Explain $ARGUMENTS in detail.

详细解释$ARGUMENTS。

Positional approach

位置参数方式

Review PR #$1 with priority $2 assigned to $3.

undefined

评审编号为$1的PR，优先级为$2，负责人为$3。

undefined

Bash Execution

Bash执行

Execute commands BEFORE the prompt runs:

markdown

---
allowed-tools: Bash(git:*)
---

Current branch: [execute: git branch --show-current]
Recent commits: [execute: git log --oneline -5]

Requirements:

Must include
```
allowed-tools: Bash(...)
```
Use [execute: command] syntax (backticks required)
Output is captured and included in prompt

Security: Limit bash access with specific tool patterns:

yaml

allowed-tools: Bash(git:*)          # Git only
allowed-tools: Bash(npm:*), Bash(git:*)  # npm and git

在提示运行前执行命令：

markdown

---
allowed-tools: Bash(git:*)
---

当前分支：[execute: git branch --show-current]
最近提交：[execute: git log --oneline -5]

要求:

必须在前置配置中包含
```
allowed-tools: Bash(...)
```
使用
```
[execute: command]
```
语法（需包含反引号）
命令输出会被捕获并包含在提示中

安全建议：通过特定工具模式限制Bash访问权限：

yaml

allowed-tools: Bash(git:*)          # 仅允许Git命令
allowed-tools: Bash(npm:*), Bash(git:*)  # 允许npm和Git命令

File References

文件引用

Include file contents with

prefix:

markdown

Review @src/auth/login.js for security issues.

Features:

Automatic CLAUDE.md inclusion from file's directory hierarchy
Works with relative or absolute paths
Directories show listing (not contents)

使用

前缀引入文件内容：

markdown

分析@src/auth/login.js中的安全问题。

特性:

自动包含文件所在目录层级中的CLAUDE.md
支持相对路径和绝对路径
目录会显示文件列表（而非内容）

Frontmatter Configuration

前置配置（Frontmatter）

Complete frontmatter options:

yaml

---
description: Brief description (required for /help and SlashCommand tool)
allowed-tools: Read, Grep, Glob, Bash(git:*)  # Optional restrictions
argument-hint: [file] [priority]              # Optional guidance
model: claude-3-5-haiku-20241022              # Optional model override
disable-model-invocation: false               # Optional, prevent auto-calling
---

完整的前置配置选项：

yaml

---
description: 简短描述（/help和SlashCommand工具必填）
allowed-tools: Read, Grep, Glob, Bash(git:*)  # 可选工具限制
argument-hint: [file] [priority]              # 可选参数指引
model: claude-3-5-haiku-20241022              # 可选模型覆盖配置
disable-model-invocation: false               # 可选，禁止自动调用模型
---

Best Practices

最佳实践

Always include description
- Helps team understand command purpose
- Required for SlashCommand tool
- Appears in
```
/help
```
Use argument-hint for clarity
- Shows expected inputs
- Self-documenting commands
- Reduces user confusion
Limit allowed-tools when appropriate
- Read-only commands:
```
Read, Grep, Glob
```
- Git-only:
```
Bash(git:*)
```
- Enhances security and safety
Structure complex commands
- Use sections (Context, Task, Constraints)
- Makes prompts easier to understand
- Follows clear flow
Reference project conventions
- Include
```
@CLAUDE.md
```
  for standards
- Reference example files
- Ensures consistency
Test incrementally
- Start simple, add features one at a time
- Test each addition before next
- Don't debug multiple features simultaneously
Organize with subdirectories
- Group related commands
- Cleaner file structure
- Easier to maintain
Commit project commands
- Share with team via git
- Version control for commands
- Team benefits from your work

始终添加description
- 帮助团队理解命令用途
- SlashCommand工具必填
- 会显示在
```
/help
```
  中
使用argument-hint提升清晰度
- 显示预期输入格式
- 命令自文档化
- 减少用户困惑
按需限制allowed-tools
- 只读命令：
```
Read, Grep, Glob
```
- Git专属命令：
```
Bash(git:*)
```
- 提升安全性
结构化复杂命令
- 使用章节划分（上下文、任务、约束）
- 让提示更易理解
- 遵循清晰的逻辑流程
参考项目约定
- 引入
```
@CLAUDE.md
```
  以遵循项目标准
- 参考示例文件
- 确保一致性
逐步测试
- 从简单版本开始，逐个添加功能
- 每次添加后都进行测试
- 不要同时调试多个功能
使用子目录组织命令
- 按功能分组相关命令
- 更整洁的文件结构
- 更易于维护
提交项目命令至Git
- 通过Git与团队共享
- 对命令进行版本控制
- 让团队受益于你的工作

Common Issues and Solutions

常见问题与解决方案

Issue: Command doesn't appear in /help

问题：命令未出现在/help中

Causes:

File not in correct location
Missing .md extension
Filename has invalid characters

Solutions:

Check file is in
```
.claude/commands/
```
or
```
~/.claude/commands/
```
Verify
```
.md
```
extension
Use lowercase-with-hyphens for filename

原因:

文件位置不正确
缺少.md后缀
文件名包含无效字符

解决方案:

确认文件位于
```
.claude/commands/
```
或
```
~/.claude/commands/
```
目录
验证文件带有.md后缀
文件名使用小写连字符格式（lowercase-with-hyphens）

Issue: Arguments not replacing

问题：参数未被替换

Causes:

Typo in placeholder (
```
$ARGUMENT
```
instead of
```
$ARGUMENTS
```
)
Not passing arguments when invoking
Wrong syntax

Solutions:

Double-check spelling:
```
$ARGUMENTS
```
,
```
$1
```
,
```
$2
```
Test with:
```
/command arg1 arg2
```
Verify placeholder exists in template

原因:

占位符拼写错误（如
```
$ARGUMENT
```
而非
```
$ARGUMENTS
```
）
调用命令时未传入参数
语法错误

解决方案:

仔细检查拼写：
```
$ARGUMENTS
```
、
```
$1
```
、
```
$2
```
使用
```
/command arg1 arg2
```
测试
验证模板中存在对应的占位符

Issue: Bash commands not executing

问题：Bash命令未执行

Causes:

Missing
```
allowed-tools: Bash(...)
```
in frontmatter
Wrong syntax (missing backticks)
Command fails when run

Solutions:

Add frontmatter:
```
allowed-tools: Bash(command:*)
```
Use correct syntax: [execute: command]
Test command in terminal first

原因:

前置配置中缺少
```
allowed-tools: Bash(...)
```
语法错误（缺少反引号）
命令本身执行失败

解决方案:

添加前置配置：
```
allowed-tools: Bash(command:*)
```
使用正确语法：
```
[execute: command]
```
先在终端测试命令是否可正常执行

Issue: File references not working

问题：文件引用无效

Causes:

Missing
```
@
```
prefix
File doesn't exist
Wrong path

Solutions:

Use
```
@path/to/file
```
syntax
Verify file exists:
```
ls path/to/file
```
Try absolute path if relative fails

原因:

缺少
```
@
```
前缀
文件不存在
路径错误

解决方案:

使用
```
@path/to/file
```
语法
验证文件存在：
```
ls path/to/file
```
相对路径无效时尝试使用绝对路径

Slash Commands vs Skills

斜杠命令 vs Skills

When to use each:

Use Slash Commands	Use Skills
Manual invocation (you decide when)	Automatic discovery (Claude decides when)
Simple prompt templates	Complex multi-file workflows
Quick, focused operations	Broad capabilities
Single .md file	Directory with multiple files

Example:

Slash command:
```
/commit
```
- You invoke when ready to commit
Skill:
```
skill-builder
```
- Claude discovers when you mention Skills

Both complement each other in your workflow.

适用场景对比:

使用斜杠命令	使用Skills
手动触发（由用户决定时机）	自动触发（由Claude决定时机）
简单提示模板	复杂多文件工作流
快速、聚焦的操作	广泛的功能覆盖
单个.md文件	包含多个文件的目录

示例:

斜杠命令：
```
/commit
```
- 准备提交时手动调用
Skill：
```
skill-builder
```
- 当你提及Skills时由Claude自动触发

二者可在工作流中互补使用。

Complete Syntax Reference

完整语法参考

For detailed syntax documentation, see reference/syntax-guide.md.

For best practices and patterns, see reference/best-practices.md.

For troubleshooting help, see reference/troubleshooting.md.

详细语法文档请查看reference/syntax-guide.md。

最佳实践与模式请查看reference/best-practices.md。

故障排查帮助请查看reference/troubleshooting.md。

Tips for Effective Commands

高效命令创建技巧

Start with the simplest version that works
Add complexity only when needed (YAGNI principle)
Test with real scenarios before sharing
Include clear descriptions in frontmatter
Use tool restrictions for safety
Reference project conventions with file refs
Gather context with bash execution
Structure prompts with clear sections
Provide examples in argument-hint
Iterate based on usage - improve over time

从可用的最简版本开始
仅在需要时增加复杂度（遵循YAGNI原则）
在共享前用真实场景测试
在前置配置中添加清晰描述
使用工具限制提升安全性
通过文件引用遵循项目约定
通过Bash执行收集上下文
用清晰章节结构化提示
在argument-hint中提供示例
基于使用情况迭代优化

Next Steps

后续步骤

After creating a command:

Test thoroughly with various inputs
Share with team (if project command)
Document in CLAUDE.md if it's a pattern others should know
Create related commands for connected workflows
Refine based on feedback - commands improve with use

Remember: Slash commands are user-invoked prompt templates. Start simple, test frequently, and add features incrementally. The best commands are clear, focused, and solve real workflow problems.

创建命令后：

全面测试：使用多种输入场景测试
团队共享（如果是项目命令）
在CLAUDE.md中记录：如果是其他成员需要了解的模式
创建关联命令：为相关工作流配套命令
基于反馈优化：命令会随使用逐步完善

注意：斜杠命令是用户触发的提示模板。从简单版本开始，频繁测试，逐步添加功能。优秀的命令应清晰、聚焦，能解决实际工作流中的问题。