Skill 设计原则

Skill 设计的七个核心原则

一个合格的 Skill 靠工程。七条原则背后其实是两条主线：省——token 是稀缺资源；稳——行为必须可预期。

Skill 和普通提示词的本质区别在于：它的读者不是人，而是另一段推理流程。它会被反复调用、需要被精准路由、必须接受度量。因此它的设计标准更接近软件接口而非文章——要能触发、能约束、能测试。理解了这一点，七条原则就都有了着落。

七条原则在开发流程上的分工也很清晰：动笔之前用原则 1、7 决定写什么，写作时用原则 3、4 决定怎么写，装载时靠原则 2 怎么省，运行时靠原则 5 怎么兜底，发布前靠原则 6 怎么证明它好用。

一、内容层：只写模型搞不定的部分

1.1 原则一：模糊逻辑进 Skill，确定性逻辑外包

动笔前先问一个问题：“这一步有没有唯一的标准答案？”

• 有——数学计算、格式转换、正则匹配、API 调用。计算机执行 100% 一致，交给模型手算反而出错。这类逻辑写入脚本或 MCP 工具。
• 没有——意图识别、情感判断、内容取舍、复杂决策。这正是模型的价值所在，写入 Skill 正文。

一句话：Skill 是大脑，负责判断"做什么"；脚本和 MCP 是手脚，负责执行"怎么做"。 大脑不该亲自做加减法。

改写示例：

• ✗ 在 Skill 里写：“逐行读取日志文件，按小时聚合错误数量，再用正则提取 error code。”
• ✓ Skill 只写：“调用 log_stats.py 聚合错误分布；若脚本报错或结果为空，结合上下文解释可能原因。”

1.2 原则七：最小够用，只写模型不知道的

模型已经掌握了海量通用知识。重复常识不仅浪费 token，还会稀释关键指令的注意力权重——正文越长，真正要紧的规则被忽略的概率越高。三条自检：

1. 删常识：凡模型本来就知道的（某格式是什么、某库怎么装），一律不写。
2. 聚焦差异：只保留业务特有、模型容易做错的内容——内部命名规范、特殊鉴权头、约定的回复话术风格。
3. 高信噪比：删掉某句话不影响任务执行，就删掉它。每一行都必须有存在的理由。

改写示例：

• ✗ “使用 Python 处理数据，Python 是一种解释型编程语言……”
• ✓ “用 pdfplumber 抽取合同文本；跨页表格需按表头拼接。”

二、表达层：让指令不可被误解

2.1 原则四：命令式语气，祈使句开头

Skill 是给 AI 的操作手册，不是建议指南。“你应该”"可以尝试"这类语气给模型留出了解释空间，执行结果就开始漂移。两条规则：

1. 消除"我"和"你"，以动词开头：“扫描错误日志……”“提取关键字段……”“格式化为 YAML……”
2. 复杂的格式要求不要解释，直接给示例。模型的模仿能力远强于理解抽象规则的能力——一个 Input → Output 少样本示例胜过三段说明文字。

改写示例：

• ✗ “你可以尝试用 YAML 输出，这样可能更好解析。”
• ✓ “输出必须为合法 YAML。示例：error: null 与 items: [] 两个顶层键。”

2.2 原则三：触发描述 = 能力 + 场景

Description 是 Skill 的门面和路由器——AI 只靠这一行字决定调不调用。描述模糊的结果是双向的：不需要时误触发（浪费资源），需要时被忽略（能力失效）。

一个合格的 Description 由三部分组成：

• 能力定义：第三人称、动名词开头，说清"做什么"。
• 触发场景：明确指出用户说什么话、上传什么文件时激活。
• 边界补充（可选）：什么情况下不该触发，防止误伤。

关键词要显式埋入描述中——Skill 靠向量检索和关键词匹配被召回，触发词不在描述里，就等于不存在。

改写示例：

• ✗ “图片助手”
• ✓ “压缩用户上传的 PNG/JPG 图片至 200KB 以内并保持宽高比；当用户上传图片或提到’压缩图片’时触发；不处理 GIF 与视频。”

三、装载层：上下文是稀缺资源（原则二）

上下文窗口是所有 Skill 共享的公共内存。一次性全量加载带来三重代价：延迟上升、成本上升、模型注意力被稀释——细节越多，重点越容易被淹没。解法是三层加载架构：

• L1 钩子（常驻）：系统提示词中只保留 name + description，控制在 100 token 内。这是路由决策的唯一依据，必须极短。
• L2 正文（触发加载）：AI 决定调用时才进入上下文。只放核心工作流与关键规则，控制在 500 行 / 5k token 内。
• L3 资源（按需引用）：API 文档、JSON Schema、参考代码不进正文，用相对路径引用（如 ./references/api_spec.md）。模型读了才计费，不读零成本。

核心心态：把 Skill 设计成目录，而不是百科全书——引导模型去查阅详情，而不是把详情直接喂给它。

改写示例：

• ✗ 把 40 页 API 文档整体贴进正文。
• ✓ “调用 API 前先读 auth.md 的鉴权规则；参数结构见 schema.json。”

四、护栏层：为失败而设计（原则五）

模型天然倾向"讨好"用户——遇到做不了的事，它宁可硬答也不说不行。Skill 必须充当安全护栏，替模型把"不"说出口。四个要点：

1. 否定约束：明确列出禁令——“严禁直接执行 DELETE 语句”“不修改原始文件，只生成副本”。
2. 失败与降级：每个关键步骤写清死胡同的出口。数据缺失时返回什么错误码（而不是编造）；接口异常时重试几次、超了怎么办。
3. 转人工条件：什么情况下必须停止执行、引导至人工——越权的代价远高于一次拒绝。
4. 高风险操作设确认门槛：删除、发送、支付类动作，要求用户显式授权。

一句话：只写成功路径，Skill 只完成了一半；把所有失败路径写清楚，才算合格。

改写示例：

• ✗ “调用退款接口完成退款。”
• ✓ “调用退款接口；若返回 429，按 Retry-After 等待后重试一次，仍失败则返回错误码 REFUND_RETRY_FAILED 并转人工；单笔金额超过 5000 元时只生成审核单，不直接执行。”

五、闭环层：Skill 是代码，不是文章（原则六）

"感觉挺好用"不是发布标准。Skill 必须像软件一样，有明确的通过/失败判定。工程化闭环三件套：

1. 定义成功指标：格式符合率（输出是否符合 Schema）、逻辑正确率（计算是否精确）、触发召回率（100 个相关查询里命中了多少次）。
2. 构建测试集：正例 10 条（应该触发的输入）、反例 10 条（相似但不该触发的输入，防误触）、边缘用例若干（空输入、乱码、超长输入）。
3. 回归机制：每次改动重跑全量测试集，防止"修一个 Bug，引入两个新 Bug"。维护 tests/ 目录 + 自动化脚本，而不是在聊天窗口里手动试一次就上线。

发布前五问

把上面的原则压缩成一张自查清单，发布任何 Skill 之前过一遍：

1. 内容：还有哪句话是模型本来就知道的？删掉。
2. 触发：随便挑一条用户输入，AI 能在众多 Skill 里准确选中这一个吗？
3. 语气：正文里还残留"你应该""可以尝试"吗？
4. 失败：找不到数据时，AI 知道返回什么错误码、何时转人工吗？
5. 证据：正例反例各 10 条跑过了吗？上一次的触发召回率是多少？

七条原则归根结底是两件事：把 token 花在刀刃上，把不确定性关进笼子里。 省与稳——这就是 Skill 设计的全部秘密。