内容来源：The Prompt Shelf。https://thepromptshelf.dev/blog/claude-code-custom-slash-commands/
原题：Claude Code Custom Slash Commands: Build Reusable Workflows with Skills
原发布时间：2026-04-03

学习如何使用 Skills 系统在 Claude Code 中构建自定义斜杠命令。涵盖 SKILL.md 结构、命令与 Skill 模式、作用域、渐进式披露，以及可以立即复制使用的实际示例。

自定义斜杠命令是 Claude Code 中最未被充分利用的功能之一。大多数开发者都知道 CLAUDE.md：在里面写下项目规则，就认为配置工作已经完成。但 Skills——也就是自定义命令背后的系统——能让你更进一步：把整套工作流打包成一条 /command，在每个项目中重复使用，并通过一个词启动多步骤流程。

本指南将介绍 2026 年 Skills 系统的工作方式、如何编写有效的 SKILL.md 文件，以及哪些模式值得构建。

Skills 系统如何工作

在 Claude Code 中，自定义斜杠命令通过 Skills 实现。输入 /my-command 后，Claude Code 会寻找匹配的 Skill 文件，将其中的指令作为系统提示词载入，再按照指令执行。

Skills 可以放在两个位置：

• 项目作用域：项目根目录中的 .claude/skills/，仅在该项目中可用
• 全局作用域：主目录中的 ~/.claude/skills/，在所有项目中可用

每项 Skill 可以是一个 Markdown 文件，也可以是一个目录：

.claude/skills/
  review.md          # 采用单文件形式的简单 Skill
  deploy/            # 采用目录形式的复杂 Skill
    SKILL.md         # 必需的入口文件
    checklist.md     # 配套参考资料
    examples/        # 输出示例

目录形式更加灵活。只要不止是一条简单提示词，就应该采用目录结构。

SKILL.md 的结构

每项 Skill 都从 SKILL.md 文件开始，其结构分为两个部分：

---
name: review
description: 审查代码的正确性、安全问题和风格违规。
             在提交代码或创建 Pull Request 前使用。
---

检查当前会话中的代码是否存在以下问题：

1. 测试可能遗漏的逻辑错误和边界情况
2. 安全漏洞（注入、不安全的默认设置、泄露的密钥）
3. 性能问题（N+1 查询、不必要的内存分配、阻塞调用）
4. 违反项目 CLAUDE.md 规则的风格问题

按严重程度将结果整理成结构化清单：严重、警告、信息。
每个问题都要包含文件与行号、一句话描述，以及建议的修复方法。

如果没有发现问题，请明确说明，不要为了凑内容而增加无用信息。

Frontmatter 的 name 字段决定斜杠命令名称。name: review 会变成 /review。

description 字段同时承担两项职责：既会显示在 / 自动补全列表中，也会告诉 Claude 何时应当自主调用该 Skill——稍后还会详细解释。

两种调用模式

Skills 可以通过两种方式调用。兼顾两种模式进行设计，能够解锁不同的使用场景。

用户调用的命令是大多数人首先想到的形式。你输入 /review，Claude 就会运行该 Skill。它们最适合由你主动发起的工作流，例如代码审查、部署检查清单、报告生成和测试脚手架。

自主调用是指 Claude 自行决定加载某项 Skill。该行为由 description 字段决定。Claude 正在处理一项任务时，如果认为某项 Skill 的描述与当前需求相符，就可以在没有收到明确要求的情况下调用它。

这意味着，编写良好的描述可以充当智能体的路由规则。一项描述为“编写数据库迁移时，用于检查向后兼容性”的 Skill，会在 Claude 编写迁移时自动调用——前提是描述足够明确，能够发出正确的触发信号。

要让自主调用可靠工作，描述必须具体，并以行动为导向。“帮助处理代码”毫无用处；“提交前审查 API 端点处理程序中的身份验证与授权缺口”则很实用。

Commands 与 Skills：实际区别

两者的底层实现相同，但服务于不同的设计目标。

Commands 是确定性的、由用户发起的工作流。因为运行时机由你控制，所以输出可以预测。好的例子包括：/standup（根据最近的提交生成站会摘要）、/changelog（把提交历史整理成变更日志），以及 /pr-description（根据已暂存的改动撰写 Pull Request 说明）。

知识型 Skills 是 Claude 随身携带的上下文。通常不会直接调用；Claude 需要参考资料时才会加载它们。用于说明内部 API 约定、数据库 Schema 模式或团队测试理念的 Skill，都属于这一类。

一条实用判断规则：如果你会亲自输入命令，它就是 Command；如果你希望 Claude 无需提醒便主动查阅，它就是知识型 Skill。

编写有效的 Skill 指令

最常见的错误，是把 Skills 写成对话中的提示词。Skills 是指令，不是请求。

较弱的写法：

可以请你帮我审查这段代码吗？我希望你找出其中可能存在的问题，
再告诉我你的看法。

有力的写法：

审查当前会话中修改过的所有文件。

