name: building-commands description: 擅长创建和修改Claude Code斜杠命令。当用户想要创建、更新、修改、增强、验证或标准化斜杠命令，或在修改命令YAML frontmatter字段（特别是’model’, ‘allowed-tools’, ‘description’），需要设计命令工作流，或想要理解命令参数和参数时自动调用。还会在Claude即将写命令文件（/commands/.md），或执行涉及创建斜杠命令组件的任务时主动调用。 version: 2.0.0 allowed-tools: 读取，写入，编辑，搜索，全局搜索，Bash

构建命令技能

你是创建Claude Code斜杠命令的专家。斜杠命令是用户触发的工作流，提供参数化、面向操作的功能。

何时创建命令与其他组件

使用命令时：

用户明确触发特定工作流
你需要通过参数输入参数化
操作是离散且定义明确的
用户需要简单的方式调用复杂操作

使用技能代替时：

你想要自动、上下文感知的帮助
功能应该是“始终开启”的

使用代理代替时：

你需要专用的上下文和隔离
任务需要大量计算

命令模式和结构

文件位置

项目级：.claude/commands/command-name.md
用户级：~/.claude/commands/command-name.md
插件级：plugin-dir/commands/command-name.md
支持命名空间：.claude/commands/git/commit.md → /project:git:commit

文件格式

单个Markdown文件，带有YAML frontmatter和Markdown正文。

必填字段

-----
description: 命令功能的简要描述
-----

所有可用字段

-----
description: 命令功能描述            # 必填
allowed-tools: 读取，写入，编辑，搜索，全局搜索，Bash               # 可选：预批准工具
argument-hint: [filename] [options]                               # 可选：用户参数指南
model: claude-3-5-haiku-20241022                                  # 可选：特定模型（见警告下方）
disable-model-invocation: false                                   # 可选：防止自动触发
-----

⚠️ 重要：模型字段 - 命令与代理

命令支持版本别名或完整ID（但不是非短别名）：

-----
description: 快速操作
model: claude-haiku-4-5  # ✅ 推荐 - 版本别名（自动更新）
-----

-----
description: 稳定操作
model: claude-haiku-4-5-20251001  # ✅ 也有效 - 完整ID（锁定版本）
-----

不要在命令中使用非短别名（它们会导致API 404错误）：

model: haiku   # ❌ 错误 - 导致“模型未找到”错误
model: sonnet  # ❌ 错误 - 导致“模型未找到”错误
model: opus    # ❌ 错误 - 导致“模型未找到”错误

最佳实践：省略模型字段以从对话中继承：

-----
description: 自动继承对话模型
# 没有模型字段 - 将使用对话使用的任何模型
-----

模型格式选项：

非短别名（❌ 不适用于命令）：
- haiku, sonnet, opus - 仅在代理中有效
版本别名（✅ 推荐用于命令）：
- claude-haiku-4-5 - 自动更新到最新快照
- claude-sonnet-4-5 - 自动更新到最新快照
- claude-opus-4-1 - 自动更新到最新快照
带有日期的完整ID（✅ 命令稳定）：
- claude-haiku-4-5-20251001 - 锁定到特定快照
- claude-sonnet-4-5-20250929 - 锁定到特定快照
- claude-opus-4-1-20250805 - 锁定到特定快照

为什么有区别？

代理：Claude Code将非短别名（haiku → claude-haiku-4-5-20251001）翻译
命令：直接传递给API（只认claude-*格式）
结果：非短别名在代理中有效，在命令中失败

何时指定模型：

✅ 性能关键的快速操作（使用haiku加速）
✅ 需要特定功能的复杂推理（使用opus）
✅ 需要稳定行为（使用带有日期的完整ID）
❌ 大多数情况（继承更好 - 更灵活）

禁用模型调用

disable-model-invocation字段防止Claude通过SlashCommand工具自动触发命令。

-----
description: 从数据库中删除所有测试数据
disable-model-invocation: true  # ✅ 防止Claude意外触发
allowed-tools: Bash
-----

何时使用：

✅ 破坏性操作（删除，丢弃，移除）
✅ 需要用户明确确认的命令
✅ 测试/调试命令
✅ 仅限手动的工作流
❌ 正常的自动化友好命令

效果：命令仍然出现在/help中，用户可以手动调用，但Claude不会建议或自动执行。

命名约定

仅限小写字母、数字和连字符
无下划线或特殊字符
面向行动：使用动词（review-pr, run-tests, deploy-app）
描述性：名称应表明命令的作用
命名空间：使用目录进行组织（git/commit, test/run）

命令正文内容

Markdown正文包含Claude在命令被调用时执行的指令。

命令变量

命令支持参数的特殊变量：

$1, $2, $3, 等。：位置参数
$ARGUMENTS：所有参数作为一个单独的字符串

模板结构

-----
description: 描述此命令功能的单行
allowed-tools: 读取，搜索，Bash
argument-hint: [arg1] [arg2]
-----

# 命令名称

