directive-synthesis

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Claude Code Command Builder

Claude Code 命令构建器

Purpose

用途

Guide users through creating effective Claude Code slash commands with proper structure, argument handling, and workflow design. Auto-invokes when users want to create or modify custom commands.

引导用户创建结构合理、参数处理完善、工作流设计规范的Claude Code斜杠命令。当用户想要创建或修改自定义命令时自动触发。

When to Use

适用场景

Auto-invoke when users mention:

Creating commands - "create command", "make command", "new slash command"
Command structure - "command template", "command format", "command frontmatter"
Arguments - "$ARGUMENTS", "$1", "$2", "command parameters", "positional args"
Workflows - "command workflow", "command steps", "command process"
Bash execution - "!
```
command
```
", "execute bash in command", "command with bash"

当用户提及以下内容时自动触发：

创建命令 - "创建命令"、"制作命令"、"新斜杠命令"
命令结构 - "命令模板"、"命令格式"、"命令frontmatter"
参数 - "$ARGUMENTS"、"$1"、"$2"、"命令参数"、"位置参数"
工作流 - "命令工作流"、"命令步骤"、"命令流程"
Bash执行 - "!
```
command
```
"、"在命令中执行Bash"、"包含Bash的命令"

Knowledge Base

知识库

Official docs:

.claude/skills/ai/claude-code/docs/code_claude_com/docs_en_slash-commands.md

Project guide:
```
.claude/docs/creating-components.md
```
Examples in repository:
```
.claude/commands/
```

官方文档：

.claude/skills/ai/claude-code/docs/code_claude_com/docs_en_slash-commands.md

项目指南：
```
.claude/docs/creating-components.md
```
仓库示例：
```
.claude/commands/
```

Process

流程

1. Gather Requirements

1. 收集需求

Ask the user:

Let me help you create a Claude Code slash command! I need a few details:

1. **Command name** (lowercase-with-hyphens):
   Example: deploy, review-pr, commit, analyze-tokens
   This will be invoked as: /your-command-name

2. **What does this command do?**
   Describe the workflow in 1-2 sentences.

3. **Does it need arguments?**
   - None (simple prompt)
   - All arguments: $ARGUMENTS
   - Positional: $1, $2, $3, etc.

4. **Does it need bash execution?**
   Commands that run before the slash command (e.g., !`git status`)

5. **Scope:**
   - Personal (`~/.claude/commands/`) - just for you
   - Project (`.claude/commands/`) - shared with team

6. **Namespace/subdirectory?**
   Example: git/, deploy/, testing/
   Helps organize related commands

询问用户：

让我帮你创建Claude Code斜杠命令！我需要以下几个细节：

1. **命令名称**（小写连字符格式）：
   示例：deploy、review-pr、commit、analyze-tokens
   调用方式为：/your-command-name

2. **该命令的功能是什么？**
   用1-2句话描述工作流。

3. **是否需要参数？**
   - 无（简单提示）
   - 所有参数：$ARGUMENTS
   - 位置参数：$1、$2、$3等

4. **是否需要执行Bash命令？**
   在斜杠命令之前运行的命令（例如：!`git status`）

5. **作用范围：**
   - 个人（`~/.claude/commands/`） - 仅你个人使用
   - 项目（`.claude/commands/`） - 团队共享

6. **命名空间/子目录？**
   示例：git/、deploy/、testing/
   有助于整理相关命令

2. Validate Input

2. 验证输入

Check the command name:

Must be valid filename (no spaces, special chars except hyphen)
Descriptive and memorable
Won't conflict with built-in commands
Use hyphens (not underscores)

Validate arguments:

Define expected arguments
Provide defaults if needed
Document argument order

检查命令名称：

必须是有效的文件名（无空格，除连字符外无特殊字符）
描述性强且易记
不会与内置命令冲突
使用连字符（而非下划线）

验证参数：

定义预期参数
必要时提供默认值
记录参数顺序

3. Determine Command Type

3. 确定命令类型

Simple Prompt (no frontmatter):

markdown

Analyze this code for performance issues and suggest optimizations.

