slash-command-builder

斜杠命令构建器

为 Claude Code 创建有效的自定义斜杠命令，并采用恰当的结构、动态功能和最佳实践。

快速参考

命令文件位置：

• 项目（共享）：.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

斜杠命令创建工作流

阶段 1：收集需求

使用 AskUserQuestion 了解他们的需求：

1. 命令应该做什么？

   • 它要自动执行什么任务或提示词？
   • 预期结果是什么？

2. 谁会使用它？

   • 仅你自己（个人命令）
   • 你的团队（项目命令）

3. 是否需要动态输入？

   • 固定提示词（无参数）
   • 用户提供的值（需要参数）
   • 来自系统的上下文（Bash 执行）
   • 文件内容（文件引用）

4. 它应该访问哪些工具？

   • 只读分析（Read、Grep、Glob）
   • Git 操作（Bash(git:*)）
   • 完全访问权限（默认，无限制）

阶段 2：选择范围

个人命令（~/.claude/commands/）：

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

项目命令（.claude/commands/）：

• 团队共享的命令
• 标准化工作流
• 提交到 git
• 所有团队成员均可使用

阶段 3：设计结构

基本命令结构：

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

[Your prompt here]

决策树：

1. 从基本提示词开始
2. 按需添加参数（$ARGUMENTS 或 $1/$2）
3. 需要上下文时添加 Bash 执行（[execute: command]）
4. 需要分析文件时添加文件引用（@path）
5. 添加 frontmatter，设置说明和限制

阶段 4：实现

步骤 1：创建文件

# For project commands
touch .claude/commands/your-command.md

# For personal commands
touch ~/.claude/commands/your-command.md

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

步骤 2：编写命令

使用 templates/ 目录中的模板：

• basic-command.md - 简单提示词
• with-arguments.md - 使用动态输入
• with-bash.md - 使用 Bash 执行
• with-files.md - 使用文件引用
• complex-command.md - 组合使用所有功能

步骤 3：添加 frontmatter（推荐）

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

阶段 5：测试

1. 确认命令已显示：

   /help
   

   在列表中查找你的命令。

2. 测试基本调用：

   /your-command
   

3. 测试带参数的调用（如适用）：

   /your-command arg1 arg2
   

4. 测试 Bash 执行（如适用）：

   • 确认命令能够执行
   • 检查输出是否出现在提示词中

5. 测试文件引用（如适用）：

   • 确认文件能够正确加载
   • 检查路径是否解析正确

6. 团队测试（用于项目命令）：

   • 请队友试用
   • 收集反馈
   • 根据使用情况进行迭代

阶段 6：迭代

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

1. 首先：使用不含动态功能的基本提示词
2. 测试：确认其正常工作
3. 添加：一个功能（参数、Bash 或文件，三选一）
4. 测试：确认新功能正常工作
5. 重复：按需添加下一个功能

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

常见命令模式

模式 1：代码分析

---
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.

模式 2：Git 工作流

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

## Current State

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

## Task

[What to do with this context]

模式 3：代码生成

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

## Existing Patterns

@[relevant examples]

## Task

Generate $ARGUMENTS following the patterns above.

模式 4：深度分析

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

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

[Extended thinking triggered by keywords]

实际示例

完整的可用示例请参阅 examples/：

• git-workflows.md - 提交、PR、分支命令
• code-analysis.md - 审查、安全、性能
• code-generation.md - 测试、文档、样板代码

高级功能

参数：$ARGUMENTS 与 $1/$2

在以下情况下使用 $ARGUMENTS：

• 你希望将所有输入作为一个整体
• 输入为自由格式文本（消息、描述）
• 不需要分别引用其中的部分

在以下情况下使用 $1、$2、$3：

• 你需要结构化参数
• 不同部分会用于不同位置
• 希望为缺失的参数提供默认值

示例：

# $ARGUMENTS approach
Explain $ARGUMENTS in detail.

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

Bash 执行

在提示词运行之前执行命令：

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

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

要求：

1. 必须包含 allowed-tools: Bash(...)
2. 使用 [execute: command] 语法（必须使用反引号）
3. 输出会被捕获并包含在提示词中

