自定义 Slash Command：把团队规范变成 /xxx

📍 Claude Code 进阶

适用信息

• 适合谁：中级
• 需要准备：安装 Claude Code，需要 Claude 付费订阅或 API；也可以接 DeepSeek，见这篇。会用 git 提交和推送；先读过自定义 Skills 更好
• 中国大陆能否直接用：不能直接用：Anthropic 不向中国大陆提供服务。可以让 Claude Code 接 DeepSeek（见这篇），Skill 和命令都是存在项目里的普通文件，不属于订阅功能；国内的 TraeCode 也支持自定义斜杠命令（放在 .trae/commands），见 Trae 教程
• 核对日期：2026-09-26（Claude Code 2.1.283）

一个四人小团队都会撞上的瞬间

想象一个典型场景：某个四人小团队的下午，有人在 Slack 上又发了一条：

“提交代码记得先跑 pytest tests/ && ruff check .，然后 commit message 用 feat: 或 fix: 开头，最后别用 --no-verify 跳过检查，统一走 CI…”

队友 A 已经第 5 次发这同一段话了。每个新人都要被这一段轰炸一次。

洁柔说：「为什么每个人都要打这一大段？能不能让 Claude 直接知道我们的规范？」

我说：「能。把这一段写成一个项目级 slash command，推到 git，所有同事 clone 项目就有 /commit 这个命令——他们打一句 /commit 自动按你们规范走。」

3 小时后，他们项目里多了一个 .claude/skills/commit/SKILL.md,所有人都不用再背规范——/commit 出来即是公司方法论。

这一篇讲的就是：把团队规范打包成 /xxx 命令，通过 git 推给全员。

一个重要变化：自定义命令 = Skill

从 Claude Code 2.1.3（2026 年 1 月）起，Anthropic 官方把「自定义 Slash Command」合并进了 Skill 系统。意思是：

• 你在「Claude Code 干活」板块学过的 Skill 写法 → 现在就是 slash command
• .claude/commands/deploy.md 跟 .claude/skills/deploy/SKILL.md 都创建 /deploy，效果一样；旧的命令文件照样能用
• 默认情况下，一个 Skill 既能由你打 /名字 手动调用，也能被 Claude 按 description 自动调用；加 disable-model-invocation: true 就只能手动（下面的 /commit、/deploy 就是这样），加 user-invocable: false 就只给 Claude 用
• 新写命令推荐用 Skill 形式（.claude/skills/<name>/SKILL.md）：参数、动态注入、子智能体这些写法两种文件都支持，但 Skill 是一个文件夹，能带附属文件（参考资料、脚本），还支持 name 和 paths（按文件路径自动激活）这两个字段，老式命令文件不支持

这一篇跟自定义 Skills的分工：

• 自定义 Skills（「Claude Code 干活」板块）教你写第一个个人级 Skill（写周报 / 改简历），讲清 description 怎么写、手动和自动两种调用
• 本篇（「Claude Code 进阶」板块）教你写团队级 + 高级特性 Skill——参数 / 动态注入 / 跑在子智能体 / 按文件路径自动激活 / 通过 git 团队共享

4 种安装范围（scope）：谁能用到这个命令

范围	路径	谁能用
企业级(管理员下发)	managed settings 配置	整个组织所有人
个人级	~/.claude/skills/<name>/SKILL.md	你所有项目
项目级(本篇重点)	项目/.claude/skills/<name>/SKILL.md	这个项目所有协作者
插件提供	<插件>/skills/<name>/SKILL.md	装了这个插件的人

优先级：企业 > 个人 > 项目（同名时高优先级覆盖低优先级）。同名的 Skill 和 .claude/commands/ 里的旧命令文件，用的是 Skill；插件里的 Skill 名字前面自带插件名（/插件名:技能名），不会和它们撞名。

项目级的杀手锏:把 .claude/skills/ 整个目录推到 git——队友 clone 项目就自动获得整套命令。团队规范从口口相传变成 git 同步。

