Claude Code Skill 上线前测什么

你在终端里随口问了一句“这个函数是干嘛用的”，Claude 却洋洋洒洒给出一套带严重程度评级的审查报告，还列了三条“建议修复”。你只是想看懂一个函数。

这多半是代码审查 Skill 的 description 写得过于宽泛，一个普通的解释性提问被拉进了审查流程。反过来的情况同样常见：用户说“看看这次能不能合并”，实际在问行为风险和漏测，Skill 却没有启用，因为描述里只写了“输入 /review”。

一个 Skill 写好之后，能被调用只是第一步。上线前还要确认几件事：

• 相关的请求会启用它，无关的请求它保持安静；
• 启用之后，它按约定的顺序读材料、做判断、输出结果；
• 遇到还没授权的重要决定，它会停下来等你确认；
• 信息不足时，它说明缺什么，而不是自己补全。

这些靠一次成功调用看不出来。办法是把流程写成可执行的步骤并留下中间产物，在尚未授权的决定上设确认点，再用一组相关请求和一组无关请求成对测试，最后查调用记录和实际读取的文件，确认它真的按方法运行。

01 把流程写成可执行的步骤

Skill 正文是一份操作手册，要明确执行顺序、确认节点和输出方式。一个清楚的流程通常包含：

• 用户需要提供什么输入。
• 继续前必须读取哪些文件。
• 哪些步骤可以自动完成。
• 哪些步骤需要用户确认。
• 怎样保存中间产物。
• 怎样判断任务完成。
• 输出格式是什么。
• 遇到信息不足时怎么处理。

例如，一个博客草稿 Skill 可以这样拆：

## 用户输入

用户应提供：

- 想法或主题
- 可用资料
- 目标读者
- 语气或风格
- 目标长度

## 执行流程

1. 创建文章目录和 resources 子目录。
2. 收集资料并保存摘要。
3. 提炼主题、角度、要点和信息缺口。
4. 向用户提出澄清问题。
5. 生成提纲并等待用户确认。
6. 保存已确认提纲。
7. 基于提纲撰写草稿。
8. 保存草稿版本。
9. 向用户展示草稿并等待反馈。
10. 根据反馈继续迭代或定稿。

02 中间产物用来定位跑偏的阶段

做过复杂内容产出的人都有体会：拿到一篇写得七零八落、论点不清的最终草稿时，如果手里只有这篇成稿，你很难复盘它是从哪一步开始跑偏的。是原始材料收集偏了，是提纲逻辑本身有漏洞，还是正文写着写着偏离了框架？

如果 Skill 流程规定留下每一阶段的中间产物，排查思路就清楚了：提纲结构扎实，问题就出在正文没有按框架展开；提纲本来就支离破碎，说明前面的信息提炼出了问题。沿中间产物往前查，就更容易找到出问题的阶段。

写作 Skill 的版本管理可以这样约定：

blog-posts/
└── YYYY-MM-DD-topic-name/
    ├── resources/
    │   ├── source-1-name.md
    │   └── source-2-name.md
    ├── OUTLINE.md
    ├── draft-v0.1.md
    ├── draft-v0.2.md
    └── final.md

当用户要求修改已有草稿时，Skill 应先读取现稿，再直接进入迭代流程，省去重复的资料收集和提纲阶段。

03 确认点设在尚未授权的决定上

确认节点设在尚未授权的重要决定上，例如提纲定稿或准备落盘。已经达成共识、上下文清晰的既定动作，可以在授权范围内继续执行。用户已说清目标、范围和动作，就在范围内继续。下面几类要特别核对：

• 覆盖请求外的重要文件，或执行影响未定的写入。
• 发布、部署、推送、提交和线上资源修改。
• 对用户材料作重大取舍，确定文章观点、品牌或产品口径。
• 大量删除、重命名或迁移。

范围不清就补齐，超出原请求就再确认。可以在 Skill 中明确写出等待点：

## 需要确认的节点

- 生成提纲后，必须等待用户批准或修改意见。
- 准备提交或推送前，必须说明将提交哪些文件。
- 涉及生产部署时，只允许用户显式触发。

例如用户已经给了资料、观点和结构，并要求直接写成新手博客，这次写作范围已清楚，可以继续成稿。若双方约定先看提纲，就把提纲做成可审查的结果，到约定位置等待。

随后又要求发布，新增的是发布动作。确认尚未明确的渠道和范围，并继续执行已经批准的动作。先找还缺哪个决定，再设确认点，流程会更自然。

部署、数据库迁移、批量删除或生产配置改动，还可以用 disable-model-invocation: true 保留手动入口，让 Claude 不会自行启动这个 Skill：

---
name: production-deploy
description: 执行生产部署前的检查和发布流程。只适用于用户明确要求部署、发布或上线的场景。
disable-model-invocation: true
---