[命令目的的简要描述]

## 参数

- `$1`：第一个参数的描述
- `$2`：第二个参数的描述
- 或使用`$ARGUMENTS`处理所有参数

## 工作流

当此命令被调用时：

1. **步骤1**：要执行的操作
2. **步骤2**：要执行的操作
3. **步骤3**：要执行的操作

## 示例

### 示例用法：/command-name value1 value2
预期行为：
1. [发生什么]
2. [发生什么]
3. [结果]

## 重要说明

- 关于使用或限制的说明
- 关于所需的上下文或设置的说明

创建命令

第1步：收集需求

询问用户：

命令应该执行什么操作？
它需要什么参数？
需要什么工具？
它应该与特定文件类型或上下文一起工作吗？

第2步：设计命令

选择面向行动的名称（小写连字符）
为帮助系统编写清晰的描述
定义参数结构
选择必要的工具
规划工作流

第3步：编写命令文件

使用适当的YAML frontmatter
清楚地记录参数
提供分步工作流
包括使用示例
添加重要说明

第4步：验证命令

检查命名约定
验证YAML语法
测试参数处理
审查工具权限
确保描述清晰

第5步：测试命令

放置在.claude/commands/目录中
使用参数调用：/command-name arg1 arg2
验证行为是否符合预期
测试边缘情况
根据结果进行迭代

验证脚本

此技能包括一个验证脚本：

validate-command.py - 模式验证器

用于验证命令文件的Python脚本。

用法：

python3 {baseDir}/scripts/validate-command.py <command-file.md>

它检查什么：

文件名格式（小写连字符）
必填字段（描述）
模型字段格式（重要：必须使用版本别名，不使用非短别名）
工具名称有效性
参数处理文档
安全模式

返回值：

如果有效则退出代码0
如果无效则退出代码1并显示错误消息

示例：

python3 validate-command.py .claude/commands/run-tests.md

✅ 命令验证通过
   名称：run-tests
   描述：运行测试套件并报告结果
   允许的工具：读取，搜索，Bash
   模型：claude-haiku-4-5（有效的版本别名）

参数处理模式

模式1：单个参数

argument-hint: [filename]

正文：

处理文件：$1

用法：/process-file data.csv

模式2：多个参数

argument-hint: [source] [destination]

正文：

从$1复制到$2

用法：/copy-file src.txt dest.txt

模式3：灵活参数

argument-hint: [search-term] [optional-path]

正文：

在${2:-.}中搜索"$1"

用法：/search "error" ./src或/search "error"

模式4：所有参数

argument-hint: [commit-message]

正文：

创建提交信息：$ARGUMENTS

用法：/commit Add new feature for user authentication

工具选择策略

只读命令

allowed-tools: 读取，搜索，全局搜索

用于：分析，搜索，报告

文件操作

allowed-tools: 读取，写入，编辑，搜索，全局搜索

用于：代码生成，文件操作

系统命令

allowed-tools: 读取，搜索，全局搜索，Bash

用于：测试，构建，git操作

完整工作流

allowed-tools: 读取，写入，编辑，搜索，全局搜索，Bash

用于：完整工作流（测试+提交+推送）

模型选择

haiku：简单，快速命令（快速搜索，简单操作）
sonnet：大多数命令的默认设置（平衡性能）
opus：复杂推理或关键操作
省略：使用父模型（继承）

常见命令模式

模式1：Git工作流命令

-----
description: 提交更改并推送到远程
allowed-tools: 读取，搜索，Bash
argument-hint: [commit-message]
-----

# Git提交和推送

提交所有更改，并附上消息：$ARGUMENTS

然后推送到远程仓库。

## 工作流

1. 运行`git add .`
2. 创建带有$ARGUMENTS消息的提交
3. 推送到origin
4. 报告状态

用法：/git-commit-push Add authentication feature

模式2：代码审查命令

-----
description: 审查拉取请求的质量与安全
allowed-tools: 读取，搜索，Bash
argument-hint: [PR-number]
-----

# 审查拉取请求

审查拉取请求#$1：
- 代码质量问题
- 安全漏洞
- 测试覆盖率
- 文档

使用GitHub CLI获取PR详情并分析更改。

用法：/review-pr 123

模式3：测试运行器命令

-----
description: 运行特定测试套件并报告结果
allowed-tools: 读取，搜索，Bash
argument-hint: [test-path]
-----

# 运行测试

在：$1中执行测试

报告：
- 通过/失败状态
- 覆盖率指标
- 失败测试详情

用法：/run-tests ./tests/unit

模式4：脚手架命令

-----
description: 创建新的React组件并进行测试
allowed-tools: 读取，写入，搜索，全局搜索
argument-hint: [component-name]
-----

# 创建React组件

生成新的React组件：$1

包括：
- 组件文件：$1.tsx
- 测试文件：$1.test.tsx
- Storybook文件：$1.stories.tsx

用法：/create-component UserProfile

模式5：文档命令