例子 1：团队 commit 命令

新建文件 项目/.claude/skills/commit/SKILL.md:

---
description: 按本项目规范提交代码——跑测试、写 commit message、推到远程
disable-model-invocation: true
allowed-tools: Bash(pytest *) Bash(ruff *) Bash(git *)
---

按团队规范提交代码 $ARGUMENTS:

1. 先跑测试:`pytest tests/ -v`,**失败就停,不要提交**
2. 跑 lint:`ruff check .`,如果有错先修
3. `git status` + `git diff --staged` 看一遍改了啥
4. 写 commit message,**严格按 conventional commits 规范**:
   - `feat:` 新功能
   - `fix:` bug 修复
   - `refactor:` 重构(不改行为)
   - `docs:` 文档
   - `test:` 测试
   - 标题不超过 50 字
5. `git commit -m "..."` + `git push`
6. **永远不用 `--no-verify`** —— pre-commit hook 是为了保护你

推到 git:

git add .claude/skills/commit
git commit -m "feat: add /commit skill for team"
git push

队友 pull → /commit 立刻能用。整个团队规范一次同步。

例子 2：参数化命令

很多命令需要参数(比如 fix-issue 要传 issue 号)。Claude Code 提供几种参数引用方式:

写法	含义
$ARGUMENTS	整段用户输入(空格分隔的原文)
$0 或 $ARGUMENTS[0]	第 1 个参数
$1 或 $ARGUMENTS[1]	第 2 个参数
$N	第 N+1 个参数
$自定义名	用 frontmatter arguments: 命名的参数

⚠️ 编号从 0 开始：$0 才是第 1 个参数，$1 是第 2 个。这跟 shell 脚本（$1 是第 1 个）不一样，网上 2025 年的旧教程写的「$1 = 第 1 个」已经过时，照抄会整体错一位。一个参数里有空格的话，用引号包起来，比如 /my-skill "hello world" second 里 $0 是 hello world。

例子 1:全部参数当一坨用

---
description: 按本项目规范修复一个 GitHub issue
---

修复 issue $ARGUMENTS,流程:
1. 读 issue 描述
2. 写代码
3. 加测试
4. 提交 PR

用：/fix-issue 123 优先紧急 → $ARGUMENTS = "123 优先紧急"

例子 2:按位置传

---
description: 从一个框架迁移组件到另一个框架
argument-hint: <组件名> <源框架> <目标框架>
---

把 $0 组件从 $1 迁移到 $2，保留所有现有行为跟测试。

用：/migrate-component SearchBar React Vue → $0=SearchBar / $1=React / $2=Vue

少传了参数的话，没对上的占位符会原样留在文字里（比如只传两个参数，Claude 看到的就是「迁移到 $2」），一眼就能发现。

例子 3:命名参数（更清晰）

---
description: 修一个 issue + 推到指定分支
arguments: [issue, branch]
---

修复 issue #$issue，推到 $branch 分支。

用：/fix-and-push 123 fix/login → $issue=123 / $branch=fix/login

arguments: 里的名字按顺序对应第 1、第 2 个参数；少传的命名参数会变成空的。

小窍门:argument-hint: <issue 号> <分支> 字段会在 Claude Code 的 / 菜单里显示提示，队友打到一半看得到该传什么。

例子 3：动态注入上下文(!command 语法)

最强大的特性——命令可以预先跑 shell 命令，把输出注入到 prompt 里,Claude 收到的就是「带数据的指令」。

写法：在 SKILL.md 里用 !`命令` 行内，或者 ```! 代码块。

例子：让 Claude 总结当前 git diff

---
description: 总结当前未提交的改动,标出风险
---

## 当前改动
!`git diff HEAD`

## 任务
用 2-3 句话总结上面的改动,然后列出你看到的风险(比如没加错误处理 / 硬编码值 / 缺测试)。
如果 diff 为空,说没有未提交改动。

怎么工作:

1. 用户打 /summarize-changes
2. Claude Code 先跑 git diff HEAD —— 把输出替换到 !`git diff HEAD` 的位置
3. Claude 看到的 prompt 已经包含真实 diff —— 不需要它自己去查

这就是动态上下文注入——比让 Claude 「自己去看」快很多 + 准很多。

更强的多行命令(用 ```! 块):

