# Claude Code 自定义斜杠命令指南

## 概述

斜杠命令允许你将常用的提示定义为 Markdown 文件，Claude Code 可以直接执行这些命令。命令支持项目级和个人级两种范围，并通过目录结构支持命名空间。

**基本语法：**
```
/<命令名称> [参数]
```

## 命令类型与存储位置

| 命令类型 | 存储位置 | 说明 | 在 `/help` 中显示 |
|---------|----------|------|-------------------|
| 项目命令 | `.claude/commands/` | 存储在项目仓库中，与团队共享 | `(project)` |
| 个人命令 | `~/.claude/commands/` | 存储在用户目录，跨所有项目可用 | `(user)` |

> **优先级**：当项目命令和个人命令同名时，**项目命令优先**。

## 快速开始

### 创建项目命令

```bash
# 创建命令目录
mkdir -p .claude/commands

# 创建一个简单的优化命令
echo "分析这段代码的性能问题并提出优化建议：" > .claude/commands/optimize.md
```

### 创建个人命令

```bash
# 创建个人命令目录
mkdir -p ~/.claude/commands

# 创建安全审查命令
echo "审查这段代码的安全漏洞：" > ~/.claude/commands/security-review.md
```

## Frontmatter 配置

在命令文件开头使用 YAML frontmatter 来配置命令行为：

```yaml
---
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
argument-hint: [message]
description: 创建一个 git 提交
model: claude-3-5-haiku-20241022
disable-model-invocation: false
---

命令内容在这里
```

### 配置参数说明

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `allowed-tools` | 命令可使用的工具列表 | 继承自当前对话 |
| `argument-hint` | 参数提示信息（显示在自动补全中） | 无 |
| `description` | 命令的简短描述 | 提示内容的第一行 |
| `model` | 指定使用的模型 | 继承自当前对话 |
| `disable-model-invocation` | 是否禁止 SlashCommand 工具调用此命令 | false |

## 参数用法

### 获取所有参数：`$ARGUMENTS`

```markdown
# .claude/commands/fix-issue.md
修复问题 #$ARGUMENTS，遵循我们的编码规范
```

**使用方式：**
```
> /fix-issue 123 high-priority
# $ARGUMENTS 会被替换为: "123 high-priority"
```

### 获取单个参数：`$1`, `$2`, `$3` ...

```markdown
# .claude/commands/review-pr.md
审查 PR #$1，优先级为 $2，分配给 $3
```

**使用方式：**
```
> /review-pr 456 high alice
# $1 = "456", $2 = "high", $3 = "alice"
```

## 高级功能

### 文件引用

使用 `@` 前缀引用项目文件：

```markdown
# 引用单个文件
审查 @src/utils/helpers.js 的实现

# 引用多个文件
比较 @src/old-version.js 和 @src/new-version.js
```

### 执行 Bash 命令

使用 `` !`command` `` 语法执行 bash 命令并将结果嵌入：

```markdown
---
allowed-tools: Bash(git add:*), Bash(git status:*)
---

当前状态: !`git status`
变更内容: !`git diff`
```

> **注意**：使用 Bash 命令嵌入时，必须在 `allowed-tools` 中包含 `Bash` 工具。

### 命名空间（子目录组织）

通过子目录组织命令，形成命名空间：

```
.claude/commands/
├── frontend/
│   └── component.md      # /component (project:frontend)
├── backend/
│   └── api.md            # /api (project:backend)
└── optimize.md           # /optimize (project)
```

### 扩展思考

斜杠命令可以通过在命令内容中包含扩展思考关键词来触发 Claude 的扩展思考模式。

## 插件命令

插件可以提供自定义斜杠命令：

- **格式**：`/plugin-name:command-name`（如无冲突，前缀可省略）
- **位置**：插件根目录的 `commands/` 目录
- **功能**：支持所有命令特性（参数、frontmatter、bash、文件引用）

## MCP 斜杠命令

MCP 服务器可以将 prompts 暴露为斜杠命令：

