3.2　创建并配置自定义斜杠命令与 Skills

这一条考什么

考你能否用自定义斜杠命令和 Skills 封装可复用的工作流：知道项目级（.claude/commands/、.claude/skills/，随 Git 共享）与用户级（~/.claude/commands/、~/.claude/skills/，仅个人）的区别；会用 SKILL.md 的前置信息 context: fork、allowed-tools、argument-hint；并能判断某条知识该做成按需调用的 Skill，还是放进始终加载的 CLAUDE.md。

核心概念

自定义斜杠命令：项目级 vs 用户级

斜杠命令就是一个 Markdown 文件，文件名即命令名：

• .claude/commands/review.md → /review，放在仓库里，提交后全团队可用，并随团队迭代保持同步。
• ~/.claude/commands/review.md → 只有你自己能用，不影响他人。

命令文件中可以用 $ARGUMENTS 接收全部参数，或用 $1、$2 接收位置参数：

---
description: 按团队清单审查当前分支的改动
argument-hint: [目标分支，默认 main]
allowed-tools: Bash(git diff:*), Bash(git log:*), Read, Grep
---

对比当前分支与 $ARGUMENTS 的差异，按以下清单逐条检查：
1. 是否有未处理的错误分支
2. 新增 SQL 是否参数化
3. 公共 API 变更是否更新了文档
输出：文件:行号 + 问题 + 建议修复。

一个典型考点：团队有一份审查清单，只在做代码审查时需要，平时写功能、调试时不需要。最合适的是做成 /review 命令（或 Skill），而不是塞进 CLAUDE.md 让每次会话都加载。

Skills：.claude/skills/<名字>/SKILL.md

Skill 是一个目录，核心是 SKILL.md，还可以附带脚本、模板、参考文档。前置信息常用字段：

• name、description：描述决定模型何时自动选用该 Skill，也可由用户用 /名字 显式调用。
• allowed-tools：Skill 运行期间可用的工具白名单。
• argument-hint：用户输入 /名字 后提示需要什么参数，没带参数时提醒必填项。
• context: fork：让 Skill 在独立的子 Agent 上下文中运行。

---
name: analyze-module
description: 深度分析一个模块的结构、依赖和潜在问题，输出精简报告
argument-hint: <模块路径，例如 src/billing>
context: fork
allowed-tools: Read, Grep, Glob
---

分析 $ARGUMENTS：
1. 列出公共导出和主要调用方
2. 画出依赖关系（文字形式）
3. 指出循环依赖、过大的函数、缺少测试的路径
最后只返回不超过 30 行的摘要。

context: fork：隔离冗长输出

代码库分析、头脑风暴多个替代方案，都会产生大量中间内容。如果在主会话里直接跑，这些内容会挤占上下文、干扰后续工作。context: fork 让 Skill 在一个分离的子 Agent 上下文中执行，只把最终结果带回主会话，主会话保持干净。

allowed-tools：限制 Skill 的能力

allowed-tools 限定 Skill 执行期间能用的工具。例如一个只负责生成文档的 Skill，只允许 Read, Grep, Glob, Write，不给 Bash，避免它执行破坏性命令；一个只读分析 Skill 则只给 Read, Grep, Glob。这是“最小权限”原则在 Skill 上的应用。

个人定制：起个不同的名字放到用户目录

想按自己的习惯修改团队 Skill，不要直接改仓库里的 .claude/skills/...（会影响所有人），而是在 ~/.claude/skills/ 下用不同的名字创建个人变体，例如团队有 migrate-component，你建 my-migrate-component。这样团队版本保持不变，同名冲突也不会发生。

Skill 还是 CLAUDE.md？

• CLAUDE.md：始终加载的、普遍适用的标准。每次会话都需要的东西：构建命令、命名约定、架构概述。
• Skill / 斜杠命令：按需调用的、针对特定任务的工作流。只在某类任务时才需要：组件迁移步骤、发布清单、审查清单。

把任务专用的长流程写进 CLAUDE.md，会让每次会话都背着无关指令；反过来把全局编码规范做成 Skill，会导致平时不调用时规范缺失。

