agent-aide/guide/01-自定义斜杠命令指南.md

Claude Code 自定义斜杠命令指南

概述

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

基本语法：

/<命令名称> [参数]

命令类型与存储位置

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

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

快速开始

创建项目命令

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

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

创建个人命令

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

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

Frontmatter 配置

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

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

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

使用方式：

> /fix-issue 123 high-priority
# $ARGUMENTS 会被替换为: "123 high-priority"

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

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

使用方式：

> /review-pr 456 high alice
# $1 = "456", $2 = "high", $3 = "alice"

高级功能

文件引用

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

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

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

执行 Bash 命令

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

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

示例

/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 工具

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

禁用特定命令被工具调用

在命令 frontmatter 中添加：

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

权限规则

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

字符预算

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

实用示例

示例1：Git 提交命令

---
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：代码审查命令

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

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

示例3：性能分析命令

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

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

示例4：生成测试命令

---
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 技能指南
• Plugins 插件指南
• Plugin Marketplaces 插件市场指南
• 官方文档：斜杠命令