With Arguments:

markdown

---
argument-hint: [file-path]
description: Analyze file for performance issues
---

Analyze the file at $1 for performance issues and suggest optimizations.

With Bash Execution:

markdown

---
allowed-tools: Bash(git status:*), Bash(git diff:*)
description: Create a git commit
---

简单提示（无frontmatter）：

markdown

分析此代码的性能问题并提出优化建议。

带参数：

markdown

---
argument-hint: [file-path]
description: 分析文件的性能问题
---

分析位于$1的文件的性能问题并提出优化建议。

带Bash执行：

markdown

---
allowed-tools: Bash(git status:*), Bash(git diff:*)
description: 创建Git提交
---

Current State

当前状态

Git status: !
```
git status
```
Staged changes: !
```
git diff --staged
```
Recent commits: !
```
git log --oneline -5
```

Git状态：!
```
git status
```
暂存变更：!
```
git diff --staged
```
最近提交：!
```
git log --oneline -5
```

Your Task

任务

Based on the above changes, create a git commit with a clear, conventional commit message.


**Full-Featured:**
```markdown
---
allowed-tools: Bash(npm run:*), Bash(git add:*), Bash(git commit:*)
argument-hint: [component-name]
description: Create a new React component with tests
model: sonnet
---

基于上述变更，创建一条清晰的符合规范的Git提交信息。


**全功能型：**
```markdown
---
allowed-tools: Bash(npm run:*), Bash(git add:*), Bash(git commit:*)
argument-hint: [component-name]
description: 创建带测试的React组件
model: sonnet
---

Create React Component

创建React组件

Component name: $1

Execute the following workflow:

Validate Input !

test -n "$1" && echo "Creating component: $1" || echo "Error: Component name required"

Check Existing Files !

ls src/components/$1.tsx 2>/dev/null || echo "Component does not exist"

Create Files Create the following files:

```
src/components/$1.tsx
```
```
src/components/$1.test.tsx
```
```
src/components/$1.module.css
```

Run Tests After creation, run: !
```
npm run test -- $1
```

undefined

组件名称：$1

执行以下工作流：

验证输入 !

test -n "$1" && echo "正在创建组件：$1" || echo "错误：需要组件名称"

检查现有文件 !

ls src/components/$1.tsx 2>/dev/null || echo "组件不存在"

创建文件 创建以下文件：

```
src/components/$1.tsx
```
```
src/components/$1.test.tsx
```
```
src/components/$1.module.css
```

运行测试 创建完成后，运行：!
```
npm run test -- $1
```

undefined

4. Generate Command File

4. 生成命令文件

Create command structure based on complexity:

Template for Simple Command:

markdown

Brief description of what the command does.

[Prompt instructions for Claude]

Template for Command with Frontmatter:

markdown

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

根据复杂度创建命令结构：

简单命令模板：

markdown

命令功能的简要描述。

[给Claude的提示指令]

带frontmatter的命令模板：

markdown

---
argument-hint: [arg1] [arg2]
description: /help菜单中显示的简要描述
allowed-tools: Bash(command:*), Read, Write
model: sonnet
disable-model-invocation: false
---

Command Name

命令名称

Usage: /command-name [args]

[Detailed instructions]

undefined

用法：/command-name [参数]

[详细说明]

undefined

5. Build Command Workflow

5. 构建命令工作流

Structure the workflow with clear steps:

markdown

Execute the following workflow:

1. **Step Name**
   ```bash
   # Bash command (if needed)
   command arg1 arg2

What this step does
Validation checks
Error handling

Next Step [Instructions for Claude]
- What to check
- How to proceed
- What to output
Final Step
- Summary of results
- Next actions for user
- Success criteria

undefined

用清晰的步骤构建工作流：

markdown

执行以下工作流：

1. **步骤名称**
   ```bash
   # 所需的Bash命令
   command arg1 arg2

此步骤的作用
验证检查
错误处理

下一步 [给Claude的指令]
- 需要检查的内容
- 执行方式
- 输出内容
最终步骤
- 结果总结
- 用户后续操作
- 成功标准