```
/mcp__<server-name>__<prompt-name> [arguments]
```

### 示例

```bash
/mcp__github__list_prs
/mcp__github__pr_review 456
/mcp__jira__create_issue "Bug title" high
```

使用 `/mcp` 命令可以：
- 查看已配置的 MCP 服务器
- 检查连接状态
- 进行 OAuth 服务器认证
- 查看可用的工具和 prompts

## SlashCommand 工具集成

Claude 可以通过 `SlashCommand` 工具程序化地执行自定义斜杠命令。

### 支持的命令

- 仅支持自定义用户定义命令（不支持内置命令如 `/compact`）
- 必须在 frontmatter 中填写 `description` 字段

### 禁用 SlashCommand 工具

```bash
/permissions
# 在拒绝规则中添加: SlashCommand
```

### 禁用特定命令被工具调用

在命令 frontmatter 中添加：

```markdown
---
disable-model-invocation: true
---
```

### 权限规则

```
SlashCommand:/commit          # 精确匹配（无参数）
SlashCommand:/review-pr:*     # 前缀匹配（带任意参数）
```

### 字符预算

- **默认限制**：15,000 字符
- **自定义限制**：通过 `SLASH_COMMAND_TOOL_CHAR_BUDGET` 环境变量设置
- 用于防止可用命令过多时的 token 溢出

## 实用示例

### 示例1：Git 提交命令

```markdown
---
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
argument-hint: [提交信息]
description: 创建 git 提交
---

## 上下文

- 当前 git 状态: !`git status`
- 当前变更 (暂存和未暂存): !`git diff HEAD`
- 当前分支: !`git branch --show-current`
- 最近提交: !`git log --oneline -10`

## 任务

根据以上变更，创建一个 git 提交，提交信息为: $ARGUMENTS
```

### 示例2：代码审查命令

```markdown
---
argument-hint: [pr编号] [优先级] [负责人]
description: 审查 Pull Request
---

审查 PR #$1，优先级为 $2，分配给 $3。
重点关注：安全性、性能和代码风格。
```

### 示例3：性能分析命令

```markdown
---
description: 分析代码性能问题
---

分析这段代码的性能问题并提出优化建议：
- 识别性能瓶颈
- 建议算法改进方案
- 推荐缓存策略
- 识别不必要的计算
```

### 示例4：生成测试命令

```markdown
---
description: 为函数生成单元测试
argument-hint: [文件路径]
---

为 @$ARGUMENTS 中的函数生成完整的单元测试：
- 覆盖正常情况
- 覆盖边界情况
- 覆盖错误处理
- 使用项目现有的测试框架
```

## 斜杠命令与技能的区别

| 方面 | 斜杠命令 | Agent Skills |
|------|----------|--------------|
| **调用方式** | 用户显式调用（`/command`） | 模型自动调用 |
| **发现机制** | 基于 `/` 前缀 | 基于 description |
| **复杂度** | 简单提示 | 复杂能力包 |
| **文件结构** | 单个 .md 文件 | 目录 + SKILL.md + 资源 |
| **适用场景** | 快速重复任务 | 扩展 Claude 能力 |

**选择建议**：
- 使用**斜杠命令**：快速、常用的提示（review、explain、optimize）
- 使用 **Skills**：包含脚本、跨文件知识、团队标准化的综合工作流

## 最佳实践

1. **命名清晰**：使用简短、有意义的命令名称
2. **提供描述**：始终在 frontmatter 中添加 `description`
3. **限制工具**：仅授予命令必需的工具权限
4. **参数提示**：使用 `argument-hint` 帮助用户理解参数用法
5. **组织结构**：使用子目录为相关命令分组

## 相关资源

- [Skills 技能指南](./02-技能指南.md)
- [Plugins 插件指南](./03-插件指南.md)
- [Plugin Marketplaces 插件市场指南](./04-插件市场指南.md)
- [官方文档：斜杠命令](https://code.claude.com/docs/en/slash-commands)