## 环境信息
```!
node --version
npm --version
git status --short
```

两个细节：行内写法的 ! 要放在行首或空格后面才会被识别；注入的命令只要有一条出错（退出码不是 0），这次调用就整个中止，Claude 什么也看不到。检查类命令发现问题时常常故意返回非 0，这种命令后面加 || true。

4 个高价值团队命令模板

直接抄走改你团队用：

1️⃣ /deploy — 部署到生产

---
description: 部署当前分支到生产环境
disable-model-invocation: true
allowed-tools: Bash(npm *) Bash(wrangler *) Bash(git *)
---

部署当前代码到生产 $ARGUMENTS:

1. 跑全套测试 `npm test`,失败立刻停
2. 跑生产构建 `npm run build`
3. 部署 `npx wrangler pages deploy dist`
4. 验证线上 URL 200
5. git tag 标记本次发布版本
6. 通知 Slack #releases 频道

⚠️ 建议加 disable-model-invocation: true —— 不让 Claude 自己决定要不要部署，只在用户主动打 /deploy 时才跑。

2️⃣ /review-pr — 自动 review 当前 PR

---
description: 自动 review 当前分支的改动,找 bug + 风格问题
context: fork
agent: Explore
allowed-tools: Bash(gh *) Bash(git *)
---

## PR 信息
- diff: !`gh pr diff`
- 评论: !`gh pr view --comments`
- 文件清单: !`gh pr diff --name-only`

## 任务
review 上面这个 PR,找:
1. 🐛 潜在 bug
2. 🎨 风格 / 命名问题
3. ⚡ 性能问题
4. 🧪 缺测试的地方

按严重程度排序输出。

context: fork + agent: Explore —— 跑在隔离的子智能体（subagent）里，不污染主对话：

• context: fork 让 Claude Code 新开一个子智能体，把这份 Skill 的内容（连同 ! 注入的整份 diff 和评论）当成它的任务，diff 只进子智能体，不占主对话的上下文
• agent: Explore 指定用内置的 Explore（只读探索型）子智能体，只看不改，正适合 review；不写 agent 就用通用的 general-purpose
• 从 2.1.218 起，这类 Skill 默认在后台跑，你可以接着干别的，跑完结论自动回到主对话；想当场等结果，在 frontmatter 加一行 background: false
• 子智能体看不到你之前的对话，所以任务要在 Skill 里写完整

⚠️ 别只在正文里写一句「请派一个子智能体去 review」来代替 context: fork：! 注入的命令在 Claude 读到这句话之前就跑完了，整份 diff 已经进了主对话。

3️⃣ /test-all — 跑全套测试

---
description: 跑全套测试 + lint + 类型检查
allowed-tools: Bash(npm *) Bash(pytest *) Bash(ruff *) Bash(mypy *)
---

跑全套质量检查:

```!
npm run lint 2>&1 | tail -20
```

```!
pytest tests/ -v --tb=short 2>&1 | tail -40
```

```!
mypy . 2>&1 | tail -10
```

总结结果:
- ✅ 全过 → 报告"OK"
- ❌ 有失败 → 列出哪里失败 + 怎么修

4️⃣ /standup — 写日报

---
description: 生成今天的开发日报
allowed-tools: Bash(git *)
---

## 今天的提交
!`git log --oneline --since="6am" --author="$(git config user.email)"`

## 今天的改动统计
!`git log --since="6am" --author="$(git config user.email)" --stat | tail -30`

## 任务
基于上面的提交记录,写一份日报(3-5 行),格式:
- 完成的事(主要)
- 进行中
- 明天的计划

风格:克制、动词起头、不夸大。

按文件路径自动激活(高级技巧)