undefined

6. Add Argument Handling

6. 添加参数处理

All Arguments ($ARGUMENTS):

markdown

Fix issue #$ARGUMENTS following our coding standards.

User runs:

/fix-issue 123 high-priority

Becomes: "Fix issue #123 high-priority following our coding standards."

Positional Arguments ($1, $2, $3):

markdown

Review PR #$1 with priority $2 and assign to $3.
Focus on: $4

User runs:

/review-pr 456 high alice security

Becomes individual parameters you can reference separately.

With Defaults:

markdown

---
argument-hint: [environment] [branch]
---

Deploy to environment: ${1:-staging}
From branch: ${2:-main}

所有参数（$ARGUMENTS）：

markdown

按照我们的编码标准修复问题#$ARGUMENTS。

用户运行：

/fix-issue 123 high-priority

转换为："按照我们的编码标准修复问题#123 high-priority。"

位置参数（$1, $2, $3）：

markdown

评审编号为$1的PR，优先级为$2，并分配给$3。
重点关注：$4

用户运行：

/review-pr 456 high alice security

转换为可单独引用的独立参数。

带默认值：

markdown

---
argument-hint: [environment] [branch]
---

部署到环境：${1:-staging}
分支来源：${2:-main}

7. Add Bash Execution (if needed)

7. 添加Bash执行（如有需要）

Use

prefix to execute commands before processing:

markdown

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

使用

前缀在处理前执行命令：

markdown

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

Context

上下文

Current branch: !
```
git branch --show-current
```
Status: !
```
git status --short
```
Recent commits: !
```
git log --oneline -5
```

当前分支：!
```
git branch --show-current
```
状态：!
```
git status --short
```
最近提交：!
```
git log --oneline -5
```

Your Task

任务

[Instructions based on the above context]


**Important:**
- Must specify `allowed-tools` with specific Bash permissions
- Output is included in command context
- Commands run before Claude processes the prompt

[基于上述上下文的指令]


**重要提示：**
- 必须在`allowed-tools`中指定具体的Bash权限
- 输出内容会包含在命令上下文中
- 命令会在Claude处理提示之前运行

8. Add File References

8. 添加文件引用

Use

prefix to reference files:

markdown

Review the implementation in @src/utils/helpers.js

Compare @src/old-version.js with @src/new-version.js

Analyze all files in @src/components/

使用

前缀引用文件：

markdown

评审@src/utils/helpers.js中的实现

比较@src/old-version.js和@src/new-version.js

分析@src/components/中的所有文件

9. Configure Thinking Mode (if needed)

9. 配置思考模式（如有需要）

For complex problems, trigger extended thinking:

markdown

Carefully analyze the following code and think through...

Let's approach this step by step...

Consider all edge cases before implementing...

These keywords can trigger extended thinking mode.

对于复杂问题，触发扩展思考模式：

markdown

仔细分析以下代码并逐步思考...

让我们一步步解决这个问题...

在实现前考虑所有边缘情况...

这些关键词可以触发扩展思考模式。

10. Create the File

10. 创建文件

Save to correct location:

Personal command:

bash

~/.claude/commands/command-name.md
~/.claude/commands/category/command-name.md  # With namespace

Project command:

bash

.claude/commands/command-name.md
.claude/commands/category/command-name.md  # With namespace

保存到正确位置：

个人命令：

bash

~/.claude/commands/command-name.md
~/.claude/commands/category/command-name.md  # 带命名空间

项目命令：

bash

.claude/commands/command-name.md
.claude/commands/category/command-name.md  # 带命名空间

11. Test the Command

11. 测试命令

Provide testing instructions:

To test your command:
1. Restart Claude Code or start a new session
2. Type: /help
3. Find your command in the list
4. Try: /your-command-name [args]
5. Verify it behaves as expected

Test cases:

bash

undefined

提供测试说明：

测试你的命令：
1. 重启Claude Code或开启新会话
2. 输入：/help
3. 在列表中找到你的命令
4. 尝试：/your-command-name [参数]
5. 验证其行为是否符合预期

测试用例：

bash

undefined

