command-development

为 Claude Code 开发命令

注意： .claude/commands/ 目录是旧版格式。对于新技能，请使用 .claude/skills/<name>/SKILL.md 目录格式。两者的加载方式完全相同——唯一的区别是文件布局。有关推荐格式，请参阅 skill-development 技能。

概述

斜杠命令是以 Markdown 文件形式定义的常用提示词，由 Claude 在交互式会话中执行。理解命令结构、frontmatter 选项和动态特性，有助于创建强大、可复用的工作流。

关键概念：

• 命令的 Markdown 文件格式
• 用于配置的 YAML frontmatter
• 动态参数和文件引用
• 用于上下文的 Bash 执行
• 命令组织与命名空间

命令基础

什么是斜杠命令？

斜杠命令是一个包含提示词的 Markdown 文件，Claude 在被调用时执行该提示词。命令提供：

• 可复用性：定义一次，重复使用
• 一致性：标准化常见工作流
• 可共享性：在团队或项目间分发
• 高效性：快速访问复杂提示词

关键：命令是写给 Claude 的指令

命令是为 Agent 使用而编写，而非供人阅读。

当用户调用 /command-name 时，命令内容会成为 Claude 的指令。请将命令编写为面向 Claude 的指令，说明要做什么，而不是面向用户的消息。

正确方式（给 Claude 的指令）：

Review this code for security vulnerabilities including:

- SQL injection
- XSS attacks
- Authentication issues

Provide specific line numbers and severity ratings.

错误方式（给用户的消息）：

This command will review your code for security issues.
You'll receive a report with vulnerability details.

第一个示例告诉 Claude 要做什么。第二个示例告诉用户将会发生什么，但没有指示 Claude。请始终使用第一种方式。

命令位置

项目命令（与团队共享）：

• 位置：.claude/commands/
• 范围：在特定项目中可用
• 标签：在 /help 中显示为 "(project)"
• 用途：团队工作流、项目特定任务

个人命令（随处可用）：

• 位置：~/.claude/commands/
• 范围：在所有项目中可用
• 标签：在 /help 中显示为 "(user)"
• 用途：个人工作流、跨项目实用工具

插件命令（随插件捆绑）：

• 位置：plugin-name/commands/
• 范围：安装插件后可用
• 标签：在 /help 中显示为 "(plugin-name)"
• 用途：插件特定功能

文件格式

基本结构

命令是扩展名为 .md 的 Markdown 文件：

.claude/commands/
├── review.md           # /review command
├── test.md             # /test command
└── deploy.md           # /deploy command

简单命令：

Review this code for security vulnerabilities including:

- SQL injection
- XSS attacks
- Authentication bypass
- Insecure data handling

基本命令无需 frontmatter。

使用 YAML Frontmatter

使用 YAML frontmatter 添加配置：

---
description: Review code for security issues
allowed-tools: Read, Grep, Bash(git:*)
model: sonnet
---

Review this code for security vulnerabilities...

YAML Frontmatter 字段

description

用途： 在 /help 中显示的简短描述 类型： 字符串 默认值： 命令提示词的第一行

---
description: Review pull request for code quality
---

最佳实践： 清晰、可操作的描述（不超过 60 个字符）

allowed-tools

用途： 指定命令可以使用的工具 类型： 字符串或数组 默认值： 继承自会话

---
allowed-tools: Read, Write, Edit, Bash(git:*)
---

模式：

• Read, Write, Edit - 特定工具
• Bash(git:*) - 仅限 git 命令的 Bash
• * - 所有工具（很少需要）

使用场景： 命令需要特定工具访问权限时

model

用途： 指定用于执行命令的模型 类型： 字符串（sonnet、opus、haiku） 默认值： 继承自会话

---
model: haiku
---

使用场景：

• haiku - 快速、简单的命令
• sonnet - 标准工作流
• opus - 复杂分析

argument-hint

用途： 记录预期参数，用于自动补全 类型： 字符串 默认值： 无

---
argument-hint: [pr-number] [priority] [assignee]
---

好处：

• 帮助用户理解命令参数
• 提升命令可发现性
• 记录命令接口

disable-model-invocation

用途： 阻止 SlashCommand 工具以编程方式调用命令 类型： 布尔值 默认值： false

