304 lines
7.4 KiB
Markdown
Executable File
304 lines
7.4 KiB
Markdown
Executable File
# 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)
|