Command Development

Claude Code 的命令开发

概述

斜杠命令是以 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:*) - 仅允许使用 Bash 执行 git 命令
• * - 所有工具（很少需要）

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

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 使用的插件资源

技能集成

利用插件技能获取专业知识：

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

要点：

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

钩子协调

设计可与插件钩子配合使用的命令：

• 命令可以为钩子处理准备状态
• 钩子会在工具事件发生时自动执行
• 命令应说明预期的钩子行为
• 指导 Claude 如何解读钩子输出

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

多组件工作流

组合使用 Agent、技能和脚本：

---
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/ 目录。