正确做法与反模式

• 正确：团队共用的工作流放 .claude/commands/ 或 .claude/skills/ 并提交。反模式：让每个开发者在 ~/.claude/ 下各自复制一份，版本不同步。
• 正确：产生大量输出的分析、探索类 Skill 加 context: fork。反模式：在主会话里直接运行，把上下文塞满中间结果。
• 正确：用 allowed-tools 把 Skill 限制在完成任务所需的最少工具。反模式：不设限制，让文档生成 Skill 也能跑任意 Bash。
• 正确：必填参数用 argument-hint 提示。反模式：靠口头约定，开发者不带参数调用后得到错误结果。
• 正确：个人变体以不同名字放 ~/.claude/skills/。反模式：直接修改仓库里的团队 Skill 来满足个人偏好。
• 正确：任务专用流程做成 Skill，通用标准放 CLAUDE.md。反模式：把审查清单写进 CLAUDE.md 让所有任务都加载。

常见陷阱

• 放错位置导致不能共享：“放在每个人的 ~/.claude/skills/”是典型干扰项，题目要求“全团队都能 /migrate-component 且保持同步”时，答案是仓库内 .claude/skills/ 并提交。
• 编造配置方式：如“在 settings.json 里用某个字段注册 Skill”这类选项，Skill 是靠目录和 SKILL.md 发现的。
• 把仅在特定任务需要的内容放进 CLAUDE.md：题干强调“只在审查时需要、其他任务不需要”，就该选斜杠命令或 Skill。
• 用子 Agent 或 plan mode 代替简单命令：为一份清单专门建子 Agent 或强制 plan mode，属于过度设计。
• 误解 context: fork：它不是“并行执行”或“新开一个会话需要手动复制结果”，而是隔离执行、只返回结果。
• 把 Skill 当作强制格式化工具：需要“每次都必定执行”的确定性动作（如每次写文件后跑 Prettier），应该用 hooks，而不是 Skill。

实操练习

目标：创建一个团队共享的斜杠命令和一个带 context: fork 与 allowed-tools 的 Skill，并做一个个人变体。

1. 在仓库中创建 .claude/commands/review.md（内容参考上文）。
2. 创建 .claude/skills/analyze-module/SKILL.md，设置 context: fork、allowed-tools: Read, Grep, Glob、argument-hint。
3. 启动 Claude Code，输入 /analyze-module 不带参数，观察参数提示；再带上 src/billing 运行。
4. 运行后检查主会话：应该只看到摘要，而不是大量 Read/Grep 输出。
5. 在 ~/.claude/skills/my-analyze-module/SKILL.md 建个人变体（如改成英文输出），确认团队版本未受影响。

mkdir -p .claude/commands .claude/skills/analyze-module ~/.claude/skills/my-analyze-module
cat > .claude/skills/analyze-module/SKILL.md <<'EOF'
---
name: analyze-module
description: 深度分析一个模块的结构和依赖，返回精简报告
argument-hint: <模块路径>
context: fork
allowed-tools: Read, Grep, Glob
---
分析 $ARGUMENTS 的公共导出、依赖与风险点，只返回 30 行以内的摘要。
EOF
sed 's/name: analyze-module/name: my-analyze-module/; s/摘要。/摘要，用英文输出。/' \
  .claude/skills/analyze-module/SKILL.md > ~/.claude/skills/my-analyze-module/SKILL.md
git add .claude && git commit -m "Add review command and analyze-module skill"

检查结果：同事拉取后能用 /review 和 /analyze-module，但看不到 /my-analyze-module；Skill 运行期间尝试写文件会被拒绝。

自测清单

• .claude/commands/ 与 ~/.claude/commands/ 的区别是什么？团队清单该放哪？
• context: fork 解决什么问题？适合哪两类 Skill？
• 如何用 allowed-tools 防止 Skill 执行破坏性操作？
• argument-hint 在什么场景下有用？
• 想按个人喜好修改团队 Skill，正确的做法是什么？
• 给出一个应放进 CLAUDE.md 的例子和一个应做成 Skill 的例子，并说明判断依据。