在 Claude Code…

当需要为 Claude Code 定义自定义斜杠命令（含 YAML frontmatter、动态参数、bash 执行、文件引用、插件集成）时使用。

适用场景

解决思路

1. 把命令写成给 Claude 的指令（directive），而不是给用户的说明；例如直接写“Review this code for security vulnerabilities including: SQL injection, XSS...”，不要写“This command will review your code...”。
2. 按作用域选择存放位置：项目命令放 `.claude/commands/`（团队共享，`/help` 显示 (project)）；个人命令放 `~/.claude/commands/`（所有项目可用，显示 (user)）；插件命令放 `plugin-name/commands/`（安装插件后可用，显示 (plugin-name)）。
3. 命令文件为 `.md` 扩展名的 Markdown；简单命令无需 frontmatter，直接写提示词即可。
4. 用 YAML frontmatter 配置命令：`description`（`/help` 中显示的简短描述，建议 60 字符以内）、`allowed-tools`（如 `Read, Write, Edit, Bash(git:*)` 或 `*`）、`model`（sonnet/opus/haiku）、`argument-hint`（如 `[pr-number] [priority] [assignee]`）、`disable-model-invocation`（true 时禁止 SlashCommand 工具程序化调用）。
5. 用 `$ARGUMENTS` 捕获全部参数为单个字符串（如 `/fix-issue 123` 展开为 `Fix issue #123 ...`）。
6. 用位置参数 `$1`、`$2`、`$3` 捕获单个参数（如 `/review-pr 123 high alice` 展开为 `Review pull request #123 with priority level high. After review, assign to alice`）。
7. 可混用位置参数与剩余参数，如 `Deploy $1 to $2 environment with options: $3`。
8. 用 `@` 语法引用文件内容：`@$1`（动态路径）、`@src/old-version.js`（静态路径），Claude 会在处理命令前读取这些文件。
9. 在命令中内联执行 bash 以动态收集上下文（如 git 状态、环境变量、仓库状态）；具体语法与示例参见 `references/plugin-features-reference.md` 的 bash execution 章节。
10. 按规模组织命令：5–15 个命令用扁平结构；15+ 个且有明确分类时用子目录命名空间（如 `ci/`、`git/`、`docs/`），`/help` 中显示命名空间。
11. 命令设计遵循：单一职责、描述清晰、必要时显式声明 `allowed-tools`、始终提供 `argument-hint`、用动词-名词命名（review-pr、fix-issue）。
12. 参数处理：校验必填参数、提供默认值、说明参数格式、处理缺失或非法参数（如用 `$IF($1, Review PR #$1, Please provide a PR number. Usage: /review-pr [number])`）。
13. 文件引用：使用明确路径、优雅处理文件不存在、使用项目相对路径、需要模式匹配时考虑 Glob 工具。
14. Bash 命令：限制范围（用 `Bash(git:*)` 而非 `Bash(*)`）、避免破坏性操作、处理失败、保持命令快速。
15. 文档化：添加注释、在注释中给出用法示例、列出依赖、标注破坏性变更（如用 HTML 注释写 Usage/Requires/Example）。
16. 常用模式：Review 模式（`!`git diff --name-only`` + allowed-tools: Read, Bash(git:*)）、Testing 模式（`!`npm test $1`` + Bash(npm:*)）、Documentation 模式（`@$1` 生成文档）、Workflow 模式（`!`gh pr view $1`` + Bash(gh:*), Read）。
17. 插件命令中用 `${CLAUDE_PLUGIN_ROOT}` 引用插件绝对路径，实现可移植：执行脚本 `!`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js $1``、加载配置 `@${CLAUDE_PLUGIN_ROOT}/config/settings.json`、使用模板 `@${CLAUDE_PLUGIN_ROOT}/templates/report.md`。
18. 插件命令按 `commands/` 目录自动发现并命名空间化（如 `commands/utils/helper.md` → `/helper (plugin:plugin-name:utils)`）；命名用描述性动作名，避免 test/run 等泛化名，多词用连字符。
19. 插件命令模式：配置驱动（`@${CLAUDE_PLUGIN_ROOT}/config/$1-deploy.json`）、模板驱动（`@${CLAUDE_PLUGIN_ROOT}/templates/docs.md`）、多脚本（依次执行 build/test/package 脚本）。
20. 与其他插件组件集成：用 Task 工具启动 `plugin/agents/` 中的 agent；提及 `plugin/skills/` 中的 skill 名称触发调用；与 hooks 协调（命令准备状态、hook 在工具事件时自动执行）；组合 agent+skill+script 的多阶段工作流。
21. 输入校验模式：参数校验（`!`echo "$1" | grep -E "^(dev|staging|prod)$" || echo "INVALID"``）、文件存在性检查（`!`test -f $1 && echo "EXISTS" || echo "MISSING"``）、插件资源校验（`!`test -x ${CLAUDE_PLUGIN_ROOT}/bin/analyze && echo "✓" || echo "✗"``）、错误处理（`!`bash ... 2>&1 || echo "BUILD_FAILED"`` 后分析错误并给出排查步骤）。
22. 排障：命令不出现时检查目录、`.md` 扩展名、Markdown 格式并重启 Claude Code；参数不生效时检查 `$1`/`$2` 语法、`argument-hint` 与用法一致、无多余空格；bash 失败时检查 `allowed-tools` 含 Bash、反引号语法、先在终端测试、检查权限；文件引用失败时检查 `@` 语法、路径有效、允许 Read 工具、使用绝对或项目相对路径。

适用边界 · 注意事项

• 不适用于非 Claude Code 环境（其他 AI 工具或编辑器没有斜杠命令机制）。
• 插件专属功能（`${CLAUDE_PLUGIN_ROOT}`、插件命名空间、agent/skill/hook 集成）仅在开发 Claude Code 插件时适用。
• 命令应只做单一任务，不要用一条命令塞入多个不相关职责。