核心论点大多数人写 Skill 的心智模型是错的。他们把 AI 当成一个听话的下属——“我写清楚了它应该照做。” 然后困惑为什么 AI 读完 50 条规则该犯的错一条不少。真相是LLM 不是在遵守你的规则它是在一个概率空间中选择下一个 token。你的 Skill 所做的不是下命令而是改变这个概率空间的地形——让正确的输出路径变成下坡路让错误的输出路径变成需要翻越的高墙。一旦你用这个心智模型重新看待 Skill 设计很多技巧就不再是技巧而是必然的推论。一、为什么 90% 的 Skill 是废纸先看一个反面教材## Rules - 代码要有良好的错误处理 - 保持函数简短 - 注意性能 - 写清晰的注释这四条规则看起来合理但对 LLM 来说等于没写。原因有三第一模糊即自由。“良好的”“简短的”“注意”——这些词给了模型巨大的自由裁量空间。概率模型在有自由裁量空间时会倾向于选择生成概率最高的路径——也就是最平庸的输出。第二声明不产生动作。保持函数简短是一个状态描述不是一个动作指令。模型读完会知道这件事但知道 ≠ 执行。就像你知道该早睡但你还是在刷手机。第三没有验证闭环。规则写了但没有检查点。模型没有任何机制回头看看自己有没有遵守。它是逐 token 生成的注意力会随序列长度衰减开头的规则到 3000 token 时已经是远处的微弱信号。理解了这三个失败原因解决方案就清晰了消除模糊、制造动作、强制验证。二、Skill 的物理结构30 秒速览skill-name/ ├── SKILL.md # 唯一必需文件元数据 执行指令 ├── scripts/ # AI 可直接运行的脚本 ├── references/ # 按需加载的参考文档省 token └── assets/ # 模板和静态资源SKILL.md内部分两层┌──────────────────────────────────────────────┐ │ YAML Frontmatter~100 tokens │ ← 常驻内存用于触发判断 │ 只回答一个问题什么时候该用我 │ ├──────────────────────────────────────────────┤ │ Markdown 正文 5000 tokens │ ← 触发后才加载 │ 只回答一个问题具体怎么做 │ └──────────────────────────────────────────────┘唯一需要记住的铁律description只写触发条件绝不总结流程。否则 AI 会照着 description 干活跳过你精心设计的正文。# ❌ 把流程写进了 description —— AI 会跳过正文description:从稳定性、性能、可读性三维度审查代码先列问题再给建议# ✅ 只写触发条件description:当用户提交代码要求审查时使用三、五个设计模式核心章节以下不是建议是从 LLM 的生成机制推导出的必然策略。模式 1动作化——把名词变成动词LLM 看到动词时会启动执行看到名词时会表示理解。# ❌ 名词式声明知识 代码审查需要关注错误处理、边界条件和资源释放。 # ✅ 动词式触发动作 1. 搜索所有 async 函数检查每一个是否有对应的 try-catch 2. 列出所有外部输入参数逐个验证是否有 null/undefined 防护 3. 找到所有资源获取点连接、文件句柄确认每一个都有释放逻辑区别不只是更具体——而是前者让模型停留在理解状态后者把模型推入执行状态。这是两种完全不同的生成模式。转化公式注意 X → 搜索所有 X 的实例逐个检查 [具体标准]列出不合格项模式 2检查门——规则 × 检测 × 阻断单独的规则是建议。规则 检测方法 阻断条件才是约束。# ❌ 裸规则模型会忘记 函数不超过 30 行。 # ✅ 检查门模型不得不执行 ## 函数长度检查 1. 统计每个函数的行数 2. 行数 30 的函数标记为 WARNING 3. 行数 50 的函数标记为 BLOCK 阻断条件存在任何 BLOCK 级函数时必须先完成拆分建议才能继续后续步骤。检查门三要素组件作用缺失后果规则声明定义标准模型不知道标准检测动作强制模型去验证模型以为自己遵守了阻断条件不通过不能继续模型发现违规但跳过模式 3注意力锚点——对抗长序列遗忘LLM 的注意力分布不均匀开头和最近的内容权重最高中段最容易被忽略。这意味着在一个 3000 token 的 Skill 中你在第 200 token 写的规则到模型生成第 2000 个 token 时影响力已经大幅衰减。对策三层防御架构## Overview开头声明——第一次曝光 核心原则先完成根因分析再给修复建议。绝无例外。 ## Steps中段执行——第二次曝光 ### Step 3 完成后 → 中途自检 - [ ] 我是否已经完成了根因分析 - [ ] 我是否在没有根因的情况下给了建议 → 如果后者为是删除建议回到 Step 2 重做。 ## Final Checkpoint结尾拦截——第三次曝光 输出前最终确认 - [ ] 根因分析是否有完整的因果链至少 3 层 Why - [ ] 每条修复建议是否都能追溯到具体根因 未通过以上检查的内容不得出现在最终输出中。同一条规则出现三次但不是简单重复——开头是声明中段是动作化的自检结尾是阻断性的最终关卡。模式 4堵死逃逸路径——借口反驳表LLM 有一种行为模式我称之为优雅逃逸它会用看似合理的话术跳过困难步骤。这段代码比较简洁没有明显问题。 ← 翻译我不想逐行检查 建议用户自行验证。 ← 翻译我不确定但不想承认 其余部分保持不变。 ← 翻译我懒得输出完整内容解法把高频逃逸路径预置为被禁止的输出模式。## 禁止的输出模式 以下表述如果出现在你的输出中说明你正在偷懒必须删除并重做 | 禁止输出 | 应替换为 | |:---|:---| | 代码整体没有问题 | 列出你具体检查了哪些路径每条的结论 | | 建议用户自行测试 | 给出具体的测试命令和预期结果 | | 其余保持不变 | 输出完整内容或明确列出未修改的部分清单 | | 可能是 X 导致的 | 给出验证是否为 X 的具体步骤 | 触发上述任何一条时回退当前步骤重做。这不是提醒模型——这是在概率空间中设置路障。当模型即将生成代码整体没有问题这个 token 序列时它知道这条路径被明确标记为错误概率会显著降低。模式 5渐进式信息投放——控制认知负荷人的工作记忆容量是 7±2 项。LLM 的有效注意力窗口虽然更大但同样遵循信息越多单条信息影响力越低的规律。策略正文只放执行指令背景知识按需加载。## Step 2: API 兼容性检查 检查所有外部 API 调用是否符合 v3 规范。 详细规范见[API v3 迁移指南](references/api-v3-migration.md) 仅加载你需要检查的部分不要一次性读取整个文档。Token 预算分配原则内容类型位置理由触发条件YAML description必须始终在内存中执行步骤 规则SKILL.md 正文触发后加载是核心指令参考文档 100 行references/按需加载避免挤占注意力代码模板assets/需要时再读取自动化脚本scripts/AI 调用即可无需理解全部四、四种 Skill 骨架选对骨架再填内容事半功倍。A. 工作流型触发 → Step 1 → [产出物] → Step 2 → [产出物] → ... → 交付 ↓ 失败 异常处理 / 回退 / 升级用于步骤有明确先后依赖关系的任务。B. 检查清单型加载清单 → 逐项检查 → 标记状态Pass/Warn/Block→ 汇总 → 判断是否通过用于确保覆盖面的审查型任务。C. 生成器型接收输入 → 校验输入完整性 → 按模板生成 → 校验输出质量 → 交付用于从少量输入产出标准化文档。D. 分析决策型收集现象 → 强制多维度分析 → 根因推导 → 方案对比 → 输出结论 ↑ 借口反驳表拦截偷懒用于需要深度思考、防止浅层回答的场景。五、完整示例代码审查 Skill将上述所有模式整合为一个可直接使用的 Skill---name:code-reviewdescription:当用户提交代码片段或 diff 要求审查时使用。 不适用于代码生成、格式化、简单语法纠错。---# Code Review ## Core Principle 先理解意图再逐项审查最后结构化输出。 禁止只看前 20 行就开始下结论。禁止输出整体不错类空话。 ## Steps ### Step 1: 全局理解 - 通读所有提交的代码 - 用一句话概括这段代码的目的是 ____ - 识别核心逻辑路径和数据流方向 ### Step 2: 三维度审查 对每个维度执行检查门 #### 稳定性 1. 搜索所有 async/await 调用 → 每个是否有 try-catch 或 .catch 2. 列出所有外部输入 → 每个是否有 null/undefined/类型校验 3. 找到所有资源获取点 → 每个是否有释放/关闭逻辑 4. 识别并发场景 → 是否有竞态条件风险 #### 性能 1. 识别所有循环 → 有无嵌套循环可降低复杂度 2. 搜索重复计算 → 是否可缓存或提取 3. 找到 I/O 操作 → 是否可批量化或并行化 #### 可读性 1. 统计每个函数行数 → 30 行标记 WARNING 50 行标记 BLOCK 2. 检查所有命名 → 是否能脱离上下文理解含义 3. 搜索魔法数字和硬编码 → 逐个判断是否应提取为常量 ### Step 2.5: 中途自检 ⚠️ - [ ] 三个维度是否每个都实际检查了不是声明已检查是有具体发现或检查路径 X未发现问题 - [ ] 是否有跳过的检查项如有补做。 ### Step 3: 结构化输出 ## Output Format ### 一句话总评 [具体描述主要问题类型和严重程度分布] ### 问题清单 | # | 维度 | 等级 | 位置 | 问题 | 修复建议 | |:--|:-----|:-----|:-----|:-----|:---------| 等级定义 - P0: 会导致运行时错误或安全漏洞必须修 - P1: 影响可维护性或性能强烈建议修 - P2: 代码质量优化可选 ### 亮点如有 [具体指出设计优秀之处及原因] ## Forbidden Outputs | 禁止出现的表述 | 替代方案 | |:---|:---| | 代码整体质量不错 | 指出具体的优秀设计或不写亮点部分 | | 建议添加更多测试 | 给出具体应该测试哪些路径 | | 可能存在性能问题 | 量化什么输入规模下、什么复杂度、影响多大 | | 其他部分没有问题 | 列出你检查了哪些路径每条的结论 | ## Escalation - 代码超过 500 行 → 建议用户分批提交 - 发现安全漏洞 → 置为 P0输出开头加 标记 - 无法判断业务意图 → 先提问确认不要猜测后审查 ## Final Gate 输出前扫描自己的回答 1. 是否触发了 Forbidden Outputs 中的任何一条→ 删除重写 2. 每个维度是否至少有一条具体发现含已检查无问题→ 补全 3. 每条修复建议是否具体到可直接实施→ 模糊的要补充代码示例六、Skill 写完后的调试循环写完不是结束是开始。好的 Skill 是调试出来的不是设计出来的。调试方法对抗性测试写完后故意用以下方式测试你的 Skill1. 给它一个极简输入看它会不会偷懒 2. 给它一个超长输入看中段规则是否被遗忘 3. 给它一个边界 case看异常处理是否触发 4. 连续跑 3 次同样的输入看输出一致性迭代公式每次 AI 犯错 → 分析属于哪种失败模式 模糊导致的 → 加量化标准 没执行 → 把名词改成动词 中段忘了 → 加中途检查点 找借口跳过了 → 加进 Forbidden Outputs 超出能力了 → 加 Escalation 条件记录每次修改的原因哪怕一行注释三个月后你会感谢自己。七、设计原则速查#原则一句话1单一职责一个 Skill 只做一件事2动作优先动词 名词指令 声明3量化一切能写数字的地方绝不写形容词4三层防御开头声明 中途自检 结尾拦截5堵死逃逸预判偷懒路径设为禁止输出6渐进披露正文 500 行背景知识按需加载7人工兜底超出能力时停止不要硬撑8持续调试每次翻车都是下一条规则的来源结语回到开头的核心论点你不是在告诉 AI 做什么。你是在一个高维概率空间中——用动作指令降低正确路径的生成阻力用检查门和阻断条件抬高错误路径的生成成本用注意力锚点确保关键约束在整个生成过程中持续施加影响。这就是 Skill 设计的全部本质。当你用这个视角审视自己写的每一行指令时你会自然地问出正确的问题“这句话会改变概率分布吗还是只是让我自己感觉写了”“这条规则有检查机制吗还是全靠 AI 自觉”“3000 token 之后这条约束还能被’感知到’吗”能诚实回答这三个问题的人写出的 Skill 不会差。