我踩过的坑是90%新手的必经之路——把Skill等同于"把所有要求堆进去的大段提示词"。但工业级Skill本质是可测试、可维护、可扩展的模块化Agent组件，它有严格的开发流程和工程规范，而不是一次性的prompt。

先纠正一个核心误区

错误认知：Skill = 超长提示词，把所有规则、流程、文档都塞进去
正确认知：Skill是一个有明确触发边界、分层执行逻辑、可量化评估标准的独立功能单元。它的核心是"什么时候做" > "怎么做"，且必须通过工程化手段保证稳定性。

工业级Skill开发全流程（5+1步）

Step 0：先写Evals（评估先行，最重要的一步）

没有Evals的Skill就是半成品，改Skill就是盲改。Evals不是上线前的"测试一下"，而是开发的起点，它定义了Skill的成功标准。

一个合格的Eval集必须覆盖3类用例（优先级：负例 > 边界 > 正例）

用例类型	测试目标	示例（PR审核Skill）
正例（Positive）	验证应该触发的场景能正确触发	"帮我盯着这个PR的CI"、"这个PR能不能合"
负例（Negative）	验证不该触发的场景绝对不触发（头号失败模式）	"帮我格式化代码"、"写一个PR模板"
边界用例（Edge）	验证模糊场景下的路由正确性	"这个PR只改了一行日志，需要审吗"

结合你提供的三层评估体系，完整的Eval测试维度

这正是Perplexity等顶尖公司的Skill评估标准，也是大厂MR必查项：

1. Skill加载精度测试（最基础也最致命）

• • 测什么：路由的精确率（precision）、召回率（recall）和禁止触发（forbidden）场景
  • 怎么测：批量跑100+条真实用户查询，统计load_skill()的调用正确率
  • 验收标准：负例误触发率必须为0，正例召回率≥95%

1. 渐进式加载测试（解决你1200行MD的问题）

• • 测什么：Skill加载后是否只读取必要的附属文件，有没有冗余读取
  • 怎么测：监控Agent的文件读取行为，验证只有满足条件时才加载对应references
  • 验收标准：核心场景不读取非必要文件，异常场景能正确触发对应文档加载

1. 端到端任务完成度测试

• • 测什么：Skill最终能不能帮用户把事情做成
  • 怎么测：全Agent循环执行 + LLM Judge按预设评分标准（rubric）自动打分
  • 验收标准：核心场景成功率≥90%，无严重错误

额外要求

• 必须在所有支持的编排模型（GPT-4o、Claude 3.5 Sonnet等）上分别跑Eval，不同模型的路由行为差异极大
• 每次修改Skill都必须回归完整Eval集，防止一个改动搞坏已有的10个Skill

Step 1：写Description（最难的一行，决定80%的质量）

Description是路由触发器，不是文档。它的唯一目标是：在正确的时间加载Skill，且绝不误触发。

黄金法则

糟糕的description描述Skill做什么，好的description说用户什么时候会需要这个Skill。

正反示例对比（PR监控Skill）

错误写法（描述做什么）：

这个Skill用于监控PR的CI状态，审核代码变更，检查是否符合合并条件，帮助工程师合并PR。

正确写法（描述触发时机）：

Load when the user asks to babysit a PR, watch CI, make sure a PR lands, or check if a PR is ready to merge.

快速检查清单（必须全部满足）

1. 严格以Load when…开头
2. 控制在50词以内，越短越精准
3. 全部使用真实用户查询中的原话，不要自己发明说法
4. 绝不总结工作流程，绝不提Skill内部实现

Step 2：写Body（执行逻辑：少教步骤，多讲规则）

跟LLM讲工作流程和跟人讲完全不同：模型已经知道99%的通用工具用法，你只需要告诉它那1%的特殊规则。

核心原则

1. 跳过模型已经懂的部分
   不要写：git log → git checkout main → git checkout -b clean-branch → git cherry-pick <commit>
   要写：Cherry-pick the target commit onto a clean main branch. Resolve conflicts preserving the original intent. If it cannot land cleanly, explain the blocking issues.
2. 聚焦Gotchas和反例（最高信噪比的内容）
   这是Skill的核心价值所在。每次Agent搞砸了，就把对应的坑加进去：

⚠️ Gotchas:

• Do not merge PRs with "WIP" in the title, even if CI passes
• Always tag the author if there are unresolved comments
• Skip unit test checks for documentation-only changes

1. 用高层级指令代替细粒度步骤
   太死板的指令比灵活的指令更脆弱。LLM擅长处理异常情况，给它目标和边界，而不是每一步该怎么走。
2. 所有重内容和条件逻辑必须移出Skill.md
   这正是1200行MD被打回的核心原因。把超过100字的文档、API说明、错误处理指南全部放到references/目录，条件触发才加载。

Step 3：用标准层级结构组织文件

工业级Skill必须是模块化的，而不是一个单文件。通用目录结构如下：

your-skill/
├── SKILL.md           # 核心文件：description + 执行逻辑 + 依赖声明
├── scripts/           # 确定性逻辑（Python/Shell脚本），模型直接调用
├── references/        # 重型文档，条件触发读取
│   ├── api-docs.md
│   └── error-handling.md
├── assets/            # 输出模板，模型直接复制填充
│   └── pr-report-template.md
└── config.json        # 首次运行配置，问一次永久保存

各目录设计意图

• scripts/：把重复的、确定性的逻辑写成代码，避免模型每次重新发明轮子，大幅提高一致性和效率
• references/：实现渐进式加载，只有当需要时才读取对应文件，减少上下文浪费（比如只有API报错时才读error-handling.md）
• assets/：统一输出格式，减少模型在格式上的精力消耗
• config.json：避免重复询问用户相同的问题

复杂Skill的拆分

如果一个Skill超过300行，或者包含多个独立子功能，必须拆成一组小Skill，用depends:声明加载关系。比如"PR全流程Skill"可以拆成：

• pr-monitor.skill（监控CI）
• pr-review.skill（代码审核）
• pr-merge.skill（合并PR）

Step 4：基于Evals的迭代

1. 切独立分支开发，不要在主分支上直接改
2. 先在无Skill的状态下跑核心用户场景（hero query），建立基准线
3. 每次修改只改一个点，改完立即跑完整Eval集
4. 重点关注溢出效应：description的一个小词改动，可能会导致其他Skill的路由异常
5. 提交MR时必须附带：

• • 完整的Eval集运行结果
  • 本次改动影响的用例列表
  • 新增的Gotchas和反例

Step 5：灰度发布与监控

1. 先给10%的内部用户灰度
2. 实时监控三个核心指标：

• • 路由准确率（误触发率）
  • 任务完成率
  • 平均响应时间

1. 收集用户反馈，持续更新Eval集和Skill本身
2. 全量发布后，保留一周的回滚能力

写好Skill的5条核心原则

1. 评估先行：没有Evals就不要写Skill，Evals是Skill的一部分
2. 边界优先：先定义"什么时候不做"，再定义"做什么"
3. 最小上下文：只给模型当前需要的信息，其他全部延迟加载
4. 容错设计：假设模型会犯错，用Gotchas和Evals提前堵住坑
5. 持续迭代：Skill不是写完就完事了，它会随着用户需求和模型升级不断进化

新手最容易犯的6个错误

1. 把Skill写成大段提示词，所有内容都塞到SKILL.md里
2. 先写Skill再写Evals，凭感觉改description
3. description写得太泛，导致大量误触发
4. 事无巨细地写步骤，限制了模型处理异常的能力
5. 只在一个模型上测试，忽略了模型差异
6. 不维护Evals，导致Skill越改越烂