安全性：使用特定的工具模式限制 Bash 访问：

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

文件引用

使用 @ 前缀包含文件内容：

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

功能：

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

Frontmatter 配置

完整的 frontmatter 选项：

---
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
---

最佳实践

1. 始终包含描述

   • 帮助团队了解命令的用途
   • SlashCommand 工具必需
   • 显示在 /help 中

2. 使用 argument-hint 提高清晰度

   • 显示预期输入
   • 让命令自带说明
   • 减少用户困惑

3. 酌情限制 allowed-tools

   • 只读命令：Read, Grep, Glob
   • 仅 Git：Bash(git:*)
   • 提升安全性

4. 对复杂命令进行结构化

   • 使用各个部分（Context、Task、Constraints）
   • 让提示词更易于理解
   • 遵循清晰的流程

5. 引用项目规范

   • 包含 @CLAUDE.md 以遵循标准
   • 引用示例文件
   • 确保一致性

6. 逐步测试

   • 从简单开始，每次添加一个功能
   • 在添加下一个功能前测试当前功能
   • 不要同时调试多个功能

7. 使用子目录进行整理

   • 将相关命令分组
   • 让文件结构更整洁
   • 更易于维护

8. 提交项目命令

   • 通过 git 与团队共享
   • 对命令进行版本控制
   • 让团队受益于你的工作

常见问题和解决方案

问题：命令没有显示在 /help 中

原因：

• 文件位置不正确
• 缺少 .md 扩展名
• 文件名含有无效字符

解决方案：

• 检查文件是否位于 .claude/commands/ 或 ~/.claude/commands/
• 确认 .md 扩展名
• 文件名使用小写字母和连字符

问题：参数没有被替换

原因：

• 占位符拼写错误（写成 $ARGUMENT 而不是 $ARGUMENTS）
• 调用时没有传递参数
• 语法错误

解决方案：

• 仔细检查拼写：$ARGUMENTS、$1、$2
• 使用以下命令测试：/command arg1 arg2
• 确认模板中存在占位符

问题：Bash 命令没有执行

原因：

• frontmatter 中缺少 allowed-tools: Bash(...)
• 语法错误（缺少反引号）
• 命令运行失败

解决方案：

• 添加 frontmatter：allowed-tools: Bash(command:*)
• 使用正确的语法：[execute: command]
• 先在终端中测试命令

问题：文件引用不起作用

原因：

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

解决方案：

• 使用 @path/to/file 语法
• 确认文件存在：ls path/to/file
• 如果相对路径无效，尝试使用绝对路径

Slash 命令与 Skills

选择使用方式：

使用 Slash 命令	使用 Skills
手动调用（由你决定何时调用）	自动发现（由 Claude 决定何时调用）
简单的提示词模板	复杂的多文件工作流
快速、专注的操作	广泛的能力
单个 .md 文件	包含多个文件的目录

示例：

• Slash 命令：/commit - 准备好提交时由你调用
• Skill：skill-builder - 当你提到 Skills 时由 Claude 发现

两者在工作流中相辅相成。

完整语法参考

详细语法文档请参阅 reference/syntax-guide.md。

最佳实践和模式请参阅 reference/best-practices.md。

故障排除帮助请参阅 reference/troubleshooting.md。

高效命令的技巧

1. 从可用的最简单版本开始
2. 仅在需要时增加复杂度（YAGNI 原则）
3. 分享前用真实场景进行测试
4. 在 frontmatter 中加入清晰的描述
5. 使用工具限制来保障安全
6. 通过文件引用项目约定
7. 通过 bash 执行来收集上下文
8. 用清晰的章节组织提示词
9. 在 argument-hint 中提供示例
10. 根据使用情况反复迭代 - 随时间不断改进

后续步骤

创建命令后：

1. 充分测试各种输入
2. 与团队分享（如果是项目命令）
3. 如果它是其他人应该了解的模式，请在 CLAUDE.md 中记录
4. 为相关工作流创建配套命令
5. 根据反馈进行改进 - 命令会在使用中不断完善

---

请记住：斜杠命令是由用户调用的提示词模板。从简单开始，频繁测试，并逐步添加功能。最好的命令清晰、专注，能够解决实际工作流问题。