No arguments

无参数

/your-command

With arguments

带参数

/your-command arg1 /your-command arg1 arg2

Edge cases

边缘情况

/your-command "" /your-command "with spaces"

undefined

/your-command "" /your-command "带空格"

undefined

Frontmatter Reference

Frontmatter 参考

Field	Purpose	Example
`argument-hint`	Show expected arguments in autocomplete	`[pr-number] [priority]`
`description`	Brief description for `/help` menu	`Review pull request`
`allowed-tools`	Tools command can use	`Bash(git:*), Read, Write`
`model`	Specific model to use	`claude-sonnet-4-5-20250929`
`disable-model-invocation`	Prevent SlashCommand tool from calling this	`true`

字段	用途	示例
`argument-hint`	在自动补全中显示预期参数	`[pr-number] [priority]`
`description`	/help菜单中的简要描述	`评审拉取请求`
`allowed-tools`	命令可使用的工具	`Bash(git:*), Read, Write`
`model`	使用的特定模型	`claude-sonnet-4-5-20250929`
`disable-model-invocation`	阻止SlashCommand工具调用此命令	`true`

Bash Tool Permissions

Bash工具权限

When using

prefix or needing bash execution:

markdown

---
allowed-tools: Bash(git add:*), Bash(git commit:*), Bash(git push:*)
---

Permission patterns:

```
Bash(git:*)
```
- All git commands
```
Bash(npm run:*)
```
- All npm run scripts
```
Bash(git add:*), Bash(git commit:*)
```
- Specific git commands

使用

前缀或需要Bash执行时：

markdown

---
allowed-tools: Bash(git add:*), Bash(git commit:*), Bash(git push:*)
---

权限模式：

```
Bash(git:*)
```
- 所有Git命令
```
Bash(npm run:*)
```
- 所有npm运行脚本
```
Bash(git add:*), Bash(git commit:*)
```
- 特定Git命令

Argument Patterns

参数模式

Pattern 1: All Arguments

模式1：所有参数

markdown

Run tests for: $ARGUMENTS

Usage:

/test users api database

Becomes: "Run tests for: users api database"

markdown

运行测试：$ARGUMENTS

用法：

/test users api database

转换为："运行测试：users api database"

Pattern 2: Positional

模式2：位置参数

markdown

Deploy $1 to $2 environment with tag $3

Usage:

/deploy my-app staging v1.2.3

Becomes: "Deploy my-app to staging environment with tag v1.2.3"

markdown

将$1部署到$2环境，标签为$3

用法：

/deploy my-app staging v1.2.3

转换为："将my-app部署到staging环境，标签为v1.2.3"

Pattern 3: Mixed

模式3：混合模式

markdown

---
argument-hint: <file> [rest of args]
---

Analyze file $1 for: $ARGUMENTS

Usage:

/analyze src/app.js performance security

Becomes: "Analyze file src/app.js for: src/app.js performance security" Note: $ARGUMENTS includes all args, so $1 is duplicated

Better approach:

markdown

Analyze file $1 for: ${2:+${@:2}}

This uses $1 separately and remaining args starting from $2

markdown

---
argument-hint: <file> [其余参数]
---

分析文件$1的以下内容：$ARGUMENTS

用法：

/analyze src/app.js performance security

转换为："分析文件src/app.js的以下内容：src/app.js performance security" 注意：$ARGUMENTS包含所有参数，因此$1会重复

更好的方式：

markdown

分析文件$1的以下内容：${2:+${@:2}}

此方式将$1单独使用，其余参数从$2开始

Pattern 4: With Defaults

模式4：带默认值

markdown

Environment: ${1:-production}
Verbose: ${2:-false}

markdown

环境：${1:-production}
详细模式：${2:-false}

Command Size Guidelines

命令大小指南

✅ Good: < 100 lines
⚠️ Warning: 100-150 lines
❌ Too large: > 250 lines (must refactor)

If too large:

Extract to external script
Split into multiple commands
Use sub-commands pattern

✅ 推荐： < 100行
⚠️ 警告： 100-150行
❌ 过大： > 250行（必须重构）