不过谁来启动与启动后做什么，仍是两件事。目标环境、范围和失败恢复，要在方法里继续交代。启动权、免确认和真拦截怎样分开设，见Claude Code 只读命令为什么还能改文件。

Skill 也可以用 $ARGUMENTS、$0、$1 接收输入，用 !`command` 注入当前项目状态。动态上下文守住两条边界：只注入当前任务需要的信息，避免上下文膨胀；动态命令先于正文执行，只放短小的只读查询，需要确认的写入放到正文执行步骤。

04 description 决定什么时候启用

description 要具体说明触发场景、任务类型和边界。写得太泛会频繁误触发，写得太窄又会漏掉真实需求。

较弱的描述：

description: 帮助写内容。

更可用的描述：

description: 根据用户提供的主题、资料和目标读者撰写博客草稿。适用于用户要求写博客、整理文章提纲、基于资料起草长文、迭代已有草稿的场景。

描述写完，换几种说法试一试。用户说“看看这次能不能合并”，实际也在问行为风险和漏测；只写“输入 /review”或“review 当前分支 diff”，就可能漏掉它。反过来，“帮助写内容”又会把许多无关请求装进来。

先看任务要做什么，再选择描述它的说法。用不同措辞的同类请求、再加无关请求对照，才能判断这段 description 的范围是否合适。Claude Code 的 Skills 文档还提到，每个 Skill 的描述在列表里有长度上限，过长会被截断，所以把最关键的使用场景写在最前面。

05 用成对请求测试触发与执行

测试 Skill，不能只看“能否调用”，还要检查触发边界、执行顺序、材料加载和高风险确认点：

发布前用这张表做正向和边界测试。正向测试确认它能运行，边界测试确认它不会干扰无关任务。可以准备两个小测试：

测试 1：正向触发
请审查当前 diff，重点关注权限校验和测试缺口。

测试 2：边界测试
请解释这个函数的作用。

第一个请求应进入审查，第二个通常只需解释函数。若设置了 disable-model-invocation: true，第一个改用 /code-review 手动启动。

把观察分成两项：

带有“Findings”和“Impact”小标题的回答，可能只是模型惯常的输出格式。检查调用记录和实际读取记录，确认是否启用了 Skill，以及是否读取了 references/security-checklist.md。

回到开头那份不请自来的审查报告：问函数作用却进了审查流程，要通过“它到底读了哪些文件”和“在边界场景下会不会误触发”这两项检查交叉核实，才能确定 Skill 是不是按设想运行。

06 外部脚本授权前逐项检查

若安装的 Skill 会直接运行脚本，先核对实际文件与内容，再决定是否授予执行权限。外部脚本可能访问网络、文件或凭据，授予执行权限前逐项检查：

• 网络：是否发送请求，数据发往何处。
• 文件：是否写入文件或修改配置，位置是否属于任务范围。
• 凭据：是否读取 $TOKEN、$KEY 等敏感变量，如何使用。
• 依赖：需要哪些本机命令，缺失时如何报错。

检查过的脚本再逐个加执行权限，例如：

chmod +x ~/.claude/skills/refactor-helper/scripts/run-tests.sh

图省事对整个目录执行 chmod -R +x，等于一次性信任了所有还没看过的脚本。

07 四类常见问题

Skill 没有触发。先核对可发现位置、目录名、SKILL.md 和 YAML，再看名称与描述是否清楚、当前任务是否匹配，以及是否有更匹配的 Skill。

Skill 触发太频繁。可以这样调整：

• 收紧 description。
• 增加适用条件。
• 写清楚任务类型。
• 少用过宽泛的词，例如“帮助”“优化”“处理”。
• 把高风险 Skill 改为用户显式触发。

看不到支持文件。检查文件路径是否正确、文件是否在 Skill 目录下、脚本是否有执行权限、SKILL.md 中引用的文件名是否一致，以及当前会话是否需要重新加载。

执行偏离预期。常见原因包括：

• SKILL.md 只写目标，没有写步骤。
• 输出格式太模糊。
• 参考资料过多，缺少读取顺序。
• 用户确认点没有写清楚。
• 把多个不相关能力塞进同一个 Skill。

最后沿一次真实调用检查一遍：名称和描述是否清楚，是否只解决一个问题，输入、步骤、材料、输出与停止点能否接起来；高风险保护、支持文件的用途、脚本权限和依赖是否核对过；相关与无关任务的成对测试是否做过。文件该怎样组织才便于按需读取，见 把太长的 SKILL.md 拆成几个文件。

一个 Skill 能否放心交给团队，要看你能不能拿出调用记录和读取记录，证明它在该启用时启用、该停下时停下。