---
disable-model-invocation: true
---

使用场景： 命令只能手动调用时

动态参数

使用 $ARGUMENTS

将所有参数捕获为单个字符串：

---
description: Fix issue by number
argument-hint: [issue-number]
---

Fix issue #$ARGUMENTS following our coding standards and best practices.

用法：

> /fix-issue 123
> /fix-issue 456

展开为：

Fix issue #123 following our coding standards...
Fix issue #456 following our coding standards...

使用位置参数

使用 $1、$2、$3 等捕获各个参数：

---
description: Review PR with priority and assignee
argument-hint: [pr-number] [priority] [assignee]
---

Review pull request #$1 with priority level $2.
After review, assign to $3 for follow-up.

用法：

> /review-pr 123 high alice

展开为：

Review pull request #123 with priority level high.
After review, assign to alice for follow-up.

组合参数

混合使用位置参数和剩余参数：

Deploy $1 to $2 environment with options: $3

用法：

> /deploy api staging --force --skip-tests

展开为：

Deploy api to staging environment with options: --force --skip-tests

文件引用

使用 @ 语法

在命令中包含文件内容：

---
description: Review specific file
argument-hint: [file-path]
---

Review @$1 for:

- Code quality
- Best practices
- Potential bugs

用法：

> /review-file src/api/users.ts

效果： Claude 在处理命令前读取 src/api/users.ts

多个文件引用

引用多个文件：

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

Identify:

- Breaking changes
- New features
- Bug fixes

静态文件引用

引用已知文件而无需参数：

Review @package.json and @tsconfig.json for consistency

Ensure:

- TypeScript version matches
- Dependencies are aligned
- Build configuration is correct

命令中的 Bash 执行

命令可以内联执行 bash 命令，以在 Claude 处理命令前动态收集上下文。这对于包含仓库状态、环境信息或项目特定上下文非常有用。

何时使用：

• 包含动态上下文（git status、环境变量等）
• 收集项目/仓库状态
• 构建上下文感知的工作流

实现细节： 有关完整语法、示例和最佳实践，请参阅 references/plugin-features-reference.md 中关于 bash 执行的章节。该参考包含确切的语法和多个可用的示例，以避免执行问题

命令组织

扁平结构

适用于小型命令集的简单组织方式：

.claude/commands/
├── build.md
├── test.md
├── deploy.md
├── review.md
└── docs.md

适用场景： 5-15 个命令，没有明确的分类

命名空间结构

在子目录中组织命令：

.claude/commands/
├── ci/
│   ├── build.md        # /build (project:ci)
│   ├── test.md         # /test (project:ci)
│   └── lint.md         # /lint (project:ci)
├── git/
│   ├── commit.md       # /commit (project:git)
│   └── pr.md           # /pr (project:git)
└── docs/
    ├── generate.md     # /generate (project:docs)
    └── publish.md      # /publish (project:docs)

优势：

• 按类别进行逻辑分组
• 在 /help 中显示命名空间
• 更容易找到相关命令

适用场景： 15 个以上命令，分类明确

最佳实践

命令设计

1. 单一职责： 一个命令，一个任务
2. 清晰的描述： 在 /help 中一目了然
3. 显式依赖： 需要时使用 allowed-tools
4. 文档化参数： 始终提供 argument-hint
5. 一致的命名： 使用动词-名词模式（review-pr、fix-issue）

参数处理

1. 验证参数： 在提示词中检查必需参数
2. 提供默认值： 参数缺失时建议默认值
3. 文档化格式： 说明预期的参数格式
4. 处理边界情况： 考虑缺失或无效的参数

---
argument-hint: [pr-number]
---

$IF($1,
Review PR #$1,
Please provide a PR number. Usage: /review-pr [number]
)

文件引用

1. 显式路径： 使用清晰的文件路径
2. 检查存在性： 优雅地处理缺失的文件
3. 相对路径： 使用项目相对路径
4. Glob 支持： 考虑使用 Glob 工具处理模式匹配

Bash 命令

1. 限制范围： 使用 Bash(git:*) 而非 Bash(*)
2. 安全命令： 避免破坏性操作
3. 处理错误： 考虑命令失败的情况
4. 保持快速： 长时间运行的命令会拖慢调用