如果过大：

提取到外部脚本
拆分为多个命令
使用子命令模式

Common Command Types

常见命令类型

1. Git Workflow

1. Git工作流

markdown

---
allowed-tools: Bash(git:*)
description: Create conventional commit
---

markdown

---
allowed-tools: Bash(git:*)
description: 创建符合规范的提交
---

Context

上下文

Status: !
```
git status --short
```
Diff: !
```
git diff HEAD
```

Create a conventional commit message.

undefined

状态：!
```
git status --short
```
差异：!
```
git diff HEAD
```

创建一条符合规范的Git提交信息。

undefined

2. Code Generator

2. 代码生成器

markdown

---
argument-hint: [component-name]
description: Generate React component
---

Create a new React component named $1:
- Component file
- Test file
- Storybook story

markdown

---
argument-hint: [component-name]
description: 生成React组件
---

创建名为$1的新React组件：
- 组件文件
- 测试文件
- Storybook故事文件

3. Analysis Tool

3. 分析工具

markdown

---
argument-hint: [file-path]
description: Analyze code complexity
---

Analyze @$1 for:
- Cyclomatic complexity
- Code smells
- Improvement suggestions

markdown

---
argument-hint: [file-path]
description: 分析代码复杂度
---

分析@$1的以下内容：
- 圈复杂度
- 代码异味
- 改进建议

4. Deployment Helper

4. 部署助手

markdown

---
allowed-tools: Bash(npm:*), Bash(git:*)
argument-hint: [environment]
description: Deploy to environment
---

Deploy to ${1:-staging}:
1. Run tests: !`npm test`
2. Build: !`npm run build`
3. Deploy: !`npm run deploy:$1`

markdown

---
allowed-tools: Bash(npm:*), Bash(git:*)
argument-hint: [environment]
description: 部署到指定环境
---

部署到${1:-staging}：
1. 运行测试：!`npm test`
2. 构建：!`npm run build`
3. 部署：!`npm run deploy:$1`

5. Documentation Generator

5. 文档生成器

markdown

---
argument-hint: [file-pattern]
description: Generate API documentation
---

Generate documentation for: $1
Include:
- Function signatures
- Parameters
- Return types
- Examples

markdown

---
argument-hint: [file-pattern]
description: 生成API文档
---

为$1生成文档，包含：
- 函数签名
- 参数
- 返回类型
- 示例

Examples from TOON Formatter

TOON格式化工具示例

Simple version:

markdown

undefined

简化版：

markdown

undefined

Convert to TOON

转换为TOON格式

Convert the specified JSON file to TOON v2.0 format with automatic optimization and show token savings.

Usage: /convert-to-toon <file>


**Advanced version with bash:**
```markdown
---
allowed-tools: Bash(jq:*), Bash(.claude/utils/toon/zig-out/bin/toon:*)
argument-hint: <file> [--delimiter comma|tab|pipe]
description: Convert JSON to TOON format
---

将指定的JSON文件转换为TOON v2.0格式并自动优化，显示Token节省量。

用法：/convert-to-toon <file>


**带Bash的进阶版：**
```markdown
---
allowed-tools: Bash(jq:*), Bash(.claude/utils/toon/zig-out/bin/toon:*)
argument-hint: <file> [--delimiter comma|tab|pipe]
description: 将JSON转换为TOON格式
---

Convert to TOON

转换为TOON格式

File: $1 Delimiter: ${2:-comma}

Validate: !
```
test -f "$1" && jq empty "$1" 2>&1
```

Analyze: !

jq 'if type == "array" then length else 0 end' "$1"

Convert: !

.claude/utils/toon/zig-out/bin/toon encode "$1"

Show savings comparison

undefined

文件：$1 分隔符：${2:-comma}

验证：!
```
test -f "$1" && jq empty "$1" 2>&1
```

分析：!

jq 'if type == "array" then length else 0 end' "$1"

转换：!

.claude/utils/toon/zig-out/bin/toon encode "$1"

显示节省量对比

undefined

Troubleshooting

故障排除

Command Not Found

