一、高质量 Skill：结构、写法与反模式
1.1 Skill 三层架构：按需加载的系统工程
错误的思路是把所有的团队知识和执行细节全塞进一个超长的 Markdown 里。 这种做法不仅拉高了单次调用的上下文成本，还会严重模糊触发边界。
Skill 架构本质上是一种按需加载的系统级路由机制。这也是 Anthropic 官方文档把较长的资源文件和可执行脚本列为“触发后延迟读取”项的原因。对高频调用的 Agent 来说，严格的分层不是补充项，而是系统性能和准确率的门槛。
| 架构层 | 工程定位 | 写坏的后果 |
|---|---|---|
| Metadata | 路由触发器 | 抢错任务，或该用时毫无反应 |
| Instructions | 契约与流程边界 | 执行顺序错乱，输出结构不稳定 |
| Resources/Scripts | 卸载确定性动作 | 产生旧知识幻觉，每次执行动作随机 |
1.2 Skill 从哪里来：基于“容错补丁”而非“百科全书”
先建立大而全的知识资产，再做成 Skill，是典型的错误路径。
真正高收益的 Skill，只诞生于“高频、有明确标准且容易被反复做错”的场景。模型训练时的知识是静态固化的，如果不处理这种代差，系统通常会出现持续输出旧版本 SDK 写法和忽略边缘异常的后果。
Google 的文章《Closing the knowledge gap with agent skills》指明： 模型知识固定在训练时点，但 SDK 和最佳实践一直在变；这会持续制造模型自己很难消除的 knowledge gap。Google 给 Gemini API developer skill 放进去的，也不是整套百科，而是能力概览、当前 SDK 信息、基础样例和官方文档入口。这个设计本身已经说明了 Skill 的角色：不是替代文档，而是把 Agent 带到正确的做法上。
Anthropic 的文档《Skill authoring best practices》指明： Skill 不是 conversation-level 的一次性提示，而是按需加载的能力单元：metadata 常驻但很轻，主说明只在触发后加载，资源文件和脚本按需读取或执行。这样做的目的很明确：不要把所有方法长期压进上下文，只把当前任务真正需要的那部分带进来。
1.3 核心写法：边界优于细节
把 Description 当作人类阅读的“宣传位”来写，是导致误触发的罪魁祸首。
- 先写触发条件：description 不是宣传位，而是路由入口。description 一旦写宽，后面的评测结果几乎一定会跟着变差，因为它先在入口处把任务抢错了。
- 再写步骤：高质量 Skill 很少靠“背景介绍很完整”取胜，更多靠步骤顺序、判断点和输出契约。
- 易变信息外置：只要内容变化快，就别硬编码进 SKILL.md。SDK 版本、接口参数、模型列表、能力矩阵，这类信息一旦写死，很快就会开始稳定输出旧做法。
- 确定性逻辑脚本化：能稳定执行的动作，不要继续留给模型临场发挥。能用 Python/Bash 稳定运行的数据处理，绝不交由模型临场生成。
- 必须在真实任务里跑：看起来合理的 Skill，上线后很可能没有任何增益。
1.4 反模式与致命陷阱
很多 Skill 失败得并不难看：它们不会报错，也不会立刻失效。更常见的情况是：开始稳定地产生旧做法，抢错任务，或者根本没有带来可见增益。
以下是被反复验证的反模式：
- 只写'这个 skill 很擅长 X'，却没写什么时候不用它
- 把团队知识全塞进一个超长 SKILL.md，导致加载成本高、边界模糊
- 没有示例输入输出，导致模型知道原则却不知道落地样子
- 没有退出条件，循环类 skill 一直修、一直改
- 把脚本当成魔法黑盒，既不说明输入输出，也不做错误处理
- 把高风险动作直接自动化，没有人工审核点
- skill 与 agent 角色重叠：既路由又执行又评审，职责失焦
- 从来不做评测，只凭'感觉模型会用'
- Skill 经常误触发
1.5 Skill 避坑指南
核心编写原则
1. 描述字段（Description）是写给 AI 看的触发器，不是写给人的总结
- 技巧：Claude 在决定是否调用某个 Skill 时，会扫描所有 Skill 的 description。因此，描述不应该只是"这是一个写代码的技能"，而应该明确写出"在什么场景、遇到什么请求时，应该触发这个技能"。
2. 重点写"避坑指南（Gotchas）"
- 技巧：在文档中专门建立一个 Gotchas（常见错误/陷阱）部分。这是整个 Skill 中价值最高的内容。
- 做法：记录 Claude 在使用该技能时最常犯的错误，并不断更新这个列表，明确告诉它"不要做某事"。
3. 不要写废话（提供反常识/打破常规的知识）
- 技巧：Claude 本身已经懂很多代码知识和常规默认做法。高质量的 Skill 应该提供能"打破 Claude 固有思维"的信息。
- 案例：比如前端设计技能，不要教它怎么写 HTML，而是教它"提高审美"，告诉它避免使用默认的 Inter 字体和老套的紫色渐变。
4. 给 AI 留有余地，不要过度死板
- 技巧：因为 Skill 要被反复复用，指令如果写得太死，会限制 AI 的发挥。应该提供必要的信息和边界，但给予 AI 根据具体情况灵活变通的空间。
架构与上下文管理（把 Skill 当作系统来设计）
5. 利用文件系统进行"渐进式披露"
- 技巧：一个 Skill 不要只写在一个巨大的 Markdown 文件里，它应该是一个文件夹。把大任务拆分，让 Claude 在适当的时候去读取特定文件。
- 做法：把详细的 API 文档放在
references/api.md里；把输出模板放在assets/里。主文件只做引导，告诉 Claude"需要时去哪里看什么文件"。
6. 为 AI 提供现成的脚本和代码库
- 技巧：与其让 AI 每次从头写模板代码，不如直接在 Skill 文件夹里提供现成的辅助脚本（Helper functions）或类库。
- 好处：这样 Claude 就可以把算力和时间花在"业务逻辑编排"和"高阶分析"上，直接调用你写好的底层脚本，大大提高成功率。
高阶功能设计（交互与记忆）
7. 设计优雅的"初始化配置"流程（Setup）
- 技巧：很多技能需要用户上下文（比如：要把日报发到哪个 Slack 频道？）。
- 做法：在目录中放一个
config.json。如果配置为空，可以通过指令让 Claude 使用 AskUserQuestion 工具主动向用户提问（甚至可以出结构化的选择题），获取信息后再执行。
8. 给 Skill 赋予"记忆（Memory）"
- 技巧：利用文件（如追加写入的
.log文件、JSON，甚至 SQLite 数据库）让技能记住历史状态。 - 案例：写完日报后存入
standups.log，第二天 Claude 运行前先读一遍历史日志，就知道今天跟昨天比有什么变化。 - 注意：要把数据存到稳定的环境变量目录（如
${CLAUDE_PLUGIN_DATA}）下，防止技能升级时数据被清空。
9. 使用按需加载的钩子（On Demand Hooks）
- 技巧：对于一些比较极端或主观的限制，不要全局生效，而是写成只有调用该技能时才生效的 Hook。
- 案例：写一个
/careful技能，拦截删除数据库或强推代码的危险命令；或者写一个/freeze技能，禁止 AI 修改特定目录以外的文件。
二、五类最常用的 Skill 模式
2.1不同业务流的最佳结构
不要遇到什么任务都用平铺直叙的指令。基于 Google Cloud Tech、Anthropic 和内部工程实践，以下五类设计模式是处理不同业务流的最佳结构。
| 设计模式 | 核心工程价值 | 典型落地场景 |
|---|---|---|
| 1. Tool Wrapper (工具包装) | 隔离实现细节，按需加载 CLI/SDK 上下文。 | 新 SDK 的 import、初始化、调用方式 |
| 2. Generator (生成器) | 用 assets/ 模板强制约束输出结构。 | Spec、PR 描述、测试计划 |
| 3. Reviewer (审阅者) | 解耦“检查内容”与“检查方式”，引入多级打分制。 | 代码审查、合规链路阻断 |
| 4. Inversion (倒置) | 阻断 Agent 的“盲目猜测”，强制转为提问收集模式。 | 模糊需求澄清、环境初始化配置 |
| 5. Pipeline (管道) | 强制按序执行 SOP，设立中间结果的强校验卡点。 | 抽取 → 校验 → 组装 → 回填 |
Pattern 1: The Tool Wrapper 工具包装
工具封装器可为您的智能体提供特定库的按需上下文。您无需将 API 约定硬编码到系统提示中，而是将其打包到一个技能中。您的智能体仅在实际使用该技术时才会加载此上下文。\
分享一个比较优秀典型的工具类的Skill:
playwright-cli：github.com/microsoft/p…
Pattern 2: The Generator 生成器
工具包装器负责应用知识，而生成器则确保输出的一致性。如果您遇到代理每次运行生成不同文档结构的问题，生成器可以通过协调填空过程来解决这个问题。
它利用了两个可选目录：𝚊𝚜𝚜𝚎𝚝𝚜/ 存放输出模板，𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/ 存放样式指南。指令充当项目管理器的角色。
它们指示代理加载模板、读取样式指南、询问用户缺失的变量并填充文档。这对于生成可预测的 API 文档、标准化提交消息或搭建项目架构非常实用。\
分享两个比较优秀典型的生成类的Skill，用来画图效果很好，五星推荐！！！
excalidraw-diagram-skill：github.com/coleam00/ex…draw.io：github.com/softaworks/…
Pattern 3: The Reviewer 审阅者
Reviewer 模式将检查内容与检查方式分开。与其编写冗长的系统提示来详细说明每个代码异味，不如将模块化的评分标准存储在 𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/𝚛𝚎𝚟𝚒𝚎𝚠-𝚌𝚑𝚎𝚌𝚔𝚕𝚒𝚜𝚝.𝚖𝚍 文件中。
当用户提交代码时，代理会加载此检查清单，并系统地对提交的代码进行评分，根据严重程度对结果进行分组。这是一种高效的方法，可以自动执行 PR 审查，或在人工查看代码之前发现漏洞。
分享
code-review-skill：github.com/awesome-ski…
Pattern 4: Inversion 倒置
智能体天生倾向于猜测并立即生成答案。反转模式颠覆了这种动态。用户不再提出问题，智能体也不再执行，而是由智能体扮演面试官的角色。\
Pattern 5: The Pipeline 管道
对于复杂任务，容不得跳过任何步骤或忽略任何指令。流水线模式强制执行严格的顺序工作流程，并设置了关键的检查点。通过实施明确的门控条件（例如，在从文档字符串生成到最终装配之前需要用户批准），该流程可确保代理无法绕过复杂任务并呈现未经验证的最终结果。
想要深入了解这些模式，建议阅读原文：《5 Agent Skill design patterns every ADK developer should know》
2.2 选择合适的模式
在实际应用中，选择哪种模式取决于你的具体需求。以下是一些选择建议：
- 需要让 Agent 正确使用某个工具或框架 → 选择 Tool Wrapper
- 需要稳定输出某种格式的文档或内容 → 选择 Generator
- 需要对已有内容进行检查和评审 → 选择 Reviewer
- 需要先收集信息再生成解决方案 → 选择 Inversion
- 需要严格按照步骤执行复杂任务 → 选择 Pipeline
需要注意的是，这些模式并不是互斥的。在实际项目中，你可能会组合使用多种模式来满足复杂的需求。例如，一个 Pipeline 模式的 Skill 内部可能会调用多个 Generator 和 Reviewer 子技能。
三、如何创建高质量技能的闭环
写完文档直接丢给大模型跑，是最粗糙的作坊式做法。 工业级 Skill 需要严谨的 8 步闭环。
把 TribalScale 的模式真正落到 skill 设计，可以总结为一个实用的 8 步闭环方法：
TribalScale《5 AI Agent Design Patterns Every Developer Needs to Know》
第 1 步：选场景：挑选高频、可复用、结果可验证的任务。
不要把开放式、极端依赖临场判断、几乎不会重复的任务硬做成 skill。先定义任务特征、时延要求、成本预算与人类参与需求，再选 pattern。
第 2 步：定边界：明确 skill 做什么、不做什么。
好的 skill 必须有排他性边界，否则多个 skill 会同时命中，造成触发混乱。OpenAI 明确建议 description 要写清楚 should trigger 与 should not trigger。
第 3 步：选模式：不是所有 skill 都需要多 Agent。
OpenAI 与 Anthropic 都建议先最大化单 Agent 的能力，再在复杂逻辑、工具过载或任务分工明显时引入多 Agent。
第 4 步：写 description：这是触发质量的关键。
description 不应只写"做 X"，而应写"在什么输入信号下，为了解决什么问题，使用什么约束，避免什么误触发"。
第 5 步：写流程：把流程写成模型可执行的命令式步骤，而不是松散的建议。
OpenAI 建议把密集 SOP 拆成更小、更清晰的动作，并确保每一步都对应具体输出或动作。
第 6 步：配资源：把模板、FAQ、策略文档、示例输入输出、确定性脚本放进 skill 目录，而不是在聊天里反复解释。
第 7 步：加护栏：任何可能涉及高风险动作、隐私数据、不可逆写操作的 skill，都要加 guardrails 和 human-in-the-loop。
OpenAI 明确把高风险动作与失败阈值升级到人工处理列为关键做法。
第 8 步：做评测：skill 不是写完就结束。
四、Skill 的评测与治理：从可写到可验证
只看最终生成的回答是否“顺眼”，是毫无意义的无效评测。 Skill 的存在会直接改变 Agent 的全局工作流，写得差的 Skill 会悄悄拉低原本正确的任务成功率。
4.1 四层评测框架：拒绝黑盒
对 Skill 的评估必须切分成四层：
- 触发层 (Trigger) ：测 Trigger Precision、Recall 和误触发率。
- 执行层 (Execution) ：测中间步骤合规率、工具调用准确率。
- 结果层 (Outcome) ：测任务最终达成率、格式契约依从度。
- 系统层 (System) ：测耗时、Token 成本以及技能间冲突率。
直接判断：如果一个评测体系不能定位问题是出在“触发失败”还是“执行偏移”上，这套评测就是失效的。这也是 OpenAI 强烈推崇 Trace Grading（链路轨迹评分），将其作为系统级缺陷定位核心方法的原因。
4.2 评测流程与发布标准
1）先收集真实失败样本。
不要先造一批"看起来合理"的测试题。先收集四类样本：历史失败任务、高频重复任务、边界场景、明确不适用场景。OpenAI 在 evals 文章里强调的是 reproducible evaluations 和 dataset-based iteration，方向很清楚。
2）必须做 A/B。
Skill 不能孤立评测，必须看"加入前 / 加入后"的差值。Google 的公开案例之所以有说服力，就因为它给了前后对照：同一模型加入 Gemini API developer skill 后，成功率从 28.2% 提升到 96.6%。没有 A/B，对"效果更好"的判断通常不可靠。
3）评分要分层。
至少准备三类评分：规则评分看格式、schema、字段、代码是否能运行；轨迹评分看步骤有没有走对、工具有没有调对；人工或模型评分看解释质量、结构性和业务可接受性。OpenAI 在《Testing Agent Skills Systematically with Evals》里给出的做法很实用：把一次运行拆成 traces 和 artifacts，再按 outcome、process、style、efficiency 这些维度去打分。
4）上线前测冲突。
单个 Skill 跑得好，不代表多个 Skill 共存时也没问题。至少要测三类冲突：两个 Skill 会不会抢同一类任务，通用 Skill 会不会压过更专门的 Skill，Skill 会不会诱导错误工具调用或无效上下文加载。对 Skill 来说，这不是补充检查，而是发布门槛。
| 维度 | 最低要求 |
|---|---|
| 触发质量 | 对目标场景的识别明显优于无 Skill 基线 |
| 结果收益 | 目标任务成功率稳定提升 |
| 负面影响 | 不明显拉低邻近任务表现 |
| 维护成本 | 易变信息已外置，不依赖高频手工改写 |
| 风险控制 | 无高危脚本、硬编码凭据、越权访问 |
如果它需要高频人工维护，说明设计有问题。
如果它收益不稳定，说明抽象边界可能错了。
如果它引入高风险脚本或越权访问，说明它根本不该直接上线。Anthropic 的 enterprise guidance 把脚本执行、网络访问、MCP 引用、硬编码凭据和越界文件访问都列成了审查项。
4.3 持续治理机制
当一个 Skill 越来越庞大，且核心价值仅仅是“稳定执行一段逻辑”时，它就该被降级为 Tool 或静态脚本。将纯计算或纯 IO 工作强留在 Prompt Context 里，只会让评测变难、维护变贵。
| 状态 | 触发条件 | 处理方式 |
|---|---|---|
| 保留 | 触发稳定、增益明确、维护可控 | 继续使用，纳入回归评测 |
| 拆分 | description 过宽、说明膨胀、职责混杂 | 拆成多个更窄的 Skill |
| 升格 | 核心价值已经变成稳定执行 | 改造成脚本、Tool 或 MCP |
| 退役 | 长期不触发、收益不足、风险过高 | 下线并保留历史记录 |
这里最重要的一句不是方法论，而是边界：当核心价值变成稳定执行时，Skill 就该退出，工具应该接管。继续把这类问题留在 Skill 里，最后只会让上下文变重、评测变难、维护变贵。
五、Skill 生态运营与工程化管理
只管新增、不管维护，最终会把高价值的内部复用能力变成一堆庞大且充满噪音的垃圾目录。
5.1 目录分级与上架门槛
Skill 必须当作内部中间件产品来管理。不要把个人的“提示词片段”直接推送到公共目录。
如果没有明确的上架约束，系统通常会面临严重的上下文污染。 相关治理手段已经被纳入头部架构的最佳实践：必须确保公共目录下的 Skill 做到“触发边界清晰、无泛化废话、无硬编码凭据、无越权脚本”。
目录分级
Skill 一旦过了十几个，最大的风险就不再是不够多，而是不好找。
How We Use Skills 分享里给出了一个很有用的观察：活跃使用的 Skills 往往会自然聚成几类，比如 Library & API Reference、Product Verification、Data Fetching & Analysis、Business Process & Team Automation、Code Scaffolding & Templates。
这个分类的价值，不在于名字本身，而在于它把"文件列表"变成了"导航结构"。目录没有分类，后面所有推荐、评测和淘汰都会变难。
| 类别 | 核心价值 | 优先做什么 |
|---|---|---|
| Library / API Reference | 减少 SDK、内部库误用 | 内部 SDK、设计系统、CLI |
| Product Verification | 把"做完了"变成"验证过了" | UI 流程验证、端到端检查 |
| Data Fetching / Analysis | 降低取数和分析门槛 | 指标查询、监控定位、漏斗分析 |
| Process Automation | 固化跨系统重复流程 | 周报、建单、发布后检查 |
| Scaffolding / Templates | 稳定输出项目约定结构 | 页面模板、服务模板、测试模板 |
这五类覆盖了大多数团队最容易产生复用价值的区域：减少误用、提高验证率、压缩重复流程、稳定输出结构。
上架门槛
不是所有有用的个人 Skill，都适合进入团队共享目录。共享目录的门槛应该明显高于个人使用，因为它会影响更多人，也更容易制造系统噪音。更稳的做法是给公共 Skill 一个最小上架标准：
- 已在真实任务里用过，不是纸面设计
- 触发边界清楚，不是泛化经验
- 有明确增益，不只是"感觉方便"
- 易变信息已外置，不依赖频繁手工改写
- 没有高风险脚本、越权访问或不可信外链
Anthropic 反复强调真实使用、发现性和安全边界；这些要求放到生态运营里，最直接的落点就是公共目录门槛。
Skill 复用率
很多内部知识系统都会掉进同一个坑：只看新增，不看使用。这在 Skill 上尤其危险。因为 Skill 不是静态文档，它会参与触发、占用上下文、影响路由。
数量本身没有价值，被正确复用才有价值。
| 指标 | 关注点 |
|---|---|
| 激活率 | 写出来的 Skill 有没有真的被用到 |
| 误触发率 | 会不会抢不该抢的任务 |
| 任务增益 | 加入 Skill 后目标任务是否稳定变好 |
| 复用范围 | 是否已经跨作者个人使用 |
| 维护滞后 | 说明和资源是否长期过期 |
| 冲突率 | 是否和其他 Skill 抢任务或互相干扰 |
这组指标和前面讲的评测框架是一套东西：评测回答"单个 Skill 值不值得存在"，运营回答"它值不值得继续占据公共目录位置"。
5.2 隔离与推荐路径
Skill 生态不是文件仓库，不能只做"收录"。真正决定生态有没有活起来的，是推荐路径：谁在什么场景下会看到哪个 Skill，哪个 Skill 默认可发现，哪个 Skill 只对特定团队开放。
Claude Code 文档已经把自动发现、额外目录、访问限制、直接调用这些机制都做出来了，这说明平台层本身就在支持"不是所有 Skill 都平铺给所有人"。
| 层级 | 角色 |
|---|---|
| 默认层 | 高频、低风险、强复用，默认可发现 |
| 专业层 | 面向特定团队或任务，按目录或权限暴露 |
| 归档层 | 低频、待淘汰或仅保留追溯价值 |
这样做的好处很直接：公共目录不会越来越吵；高价值 Skill 更容易被找到；低频 Skill 也不会一刀切消失。
Skill 生态运营不是"把更多 Skill 收进来"，而是把零散技巧变成组织资产。一个团队如果只会写 Skill，不会运营 Skill，最后通常会得到三种结果：目录越来越大，但没人知道该用哪个；真正有价值的 Skill 被淹没在噪音里；旧 Skill 不退出，系统越来越不可信。
附录 A：工程化可复用的 Skill 模板
这个模板去掉了所有冗余的礼貌用语，强制以边界划分、契约交付和异常熔断为核心。
---
name: target-skill-name
description: [触发器] 在检测到 {A信号}、用于解决 {B类问题} 时强制触发。遇到 {C情况} 严禁触发本技能。
---
### 1. Purpose & Boundary (目标与边界)
- **适用范围**：...
- **禁用场景**：...
### 2. Execution Workflow (执行管线)
- **Step 1. [判断]**：如果缺乏变量 X，调用 AskUser 索取，严禁自行伪造。
- **Step 2. [加载]**：读取 `references/api_v2.md` 获取最新 Schema。
- **Step 3. [执行]**：调用 `scripts/validate.py` 验证数据。
### 3. Output Contract (输出契约)
- **必须包含**：...
- **禁止出现**：绝对不要生成默认的紫色渐变、不要使用过期 API 语法。
### 4. Fallback Strategy (熔断回退)
- 遇到未见过的错误码时，停止推断，原样输出错误并转交人工。
附录 B：一个 Skill 评测案例
下面给一个可以直接落地的评测案例。数据是示例数据，目的不是证明某个具体产品的真实表现，而是把评测怎么做、结果怎么读、最后怎么决定能不能上线，走完整一遍。
场景
假设团队做了一个 SDK 接入 Skill。
它的目标很简单：当 Agent 需要基于某个新 SDK 生成代码时，优先使用当前推荐的 import、初始化方式、调用路径和最小样例，避免继续输出旧版本写法。
这个场景适合拿来做评测案例，原因也简单：
- 任务边界清楚，容易定义"对"和"错"
- 没有 Skill 时，模型很容易继续输出旧写法
- 加 Skill 后，前后对比通常很明显
Google 公开的 Gemini API developer skill 就是类似场景：它围绕 SDK 用法、样例和官方文档入口来设计，并且给了前后对照结果。
评测目标
这个 Skill 不是为了让回答"看起来更完整"，而是为了减少三类错误：
- 使用过期 import
- 使用错误初始化方式
- 输出不符合当前 SDK 推荐结构的代码
真正的问题不是"生成代码像不像"，而是：
加了 Skill 之后，Agent 是否更稳定地写出当前正确用法。
评测集设计
评测集不从"想象题"开始，而从真实使用场景开始拆。
| 类别 | 数量 | 示例任务 |
|---|---|---|
| 基础代码生成 | 20 | 用 SDK 生成一个最小聊天示例 |
| 流式输出 | 15 | 生成支持 stream 的调用示例 |
| 工具调用 | 15 | 生成支持 function/tool calling 的示例 |
| 文档问答封装 | 10 | 基于 SDK 封装一个文档问答函数 |
| 错误修复 | 20 | 修复一段使用旧 SDK 写法的代码 |
| 边界场景 | 10 | 用户描述模糊，要求 Agent 先判断再生成 |
| 不适用场景 | 10 | 与该 SDK 无关，不应触发 Skill |
评测集总计 100 条。
"不适用场景"不能省。Skill 评测不只测"用了之后好不好"，还要测"本来不该用的时候会不会乱触发"。
评测方法
采用 A/B 对照：
- A 组：无 Skill
- B 组：有 Skill
- 模型、系统提示、工具环境、测试题全部保持一致
- 每条样本各跑 3 次，减少单次波动
评测按四层拆：
| 评测层 | 关注点 | 指标 |
|---|---|---|
| 触发层 | 该用时是否触发，不该用时是否不触发 | Trigger Precision / Recall |
| 执行层 | 是否按 Skill 指定流程走 | 步骤合规率、是否读取正确资源 |
| 结果层 | 代码结果是否正确 | 任务成功率、代码可运行率 |
| 系统层 | 是否引入副作用 | 误触发率、平均延迟、平均 token 成本 |
评分规则
规则评分（适合能明确判定的项）：
- 是否使用当前 import
- 是否使用当前初始化方式
- 是否包含必须参数
- 代码是否能运行
- 输出是否满足规定格式
轨迹评分（适合过程检查）：
- 是否先读取 Skill 指定资源
- 是否调用了不该调用的工具
- 是否跳过关键步骤直接生成
人工评分（适合结构与可用性检查）：
- 代码是否容易复用
- 注释是否够用
- 解释是否和代码一致
OpenAI 在 Testing Agent Skills Systematically with Evals 和 trace grading 里的做法，本质上就是把这些维度显式拆开，而不是只看最后答案。
示例结果
下面给一组示例结果，主要用来说明怎么读数。
触发层结果
| 指标 | 无 Skill | 有 Skill |
|---|---|---|
| Trigger Precision | - | 0.91 |
| Trigger Recall | - | 0.87 |
| 不适用场景误触发率 | - | 0.08 |
这里先看的不是"触发率高不高"，而是"误触发高不高"。
因为一个 Skill 就算结果层表现很好，只要误触发高，进生产后也会开始抢不该抢的任务。
结果层结果
| 指标 | 无 Skill | 有 Skill |
|---|---|---|
| 任务成功率 | 62% | 86% |
| 代码可运行率 | 68% | 90% |
| 旧 SDK 写法出现率 | 31% | 6% |
| 输出格式合规率 | 74% | 93% |
这组结果说明 Skill 带来的收益主要体现在两点：
- 旧写法明显下降
- 可运行率明显提升
这也是 SDK 类 Skill 最典型的价值来源：它不是让模型"更会解释"，而是让模型少走旧路径。
系统层结果
| 指标 | 无 Skill | 有 Skill |
|---|---|---|
| 平均延迟 | 5.2s | 5.9s |
| 平均 token 成本 | 1.00x | 1.12x |
| 与其他 Skill 冲突率 | - | 0.05 |
这里能看到一个很真实的现象：加 Skill 之后，成本和延迟通常会略涨。只要收益明显覆盖这部分代价，这不是问题。真正麻烦的是收益不稳定、误触发不降、冲突率还高。
怎么读这个结果
这类案例最容易犯的错，是只盯成功率。
只看成功率不够，至少还要同时看三件事：
- 误触发高不高
不适用场景里也频繁触发，通常就是 description 写宽了。 - 旧写法是否真的下降
这比"回答更像样"更重要，因为它能证明 Skill 改变了方法路径。 - 系统副作用是否可接受
成本、延迟、冲突率如果涨得过快，说明这个 Skill 还不适合直接上线。
评测结论
基于这组示例数据，这个 Skill 可以进入下一阶段，但还不能视为"已经完成"。
原因很直接：
- 结果收益已经够明显
- 误触发率还可以继续压
- 与其他 Skill 的冲突率还要继续测
更合理的处置不是"上线完事"，而是：
- 收窄 description，继续压误触发
- 补更多不适用场景样本
- 在多 Skill 共存环境里继续做冲突评测
- 纳入回归评测，防止旧写法被重新带回来
这个案例真正说明的，不是"成功率提高了多少"，而是 Skill 评测应该怎么做：不是只看最终答案，不是只测单轮输出，不是写完就上线，而是把触发、执行、结果、系统四层拆开看。
关于 OpenTiny NEXT
OpenTiny NEXT 是一套企业智能前端开发解决方案，以生成式 UI 和 WebMCP 两大核心技术为基础，对现有传统的 TinyVue 组件库、TinyEngine 低代码引擎等产品进行智能化升级，构建出面向 Agent 应用的前端 NEXT-SDKs、AI Extension、TinyRobot智能助手、GenUI等新产品，实现AI理解用户意图自主完成任务，加速企业应用的智能化改造。
欢迎加入 OpenTiny 开源社区。添加微信小助手：opentiny-official 一起参与交流前端技术～
OpenTiny 官网：opentiny.design
GenUI SDK 代码仓库：github.com/opentiny/ge… （欢迎star ⭐）
TinyRobot 代码仓库：github.com/opentiny/ti… （欢迎star ⭐）
NEXT SDK 代码仓库：github.com/opentiny/we… （欢迎star ⭐）
如果你也想要共建，可以进入代码仓库，找到 good first issue标签，一起参与开源贡献~如果你有任何问题，欢迎在评论区留言交流！