想让规范只在写测试时出现？用 paths 字段：它让 skill 只在 Claude 处理匹配的文件时才自动加载。

---
description: 写 Python 测试的规范。当创建或修改 tests/ 目录下的 .py 测试文件时使用。
paths: tests/**/*.py
---

写 Python 测试要按本团队规范:
- 用 pytest 不用 unittest
- 测试函数名必须 `test_<被测>_<场景>_<预期>` 格式
- 用 fixture 不用 setUp
- mock 用 unittest.mock,不引入第三方
- ...

效果：当 Claude 在 tests/ 下读写 .py 文件时，这个 skill 自动加载——团队规范「按上下文出现」。

几点说明：

• paths 用的是 glob 通配符写法（** 表示任意层目录，* 表示任意文件名），多个规则用逗号隔开，或者写成 YAML 列表
• description 照样要写清楚，Claude 还是靠它理解这个 skill 是干什么的
• paths 只对 .claude/skills/ 下的 skill 有效，老式 .claude/commands/ 命令文件不支持这个字段

3 个新手最容易踩的坑

❌ 坑 1：命令越写越长

新手把团队规范一股脑塞进一个 /dev-rules —— 800 行 markdown，每次激活都炸 context。

修正:一个 skill 一个明确动作。规范太长就拆：/commit / /test-all / /deploy / /review-pr —— 各管一摊，互不重叠。

❌ 坑 2：把敏感操作开放给 Claude 自动调用

不加 disable-model-invocation: true 的 /deploy —— Claude 可能自己判断「代码看着 OK」就调用部署,误部署的事真发生过。

修正:所有带副作用的命令(部署 / 发邮件 / 删数据)强制加 disable-model-invocation: true。

❌ 坑 3:!command 命令吐出爆炸输出

!`git log` —— 项目历史几千条 commit，一股脑塞进来，白白占掉一大块 context；太长的输出还会被换成「文件路径 + 一小段预览」，Claude 反而看不全。

修正:所有 !command 都加 | tail -N 或 | head -N 限制输出大小:

!`git log --oneline | head -20`

怎么发给团队

方式 1：推到项目 git(最常用)

git add .claude/skills/
git commit -m "feat: add team skills"
git push

队友 pull → 立刻可用。

方式 2：打包成 Plugin 分享给社区

Plugin 发布 —— 把这些 Skill 放进插件的 skills/ 目录。最常见的做法是建自己的插件市场（一个带 .claude-plugin/marketplace.json 的 git 仓库），别人 /plugin marketplace add 加上以后就能 install，不用审核；也可以提交到 Anthropic 官方目录，要通过审核。

方式 3:GitHub gist 单独分享

把单个 SKILL.md 发 gist（GitHub 上分享单个文件的小仓库）—— 其他人下载后放成 ~/.claude/skills/名字/SKILL.md 的「文件夹 + SKILL.md」结构就能用。反过来，用别人的 Skill 前先读一遍：留意 ! 开头会执行命令的行和 allowed-tools 放行了哪些工具。

一份给团队装的「起步包」

如果你今天就想让团队上手，这 5 个命令是性价比最高的:

命令	干啥
/commit	按规范提交代码
/review-pr	自动 review PR
/test-all	跑全套测试 + lint
/deploy	一键部署生产
/standup	写每日日报

把这 5 个文件放进项目 .claude/skills/，推到 git,团队所有协作者 5 分钟内就能用上。

下一步

读完这一篇你应该会：

• 理解 自定义 Slash Command 现在就是 Skill(merged)
• 用 项目级 + git 同步 把规范推给全员
• 用 参数 $ARGUMENTS / $0 / $1 / $自定义名 让命令灵活
• 用 !command 动态注入上下文 让命令带数据
• 用 paths 让 skill 按文件路径自动激活

接下来「Claude Code 进阶」板块还有：

→ Subagents（子智能体）：多个 Claude 并行干活

→ Git Worktree：多个 Claude 各改各的不打架

想及时看到更新，可以收藏 niuxue.org 主页。