命令未找到

Check:

bash

undefined

检查：

bash

undefined

List all commands

列出所有命令

ls ~/.claude/commands/.md ls .claude/commands/.md

Verify filename

验证文件名

ls .claude/commands/your-command.md


**Remember:**
- Filename (without `.md`) becomes command name
- Hyphens in filename become hyphens in command
- Case-sensitive on Linux/Mac

ls .claude/commands/your-command.md


**注意：**
- 文件名（不含.md）即为命令名称
- 文件名中的连字符即为命令中的连字符
- 在Linux/Mac系统中区分大小写

Arguments Not Working

参数不生效

Debug:

markdown

Debug: $ARGUMENTS
Debug $1: "$1"
Debug $2: "$2"

Run command and check output to see what's being passed.

调试：

markdown

调试：$ARGUMENTS
调试$1："$1"
调试$2："$2"

运行命令并检查输出，查看传递的内容。

Bash Commands Not Executing

Bash命令未执行

Check:

```
allowed-tools
```
includes correct Bash permissions
Using
```
!
```
prefix:
```
!
```
command``
Backticks are correct: `command` not 'command'
Command is allowed by permissions

检查：

```
allowed-tools
```
包含正确的Bash权限
使用了
```
!
```
前缀：
```
!
```
command``
反引号正确：`command` 而非 'command'
命令在权限允许范围内

Command Not in /help

命令未出现在/help中

Possible reasons:

File not in correct location
File doesn't have
```
.md
```
extension
Syntax error in frontmatter
Need to restart Claude Code

可能原因：

文件不在正确位置
文件没有.md扩展名
frontmatter存在语法错误
需要重启Claude Code

Best Practices

最佳实践

DO:

建议：

✅ Provide clear argument hints ✅ Include usage examples ✅ Handle errors gracefully ✅ Show progress for long operations ✅ Document expected behavior ✅ Test with various inputs ✅ Use descriptive command names

✅ 提供清晰的参数提示 ✅ 包含用法示例 ✅ 优雅处理错误 ✅ 显示长操作的进度 ✅ 记录预期行为 ✅ 使用各种输入测试 ✅ 使用描述性的命令名称

DON'T:

避免：

❌ Make commands too complex (>250 lines) ❌ Forget to specify allowed-tools for Bash ❌ Use unclear argument names ❌ Skip error handling ❌ Hardcode values (use arguments) ❌ Forget to test edge cases

❌ 命令过于复杂（>250行） ❌ 忘记为Bash指定allowed-tools权限 ❌ 使用不清晰的参数名称 ❌ 跳过错误处理 ❌ 硬编码值（使用参数代替） ❌ 忘记测试边缘情况

Comparison: Commands vs Skills

对比：命令 vs 技能

Use Commands when:

You want explicit control (manual invocation)
Simple, repetitive prompts
Specific workflow steps
Frequently-used templates

Use Skills when:

Claude should auto-detect need
Complex, multi-file workflows
Comprehensive domain knowledge
Team needs standardized expertise

Can use both:

Command invokes skill explicitly
Skill activates automatically
Command provides quick access
Skill provides deep capability

使用命令的场景：

需要显式控制（手动触发）
简单、重复的提示
特定的工作流步骤
频繁使用的模板

使用技能的场景：

Claude应自动检测需求
复杂的多文件工作流
全面的领域知识
团队需要标准化的专业能力

可结合使用：

命令显式调用技能
技能自动激活
命令提供快速访问方式
技能提供深度能力

Resources

资源

Official Command Docs:

.claude/skills/ai/claude-code/docs/code_claude_com/docs_en_slash-commands.md

Project Component Guide:
```
.claude/docs/creating-components.md
```
Command Examples:
```
.claude/commands/
```
directory
Skills vs Commands: Section in slash-commands.md

官方命令文档：

.claude/skills/ai/claude-code/docs/code_claude_com/docs_en_slash-commands.md

项目组件指南：
```
.claude/docs/creating-components.md
```
命令示例：
```
.claude/commands/
```
目录
技能vs命令： 斜杠命令文档中的相关章节