本文基于真实企业 AI 助手开发经验，以明道云文印登记场景为例，总结 Claude Code Skill 编写的 8 条核心规律。

前段时间，有个同事找我说 AI 帮他登记了一条文印记录，但他根本没打印过那个东西。

去查日志，发现 AI 把用户的描述当成了事实，直接"脑补"了一条记录，格式完整，字段齐全，就是数据是假的。

这不是 AI 的 bug，是 Skill 没写好。

从那次之后，我开始认真对待 Skill 的编写。现在回头看，踩过的坑基本都能归结为这 8 条规律。

---

什么是 Claude Code Skill

Skill 是 Claude Code 的一种扩展机制，本质上是给 AI 的 SOP（标准操作流程）。

你在项目里放一份 SKILL.md，Claude 识别到对应场景时就按你写的流程执行。写得越细，AI 越听话；写得越模糊，AI 越自由发挥。

类比到 Java 开发：Skill 就像接口定义加上详细的 Javadoc。你不写清楚前置条件、异常处理、返回格式，调用方就会按自己的理解来。

---

8 条核心规律

1. 触发词穷举，宁多勿少

Skill 的 description 字段决定 AI 什么时候触发这个 Skill。只写一两个关键词，用户换个说法就不触发了。

正确做法——列举所有可能的用户表达方式：

文印登记：管理文印登记记录。当用户提到"文印登记""打印登记"
"复印登记""我要打印""帮我登记打印""查看打印记录""文印记录"
"登记复印""文印""打印登记单""复印记录""我的文印""文印查询"
"加急次数""加急记录""查看加急"等时触发。

规律：description 里触发词至少 10 个以上，覆盖"正式说法"“口语说法”"缩略说法"三类变体。

---

2. 安全铁律置顶，用视觉强调

AI 的默认行为是"尽力帮你"——遇到不确定的情况会补全、推断甚至编造。

在 Skill 第一行明确禁止：

⚠️ **最高优先级：你必须使用 Bash/Terminal 工具实际运行脚本，
严禁凭空捏造结果。回复内容必须 100% 基于脚本的真实输出。**

"最高优先级"这四个字很关键。AI 处理 Skill 时会权衡不同规则，加上这个标记，这条规则会压过后面所有内容。

规律：涉及数据真实性的操作，必须在顶部明确禁止编造，视觉强调（粗体 + 警告符号）。

---

3. 歧义字段用对比表消灭

业务字段里经常有容易混淆的概念对，靠 AI 自己猜会猜错。

文印场景里"份数"和"页数"就是典型案例，Skill 里专门写了辨析表：

用户表达	映射到字段
“打印10份”“印10份”“学生10人”	份数 = 10
“共5页”“每份5页”“A4纸5张”	页数 = 5
“打印10份，每份5页”	份数 = 10，页数 = 5
“打印10份”	份数 = 10，页数留空追问

规律：任何在业务上容易混淆的概念，用表格形式明确映射关系，不依赖 AI 推断。

---

4. 信息收集要"自然追问"，不要列参数清单

写"缺少必填字段时询问用户"，AI 会问出这种话：

“请提供以下信息：1. 文件名称 2. 年级 3. 学科 4. 份数 5. 页数 6. 是否加急”

用户体验像在填表格，很差。

正确写法：

缺少必填项时，自然追问（不要列出参数清单）。

加了这一句，AI 会说：“好的，请问要打印什么文件？需要多少份？”——正常对话节奏。

规律：明确指定期望的交互风格，AI 会模仿。不指定，AI 会选最"完整"而非最"自然"的方式。

---

5. 写操作必须分轮次确认

早期 Skill 写"收集完信息后确认，确认后执行 add"，AI 在同一轮回复里既展示了确认信息，又调用了 add 命令。用户还没看清楚，数据已经写进去了。

正确写法：

⚠️ 二次确认必须分步执行：回显确认信息时，当前回合绝不能同时
调用 add 命令。必须等用户在下一轮对话中明确回复确认后，才在
新的回合中执行 add 提交。

"当前回合绝不能"是关键表达，明确把确认和执行拆成两个交互轮次。

规律：涉及写操作（add/edit/delete），确认和执行必须强制分轮次，不能只写"先确认再执行"。

---

6. 错误处理穷举，给 AI 准备好用户话术

AI 遇到没有明确处理规则的错误时会自己发挥——有时把技术报错原样给用户，有时编一个"合理"的解释。

正确做法是写完整的错误处理表：

情况	回复用户
加急次数不足	“该学科组剩余加急次数不足，请将「是否加急」改为「否」后重新提交”
查询结果为空	“暂时没有查到文印登记记录”
人员匹配歧义 (code=409)	展示候选人员列表，让用户选择后重新查询
无权操作 (code=403)	“您只能修改自己的文印记录”
系统异常 (code=500)	“系统出了点问题，请稍后再试”

规律：错误处理要穷举每种 error code 对应的用户话术，不能只写"处理异常"。

---

7. 禁止清单和业务逻辑同等重要

业务流程告诉 AI"要做什么"，但你还需要明确告诉它"不能做什么"。

我的 Skill 里有专门的执行约束章节：

🔴 严禁在回复中展示任何命令（bash、python、脚本调用）
🔴 严禁在回复中暴露脚本路径、文件路径
🔴 回复数据只能来自脚本的实际返回结果，严禁编造
🔴 禁止自己编写代码替代脚本执行

不写这些约束，AI 会把内部命令展示给用户，会把路径信息暴露出去，会用推断的数据填充结果。

规律：每个 Skill 都要有"禁止清单"章节，用红色标注，放在显眼位置。

---

8. 边界情况给正反例

光写"正确写法是 X"还不够。AI 在不确定时会选"看起来最合理"的写法，而不一定是你期望的那个。

文印登记 Skill 里附件字段有这样一个对比表：

写法	正误	说明
[{"fileName":"a.pdf","url":"https://..."}]	正确	原生 JSON 数组
"[{\"fileName\":\"a.pdf\",\"url\":\"https://...\"}]"	错误	被引号包成了字符串

正反例并列，AI 遇到边界情况时能对照着判断自己是否走偏。

规律：格式要求严格的字段，必须给正例和反例，并说明错误的原因。

---

Skill 编写 Checklist

每次写完 Skill 对照检查：

• description 触发词写了 10 个以上，覆盖口语/书面/缩略三类说法
• 数据安全铁律置顶，有视觉强调
• 业务歧义字段有对比映射表
• 信息收集明确写了"自然追问，不列参数清单"
• 写操作有"分轮次确认"约束
• 错误处理表穷举了所有 error code 对应的用户话术
• 有"禁止清单"章节，用醒目格式
• 边界情况有正反例

---

总结

Skill 本质上是给 AI 写的操作手册。写得越细，AI 越听话；写得越模糊，AI 越自由发挥。

核心原则：把你希望 AI 做的和不希望 AI 做的，都明确写出来。

AI 不会因为没写就自动猜对，但会因为没写就自动猜——猜对是运气，猜错是常态。

---

完整的文印登记 Skill 源码和本文的 Skill 编写 checklist，在知识星球「Java转AI实战内参」。