Skill 开发最佳实践
核心要点
-
Description 是 Skill 的触发器——写得太笼统 AI 不知道啥时候该用，写得太窄很多该触发的场景会漏。用”触发评估”方法（准备 20 个问题，一半该触发一半不该触发）来校准。
-
Skill 不是免费的——每加载一个 Skill 都占上下文窗口。Level 1（name + description）约 50-150 Token/个，Level 2（SKILL.md 正文）约 2,000-5,000 Token。装 20 个 Skill 光元数据就吃 1,000-3,000 Token。
-
三层渐进式加载机制——Level 1 元数据常驻、Level 2 正文按需加载、Level 3 脚本/参考资料按需引用。核心原则：Level 1 越精准越好，Level 2 越精简越好，Level 3 放心放。
-
SKILL.md 控制在 500 行以内——超过就拆成主 Skill + 子 Skill。一个 Skill 只管一件事，多件事用模块化架构编排。
-
Few-Shot 比文字描述有效得多——3-5 个高质量示例（覆盖典型、变化、边界场景），AI 表现会稳定很多。先放最典型的，AI 更倾向模仿前面的示例。
-
用祈使句下指令，解释”为什么”——“必须使用参数化查询”不如”使用参数化查询而非字符串拼接，因为字符串拼接会导致 SQL 注入漏洞”。AI 理解了背后的道理，遇到未预见的情况也能合理判断。
-
工程化评估是质量分水岭——Skill Creator 支持触发评估（Precision/Recall）和效果评估（有 Skill vs 无 Skill 对比），从”凭感觉”升级到”跑数据”。
-
六大反模式要避免：大杂烩 Skill、Description 黑话、没有示例、没有验证点、写死数值、当 Wiki 写。
-
安全是底线——绝不硬编码敏感信息、危险操作必须确认、数据库操作先备份、防范 Prompt 注入。
-
MCP vs HTTP 的选择——已有 MCP Server → 优先用 MCP；需要多平台复用 → 封装 MCP；简单一次性调用 → 脚本直接 HTTP。
-
高精度步骤脚本化——接口提取、目录索引、编译验证这类确定性环节不要交给模型自由发挥。淘宝企业购把接口提取从模型中剥离出来，由脚本解析后再让 AI 校验补漏，避免错误沿流水线逐级放大。
-
长链路拆子 Skill——一个 Skill 不应承载超长文档和多个复杂接口的全部推理。可用编排 Skill 负责总流程，子 Skill 独立处理单接口、单阶段或单评审点，再由汇总步骤组装结果。
-
先例子后能力，先边界后正文——不要从抽象能力开始写 Skill。先收集真实触发请求、输入输出、失败点和成功标准，再规划 scripts / references / assets。没有具体例子就开始写，往往会得到宽泛但不可执行的说明。
-
description 只负责触发，正文才负责执行——description 应覆盖做什么、何时使用、典型触发词和不适用边界，但不要写完整流程。完整流程放进
SKILL.md和模块文件，否则 Agent 可能只凭 description 的印象执行，跳过真正的约束和验证。