文档

1. 添加注释： 解释复杂的逻辑
2. 提供示例： 在注释中展示用法
3. 列出要求： 记录依赖项
4. 版本化命令： 注明破坏性变更

---
description: Deploy application to environment
argument-hint: [environment] [version]
---



Deploy application to $1 environment using version $2...

常见模式

审查模式

---
description: Review code changes
allowed-tools: Read, Bash(git:*)
---

Files changed: !`git diff --name-only`

Review each file for:

1. Code quality and style
2. Potential bugs or issues
3. Test coverage
4. Documentation needs

Provide specific feedback for each file.

测试模式

---
description: Run tests for specific file
argument-hint: [test-file]
allowed-tools: Bash(npm:*)
---

Run tests: !`npm test $1`

Analyze results and suggest fixes for failures.

文档模式

---
description: Generate documentation for file
argument-hint: [source-file]
---

Generate comprehensive documentation for @$1 including:

- Function/class descriptions
- Parameter documentation
- Return value descriptions
- Usage examples
- Edge cases and errors

工作流模式

---
description: Complete PR workflow
argument-hint: [pr-number]
allowed-tools: Bash(gh:*), Read
---

PR #$1 Workflow:

1. Fetch PR: !`gh pr view $1`
2. Review changes
3. Run checks
4. Approve or request changes

故障排除

命令未出现：

• 检查文件是否在正确的目录中
• 确认存在 .md 扩展名
• 确保 Markdown 格式有效
• 重启 Claude Code

参数不工作：

• 验证 $1、$2 语法正确
• 检查 argument-hint 与用法匹配
• 确保没有多余空格

Bash 执行失败：

• 检查 allowed-tools 是否包含 Bash
• 验证反引号中的命令语法
• 先在终端中测试命令
• 检查所需权限

文件引用不工作：

• 验证 @ 语法正确
• 检查文件路径是否有效
• 确保允许 Read 工具
• 使用绝对路径或项目相对路径

插件特定功能

CLAUDE_PLUGIN_ROOT 变量

插件命令可以访问 ${CLAUDE_PLUGIN_ROOT}，这是一个解析为插件绝对路径的环境变量。

用途：

• 以便携方式引用插件文件
• 执行插件脚本
• 加载插件配置
• 访问插件模板

基本用法：

---
description: Analyze using plugin script
allowed-tools: Bash(node:*)
---

Run analysis: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js $1`

Review results and report findings.

常见模式：

# Execute plugin script

!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/script.sh`

# Load plugin configuration

@${CLAUDE_PLUGIN_ROOT}/config/settings.json

# Use plugin template

@${CLAUDE_PLUGIN_ROOT}/templates/report.md

# Access plugin resources

@${CLAUDE_PLUGIN_ROOT}/docs/reference.md

为什么使用它：

• 适用于所有安装方式
• 可在不同系统之间移植
• 无需硬编码路径
• 对于多文件插件必不可少

插件命令组织

插件命令从 commands/ 目录自动发现：

plugin-name/
├── commands/
│   ├── foo.md              # /foo (plugin:plugin-name)
│   ├── bar.md              # /bar (plugin:plugin-name)
│   └── utils/
│       └── helper.md       # /helper (plugin:plugin-name:utils)
└── plugin.json

命名空间的好处：

• 逻辑化的命令分组
• 显示在 /help 输出中
• 避免名称冲突
• 组织相关命令

命名约定：

• 使用描述性的动作名称
• 避免通用名称（test、run）
• 考虑使用插件专属前缀
• 多词名称使用连字符

插件命令模式

基于配置的模式：

---
description: Deploy using plugin configuration
argument-hint: [environment]
allowed-tools: Read, Bash(*)
---

Load configuration: @${CLAUDE_PLUGIN_ROOT}/config/$1-deploy.json

Deploy to $1 using configuration settings.
Monitor deployment and report status.

基于模板的模式：

---
description: Generate docs from template
argument-hint: [component]
---

Template: @${CLAUDE_PLUGIN_ROOT}/templates/docs.md

Generate documentation for $1 following template structure.

多脚本模式：

---
description: Complete build workflow
allowed-tools: Bash(*)
---