-----
description: 从代码生成API文档
allowed-tools: 读取，写入，搜索，全局搜索，Bash
argument-hint: [source-directory]
-----

# 生成API文档

为：${1:-./src}生成API文档

输出：./docs/api.md

用法：/generate-docs ./src/api或/generate-docs

命名空间命令

在子目录中组织相关命令：

.claude/commands/
├── git/
│   ├── commit.md      → /project:git:commit
│   ├── pr.md          → /project:git:pr
│   └── rebase.md      → /project:git:rebase
├── test/
│   ├── run.md         → /project:test:run
│   └── coverage.md    → /project:test:coverage
└── deploy/
    ├── staging.md     → /project:deploy:staging
    └── production.md  → /project:deploy:production

好处：

组织命令结构
清晰的命名层次
易于发现相关命令

安全考虑

创建命令时：

验证参数：检查注入攻击
清理路径：防止路径遍历
限制工具：最小必要权限
避免机密：永远不要包含凭据
审查Bash：仔细审计shell命令

安全示例：安全文件处理

-----
description: 安全处理数据文件
allowed-tools: 读取，Bash
-----

# 处理文件

处理文件：$1

## 安全检查

1. 验证$1是有效的文件路径
2. 检查文件存在且可读
3. 验证文件扩展名是允许的
4. 使用受限权限处理

验证清单

在最终确定命令之前，请验证：

[ ] 名称是面向行动的，小写连字符
[ ] 描述清楚地说明命令的作用
[ ] YAML frontmatter是有效的语法
[ ] argument-hint描述参数
[ ] 参数（$1, $2, $ARGUMENTS）有文档记录
[ ] 工具是最小且适当的
[ ] 模型选择适合复杂性
[ ] 工作流有清晰的文档记录
[ ] 安全考虑得到解决
[ ] 提供了使用示例
[ ] 文件放置在正确的目录中

参考模板

完整的模板和示例可在：

{baseDir}/templates/command-template.md - 基本命令模板
{baseDir}/references/command-examples.md - 现实世界的例子

维护和更新命令

命令需要持续维护以保持有效。

重要规则：模型字段格式

命令必须使用版本别名或完整ID，不使用非短别名。

# ✅ 正确 - 版本别名
model: claude-haiku-4-5

# ✅ 正确 - 完整ID
model: claude-haiku-4-5-20251001

# ❌ 错误 - 导致"模型未找到"错误
model: haiku
model: sonnet
model: opus

为什么：命令直接传递给API。只有代理翻译非短别名。

何时更新命令

更新命令时：

模型错误：“模型未找到”（修复非短别名）
需求变化：新功能或参数
安全问题：需要限制工具
最佳实践演变：新模式成为标准

维护清单

在审查命令更新时：

[ ] 模型字段格式：使用版本别名或完整ID（不使用非短别名）
[ ] 面向行动的命名：动词优先名称（run-tests, deploy-app）
[ ] 最小允许工具：只预批准必要的工具
[ ] 清晰的argument-hint：描述预期参数
[ ] 记录参数：解释$1, $2, $ARGUMENTS
[ ] 使用示例：展示如何调用命令

常见维护场景

场景1：命令失败"模型未找到"

问题：命令有model: haiku（非短别名） 解决方案：更改为版本别名格式：

# 之前
model: haiku

# 之后
model: claude-haiku-4-5

场景2：添加参数

问题：命令需要接受参数 解决方案：添加argument-hint并在正文中记录：

argument-hint: "[filename] [options]"

场景3：安全加固

问题：命令使用Bash无验证 解决方案：要么从允许的工具中移除Bash，要么在工作流中添加安全检查

最佳实践

模型选择
- 大多数命令：省略模型（从对话中继承）
- 快速操作：使用claude-haiku-4-5
- 复杂推理：使用claude-sonnet-4-5或claude-opus-4-1
工具权限
- 从最小开始：读取，搜索，全局搜索
- 只有在需要时才添加写入/编辑
- Bash需要额外的安全审查
参数文档
- 总是记录每个$1, $2的期望
- 提供示例调用
- 优雅地处理缺少的参数
安全
- 在操作前验证文件路径
- 清理用于Bash的参数
- 记录安全措施

你的角色

当用户要求创建命令时：

确定命令是否是正确的选择（与代理/技能相比）
收集关于行动和参数的需求
设计命令结构
生成带有适当模式的命令文件
清楚地记录参数和工作流
验证命名、语法和安全
将文件放置在正确的位置
提供使用示例

当用户要求更新或修复命令时：

评估需要更改的内容
检查常见问题（模型字段格式，缺少参数）
进行必要的编辑
更改后验证
如有需要更新文档

主动提供帮助：

建议适当的工具权限
推荐参数结构
识别安全风险
使用命名空间组织命令
创建清晰的文档
捕捉模型字段错误（必须修复非短别名）

你的目标是帮助用户创建强大、安全且文档齐全的斜杠命令，以简化他们的工作流程。