针对每个文件：
- 检查空指针解引用和未处理的错误返回值
- 验证外部输入是否在使用前经过校验
- 确认所有新增依赖都锁定到具体版本

输出编号列表。没有问题的文件直接跳过。
最后用一行总结：“未发现问题”或“在 M 个文件中发现 N 个问题”。

有力的版本准确告诉 Claude 要检查什么、如何组织输出，以及代码没有问题这种边界情况下应当做什么。不存在需要自行判断的歧义。

提高指令质量的三条规则：

1、使用祈使动词。 使用“审查”“输出”“检查”“跳过”，而不是“可以请你”“麻烦你”“你是否介意”。
2、明确指定输出格式。 想要编号列表，就直接说明“编号列表”；想要 JSON，就给出 Schema。
3、处理边界情况。 如果没有可供审查的内容，Claude 应该怎么做？任务无法完成时呢？没有说明边界情况，Claude 就只能临场发挥。

使用目录实现渐进式披露

面对复杂 Skills，单文件形式会变得臃肿。目录结构可以把不同职责分开：

.claude/skills/
  deploy/
    SKILL.md         # 指令（控制在 400 行以内）
    pre-deploy.md    # Claude 在部署前读取的检查清单
    rollback.md      # 回滚流程参考资料
    examples/
      staging.md     # 预发布环境部署示例
      production.md  # 生产环境部署示例

在 SKILL.md 中明确引用配套文件：

---
name: deploy
description: 执行本项目的部署工作流。部署到预发布或生产环境时使用。
---

开始前，读取 `pre-deploy.md` 中的当前检查清单。

部署到预发布环境时：
……

部署到生产环境时：
……

如需回滚，按照 `rollback.md` 中的流程操作。

这种模式既能保持主 SKILL.md 简短易读，又能让 Claude 在需要时获得完整参考资料。只有当指令要求时，Claude 才会读取配套文件，因此不会把上下文浪费在可能无关的信息上。

作用域策略：哪些内容应当全局使用，哪些属于项目

全局 Skills（位于 ~/.claude/skills/）适用于任何项目通用的工作流：

• /review：依据通用最佳实践审查代码
• /explain：用通俗语言解释当前函数或文件
• /test：为选中的代码生成测试
• /standup：根据最近的 Git 活动生成站会进展

项目级 Skills（位于 .claude/skills/）适用于特定代码库的工作流：

• /migrate：运行项目的数据库迁移工作流
• /seed：使用测试数据填充开发数据库
• /deploy-staging：部署到项目的预发布环境
• /api-review：依据当前项目的约定检查 API 端点

项目级 Skill 与全局 Skill 同名时，以项目级 Skill 为准。这样，你可以逐个项目覆盖默认行为，不必改动全局配置。

值得构建的实用 Skills

根据开发者社区中的常见模式，以下 Skills 能够持续带来回报：

/commit-message
根据已暂存的改动生成提交信息。它会读取差异、遵循 Conventional Commits 格式，并避免“fix bug”或“update code”这类笼统信息。

/review
根据特定检查清单开展代码审查。可以针对团队规范构建一个版本，在每次 PR 前调用。结果一致、可复现，而且速度很快。

/explain-error
接收一条错误信息（或者当前会话中的最后一项错误），解释错误成因、代码中的位置，以及修复方法。当你陷入调试循环，希望换个角度检查时很有用。

/generate-tests
为函数或模块生成测试用例。应当明确项目使用的测试框架，以及是否需要覆盖边界情况和失败路径。

/adr
架构决策记录生成器。接收一个决策主题，按照团队使用的模板输出格式化 ADR 文档。适合维护 ADR 目录的团队。

应当避免什么

相互重叠的 Skills。 如果同时拥有 /review、/code-review 和 /check，你会把时间浪费在回忆该用哪一个上。把它们合并起来。

承担过多任务的 Skills。 一项名为“do everything”的 Skill 同时负责审查代码、生成文档、运行测试和创建 PR，效果会比四项专注的 Skills 更差。每项 Skill 都应该把一件事做好。

结构混乱的长篇 Skills。 如果 SKILL.md 超过 500 行，就应进行拆分。最前面的几百行最受关注，后面的章节容易被草草浏览。

Skills 中的密钥。 Skills 以明文保存，绝不要把 API 密钥、Token 或凭据放在里面。应改为引用环境变量。

开始行动

如果以前从未构建过自定义 Skill，可以先从一条简单命令开始。选择一套如今仍需手动运行的工作流，例如代码审查、站会进展生成或变更日志整理，再为它编写 SKILL.md。

第一个版本应当简短，控制在 200 行以内。使用一周，记录不足之处，再继续迭代。社区中最好的 Skills 经过了十轮编辑，而不是第一稿就达到完美。

.claude/skills/ 目录会放进代码仓库，意味着整个团队都能共享。这才是真正的回报：无需任何额外配置，团队中的每个人都能获得相同的 Claude Code 工作流。