Build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh`
Test: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test.sh`
Package: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/package.sh`

Review outputs and report workflow status.

详细模式请参阅 references/plugin-features-reference.md。

与插件组件集成

命令可以与其他插件组件集成，实现强大的工作流。

Agent 集成

启动插件 Agent 来处理复杂任务：

---
description: Deep code review
argument-hint: [file-path]
---

Initiate comprehensive review of @$1 using the code-reviewer agent.

The agent will analyze:

- Code structure
- Security issues
- Performance
- Best practices

Agent uses plugin resources:

- ${CLAUDE_PLUGIN_ROOT}/config/rules.json
- ${CLAUDE_PLUGIN_ROOT}/checklists/review.md

要点：

• Agent 必须存在于 plugin/agents/ 目录中
• Claude 使用 Task 工具启动 Agent
• 记录 Agent 的能力
• 引用 Agent 使用的插件资源

Skill 集成

利用插件 Skill 获取专业知识：

---
description: Document API with standards
argument-hint: [api-file]
---

Document API in @$1 following plugin standards.

Use the api-docs-standards skill to ensure:

- Complete endpoint documentation
- Consistent formatting
- Example quality
- Error documentation

Generate production-ready API docs.

要点：

• Skill 必须存在于 plugin/skills/ 目录中
• 提及 Skill 名称以触发调用
• 记录 Skill 的用途
• 说明 Skill 提供的内容

Hook 协调

设计与插件 Hook 协同工作的命令：

• 命令可以为 Hook 准备待处理的状态
• Hook 在工具事件发生时自动执行
• 命令应记录预期的 Hook 行为
• 指导 Claude 解读 Hook 输出

有关与 Hook 协调的命令示例，请参阅 references/plugin-features-reference.md

多组件工作流

组合 Agent、Skill 和脚本：

---
description: Comprehensive review workflow
argument-hint: [file]
allowed-tools: Bash(node:*), Read
---

Target: @$1

Phase 1 - Static Analysis:
!`node ${CLAUDE_PLUGIN_ROOT}/scripts/lint.js $1`

Phase 2 - Deep Review:
Launch code-reviewer agent for detailed analysis.

Phase 3 - Standards Check:
Use coding-standards skill for validation.

Phase 4 - Report:
Template: @${CLAUDE_PLUGIN_ROOT}/templates/review.md

Compile findings into report following template.

适用场景：

• 复杂的多步骤工作流
• 利用多个插件能力
• 需要专门的分析
• 需要结构化的输出

验证模式

命令应在处理之前验证输入和资源。

参数验证

---
description: Deploy with validation
argument-hint: [environment]
---

Validate environment: !`echo "$1" | grep -E "^(dev|staging|prod)$" || echo "INVALID"`

If $1 is valid environment:
Deploy to $1
Otherwise:
Explain valid environments: dev, staging, prod
Show usage: /deploy [environment]

文件存在性检查

---
description: Process configuration
argument-hint: [config-file]
---

Check file exists: !`test -f $1 && echo "EXISTS" || echo "MISSING"`

If file exists:
Process configuration: @$1
Otherwise:
Explain where to place config file
Show expected format
Provide example configuration

插件资源验证

---
description: Run plugin analyzer
allowed-tools: Bash(test:*)
---

Validate plugin setup:

- Script: !`test -x ${CLAUDE_PLUGIN_ROOT}/bin/analyze && echo "✓" || echo "✗"`
- Config: !`test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo "✓" || echo "✗"`

If all checks pass, run analysis.
Otherwise, report missing components.

错误处理

---
description: Build with error handling
allowed-tools: Bash(*)
---

Execute build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh 2>&1 || echo "BUILD_FAILED"`

If build succeeded:
Report success and output location
If build failed:
Analyze error output
Suggest likely causes
Provide troubleshooting steps

最佳实践：

• 在命令中尽早验证
• 提供有用的错误消息
• 建议纠正措施
• 优雅地处理边缘情况

---

有关 frontmatter 字段的详细规范，请参阅 references/frontmatter-reference.md。 有关插件专属功能和模式，请参阅 references/plugin-features-reference.md。 有关命令模式示例，请参阅 examples/ 目录。