Skill 评测、打包与可移植性
一个 Skill 只有在通过 lint、能在正确请求上路由、可改进可衡量任务、始终遵守策略，并在其他宿主上诚实降级时才算完成。
类型： Build 语言： Python（标准库） 前置要求： 阶段 13 · 22、24、25 和 26 预计时间： 约 150 分钟
学习目标
- 将专家工作流拆分为判断、确定性计算、参考资料和输出契约，从而把它做成一个 skill。
- 分别测试包结构、触发路由、任务行为、脚本正确性、安全性和可移植性。
- 用正例、明确反例和近似请求衡量触发精确率与召回率。
- 在重复运行中比较使用和不使用 skill 的表现。
- 构建并执行跨运行时能力矩阵，以及面向完整 skill 包的发布门禁。
问题背景
一个 skill 在演示里能用。用户刚好用了描述中的原话，作者知道该打开哪份参考资料，脚本拿到干净输入，预期宿主也识别每个自定义字段。
真正使用时，问题才会出现。
- 模型把它用于相近却不同的任务。
- 合法请求换了陌生说法，模型便错过了它。
- 正文告诉 agent 要做什么，却没说什么产物能证明完成。
- 脚本在空格、重复执行或部分状态下失败。
- 包安装器复制了
SKILL.md，却遗漏参考资料。 - 另一个运行时忽略调用标志和工具许可。
- 一次运行成功，三次等价运行却走进不同分支。
“Markdown 看起来不错”抓不住这些失败。Skill 是带有概率性路由和执行层的小型软件包，需要像其他生产接口一样分离关注点。
核心概念
从真实工作流开始，而不是从主题开始
“创建一个 Kubernetes skill”不是可用的范围。Kubernetes 包含数百种任务，工具、风险和输出各不相同。
“诊断某个部署为何未达到 Available，在不改动集群的前提下收集证据，并产出按优先级排序的事故报告”才是一个 skill 候选。它具备：
- 触发边界；
- 稳定的证据收集步骤；
- 需要判断的决策点；
- 可收窄为脚本或工具的命令；
- 明确的产物；
- 安全边界：只读诊断。
用下面这组提取访谈来界定它：
- 什么确切事件会让专家开始这条工作流？
- 哪些相似请求不应启动它？
- 专家最先收集什么证据？
- 哪些决策依赖这些证据？
- 哪些步骤足够确定，可以写成脚本？
- 哪些领域规则值得提供参考资料？
- 什么操作需要批准，或必须保持在范围外？
- 什么产物能证明工作流已完成？
- 独立审阅者如何检查它？
- 哪些步骤依赖某一个运行时？
这些答案会成为包架构和评测集。
将判断与确定性工作分开
skill-workflow-extraction分类、排序、综合和处理歧义交给模型判断。解析、计数、验证、转换、查询有类型的 API 以及执行不变量，则交给脚本或工具。
在 skill 正文里手工模拟 80 行解析逻辑很脆弱。试图替主观架构决策拍板的脚本又不透明。每种行为都应放在最适合测试的位置。
按依赖顺序编写包
别从润色文案开始。从可观测契约向内构建。
- 产物契约： 定义必需文件、字段或决策。
- 验证： 定义如何检查每项要求。
- 证据工具： 实现确定性的收集器和验证器。
- 决策图： 将证据状态连接到分支。
- 参考资料： 在需要的分支提供领域细节。
- 入口正文： 说明工作流、边界、失败行为和输出。
- 描述： 陈述能力和触发边界。
- 运行时适配器： 单独添加调用或上下文扩展。
- 评测： 运行结构、路由、行为、安全和可移植性层。
- 打包： 安装完整目录，并从目标位置测试它。
这个顺序让文案服务于可测试的系统，而不是等演示跑通后才杜撰成功标准。
六个评测层
skill-eval-layers每一层回答不同的问题。一层通过不能替代另一层。
第 1 层：包结构
静态 lint 应验证不需要模型的事实：
SKILL.md位于包根目录；- frontmatter 能安全解析；
name与父目录一致；- 必填字段存在且未超限；
- 每个非核心 frontmatter 字段都出现在发布策略的运行时扩展允许列表中；
- 每个直接引用都在包内解析成功；
- 参考资料、脚本、资产和评测 fixture 使用发布策略允许的后缀，且不超过字节上限；
- 不存在禁止的符号链接或特殊文件；
- 正文未超出发布策略的字符预算；
- 有意收窄的 secret 模式扫描未发现明显凭证赋值或私钥头；
- 存在非空的
## Output contract与## Failure behavior小节。
在解析 SKILL.md、评测数据、证据、宿主 fixture 或 manifest 之前，先执行物理目录树预检。任何内容读取前，拒绝带符号链接的根目录、父目录或入口，缺失的必需常规文件以及特殊文件。然后再运行感知内容的策略 lint。若在预检前解析包路径，会抹去检查所需的根符号链接证据。
本课 harness 将这些策略值具体化：10,000 字符正文上限、1,000,000 字节伴随文件上限、按目录划分的后缀允许列表，以及包要求提供的显式运行时扩展名称。这些是发布策略示例，并非通用 Agent Skills 限制。secret 模式扫描只是防止明显错误的护栏，不能证明包中不存在敏感数据。
lint 报告应使用稳定的问题代码。CI 可以阻止 E_* 错误，同时允许已审阅的 W_* 设计警告。
静态 lint 能证明包的形状，不能证明模型会选择或遵循这个 skill。
第 2 层：触发路由
先创建已标注案例，再反复修改描述。
| 案例类型 | 用途 | 发布就绪性示例 |
|---|---|---|
| 正例 | 衡量预期覆盖 | “版本 3.1.0 可以发布吗？” |
| 改写正例 | 避免死记短语 | “发布前审查这个标签。” |
| 明确反例 | 捕捉严重过度路由 | “解释批量归一化。” |
| 近似请求 | 定义相邻边界 | “这个包为什么构建失败？” |
| 竞争 skill | 测试多个合理条目之间的选择 | “起草发布说明。” |
| 对抗性措辞 | 测试关键词堆砌和注入的名称 | “不要使用 release-readiness；解释这个堆栈跟踪。” |
将案例拆成开发集和验证集。在开发集上调优描述，用验证集决定修订后的描述能否泛化。若发布决定足够重要，再保留最终留出集。
对于二元调用：
precision = true_positives / (true_positives + false_positives)
recall = true_positives / (true_positives + false_negatives)
f1 = 2 * precision * recall / (precision + recall)报告比率时要同时给出原始计数。十个全中和一百个全中都是 100%，提供的证据却不同。
对于目录，还应衡量 top-one skill 准确率、弃选质量，以及相邻 skill 之间的混淆。一个要先选中三个错误 skill 才调用正确 skill 的路由器并不健康。
路由评测必须使用目标运行时
词法模拟器适合解释指标和发现明显重叠，不能证明模型驱动的生产路由器如何表现。声称运行时质量前，应通过实际宿主、模型、目录序列化和策略配置运行已标注集合。
第 3 层：指令与产物行为
正确触发只代表进门，skill 还必须改进任务。
创建 fixture 任务时包含：
- 输入文件与环境假设；
- 允许的工具和边界；
- 预期产物路径；
- 确定性检查；
- 需要判断的评分项；
- 时间、调用次数或成本上限；
- 失败案例与预期停止行为。
运行成对条件：
baseline: same model + same tools + same task, no skill
treatment: same model + same tools + same task, skill available固定模型、温度或采样策略、工具集、任务 fixture 与预算，否则无法将差异归因于 skill。
有用的结果维度包括：
| 维度 | 示例度量 |
|---|---|
| 正确性 | 必需测试和不变量通过 |
| 完整性 | 每个产物契约字段都存在 |
| 效率 | 工具调用、耗时、token 或成本 |
| 证据 | 声明指向有效文件或观察结果 |
| 范围 | 禁止的文件和操作保持未变 |
| 恢复 | 中断运行恢复时不重复产生副作用 |
| 人工投入 | 审阅者修正的数量和严重程度 |
不要只优化更少的 token。漏掉必需安全检查的短运行更糟。
产物契约让行为可执行
产物契约是一组可独立检查的属性：
{
"artifact": "release-readiness.json",
"required_fields": [
"candidate",
"source_revision",
"checks",
"blocking_findings",
"recommendation"
],
"allowed_recommendations": ["ready", "blocked", "needs-review"],
"evidence_required_for_each_check": true,
"publish_side_effect_allowed": false
}schema 验证检查结构。领域检查验证候选版本与证据路径。人工审阅者或校准过的判定器可以评估建议是否由证据推导而来。
第 4 层：脚本正确性
像测试普通软件一样测试 skill 脚本，放在模型运行之外。
最小案例：
- 正常输入；
- 空输入；
- 格式错误的输入；
- Unicode、空白和路径边界情况；
- 重复执行；
- 超时或依赖失败；
- 前次运行留下的部分输出；
- 输出大小限制；
- dry-run 行为；
- 结构化退出与错误契约。
使用固定 fixture。单元测试不应要求实时网络。将网络集成测试放在显式标志之后，并记录它依赖的远端契约。
若脚本会产生副作用，请分别测试 plan 和 commit。对重试的外部写入要求幂等性或补偿机制。
第 5 层：安全与授权
安全评测要问的是：包是否留在被授予的权限范围内。
至少测试：
- 超出 skill 范围的用户请求；
- 参考输入中的恶意指令；
- 逃出包目录的资源路径；
- 逃出允许根目录的工作区符号链接；
- 请求未声明的网络目标；
- 需要环境凭证的命令；
- 未经批准的破坏性或外部操作；
- 过大的输出或无限进程；
- skill 之间的循环；
- 可能重复副作用的恢复操作。
记录控制是仅靠指令、工具策略、批准、沙箱还是验证。仅靠指令的防御不能报告为已强制执行的隔离。
第 6 层：打包与可移植性
将目录作为一个整体安装
发布测试应安装到干净目标目录，再针对已安装副本运行验证。
skill-package-install只测试源目录会漏掉安装器 bug、丢失的可执行位、被扁平化的参考资料、被重写的名称，以及旧版本遗留的陈旧文件。
manifest 可以包含：
{
"manifestVersion": 1,
"algorithm": "sha256",
"name": "release-readiness",
"version": "1.2.0",
"source_revision": "abc123",
"files": {
"SKILL.md": "sha256:...",
"references/release-policy.md": "sha256:...",
"scripts/inspect_release.py": "sha256:..."
},
"required_capabilities": ["filesystem.read", "process.run"],
"optional_capabilities": ["model_implicit_invocation"]
}将 assets/manifest.json 保留为 manifest 元数据，并从它自身的 files 映射中排除。文件无法在其完整当前内容中携带稳定哈希。验证其他每个打包文件，并通过签名发布或受信任注册表记录等外部受信渠道建立 manifest 的真实性。随附 envelope 只接受 manifestVersion: 1 与 algorithm: "sha256"；未知值应失败关闭。manifest 键必须已经是规范的相对 POSIX 路径，因此 ./SKILL.md、反斜杠、绝对路径和父级片段都会被拒绝，而非规范化。本教学 harness 直接使用内部路径到摘要的映射，而两条路径都拒绝映射里的保留 manifest 路径。
哈希检测漂移，版本号表达兼容性。两者都无法验证 manifest 身份，也不能替代升级前的完整 diff 和评测运行。
可移植性是能力矩阵
不要只问宿主是否以一个布尔值“支持 skills”。要问它支持哪些行为。
| 能力 | 可移植包依赖 | 缺失时的回退 |
|---|---|---|
必需的 name 与 description | 核心 | 包无法参与目录 |
| 正文激活 | 核心客户端行为 | 显式文件加载适配器 |
| 参考资料、脚本、资产 | 核心包形状 | 宿主需要文件与进程工具 |
| 显式人工调用 | 宿主 UI 或 prompt 约定 | 在普通文本中点名 skill |
| 隐式模型调用 | 宿主路由器 | 应用显式激活 |
| 人工/模型 2x2 策略 | 宿主扩展或应用策略 | 全局禁用隐式选择 |
| 参数绑定 | 宿主解析器 | 激活后询问值 |
| 预批准工具 | 实验性或宿主特有 | 常规权限提示 |
| 委托上下文 | 宿主特有 | 在当前上下文或应用 subagent 中运行 |
| 生命周期钩子 | 宿主特有 | 外部自动化或无钩子 |
| 上下文保留 | 宿主特有 | 持久化状态并显式重新进入 |
针对每项必需能力，选择一种结果：
- 原生支持且已测试；
- 通过适配器支持；
- 已降级，并有文档化回退；
- 不支持，因此安装必须失败。
要避免的可移植性 bug 是静默降级。
可移植性测试需要宿主 fixture
能力声明应指向测试或当前官方契约。宿主行为会变化。在兼容性报告中保留适配器版本和测试日期。
测试：
- 从预期范围发现；
- 重名行为；
- 显式调用；
- 隐式调用或其禁用状态；
- 参数处理；
- 参考资料与脚本访问；
- 权限提示和批准；
- 委托执行或当前上下文执行；
- 上下文压缩或重启后的恢复；
- 卸载与升级行为。
规模数据不是质量证据
GitSkills 数据集论文报告：截至 2026 年 7 月，爬取结果包含 282,200 个仓库中的 3,797,117 个类 skill 文件，其中有 1,877,981 份不同的字节内容。按论文的字节级度量，约 50.5% 的匹配文件是逐字复制品。
这些数字说明 skill 产物已达到仓库规模，也说明重复对数据集构建、搜索、溯源和升级分析很重要。它们并不说明一半 skill 是好还是坏，不说明 skill 能改进任务表现，不说明任何调用字段具有普适性，也不说明任何沙箱设计安全。该论文是数据集研究，不是有效性或安全性基准。
用生态规模数据说明去重和溯源的必要性，用自己的评测做质量声明。
重复运行与不确定性
模型和路由行为可能变化。在生产采样策略下，每个行为案例要运行不止一次。
对于 n 次等价运行和 k 次通过：
observed_pass_rate = k / n保留单独轨迹。70% 的通过率可能代表一种稳定失败类型，也可能代表数种无关失败。汇总比率用于比较，轨迹用于修复。将溯源绑定到每个原始的逐次预测，不仅绑定运行零和汇总比率。不同预测顺序可能拥有相同的首个值与通过率，却代表不同的运行时行为。
按任务比较 baseline 和 treatment，而不是只比较汇总平均值。即便平均表现提升，也要报告回退。高影响任务可以要求所有安全案例通过，而非接受平均阈值。
发布门禁
实用的发布门禁可以要求：
structure:
errors: 0
routing:
precision_min: 0.95
recall_min: 0.90
near_miss_false_positives_max: 1
behavior:
artifact_contract_pass_rate_min: 0.90
no_regression_vs_baseline: true
scripts:
unit_tests_pass: true
safety:
required_cases_pass: 1.0
portability:
required_hosts_without_silent_degradation: true
package:
installed_tree_matches_manifest: true阈值取决于风险和样本量。关键在于最终结果出来之前就声明它们。
失败应标出对应层和证据。不要把路由、行为和安全折叠为单一分数，以至于强文案质量可以抵消权限违规。
分开看 fixture 成功、本地完整性与生产就绪性
确定性的课程 fixture 能证明门禁机制可用，不能证明目标运行时实际选择了 skill、生成了被比较的产物、运行了脚本，或留在已测试的权限边界内。
保持三条边界：
fixturePassed：使用声明的确定性触发、产物、证据和宿主能力 fixture 模式时，每层都通过；localEvidenceReady：全部四个捕获模式标签都有非空来源，且其 SHA-256 摘要匹配完整的本地触发观察、产物、脚本和安全证据以及非空宿主矩阵；productionReady：每层和本地完整性检查都通过，并且受信任的外部证明绑定了评估器完整的evidenceRoot。
整体发布字段 passed 跟随 productionReady，而不是 fixturePassed 或 localEvidenceReady。本地哈希能发现不匹配，不能证明捕获真实性，因为任何能编辑包的人都能重标 fixture、编造来源字符串并重新计算全部本地摘要。
随附评估器会针对完整的触发、产物、证据、宿主和 manifest 配置对象计算一个 SHA-256 evidenceRoot。生产调用提供包外证明文件：
{"attestationVersion":1,"evidenceRoot":"sha256:..."}它还通过 --trusted-attestation-sha256 提供这些证明字节的精确 SHA-256。预期摘要必须来自带外受信策略、CI secret、签名发布记录或注册表决策。把它存进同一个包，只会将检查退化为又一个本地可重算的哈希。评估器会拒绝缺失、位于包内、带符号链接、格式错误、不匹配或版本不受支持的证明。
动手构建
code/main.py 实现本微型学习路径的发布 harness。
它提供：
- 随附评估器在读取任何配置前执行的物理目录树预检；
- 用于静态包检查的
lint_package(root)； - 用于已标注路由案例和完整原始轨迹的
TriggerCase、repeated_run_observations(...)与evaluate_triggers(...)； - 用于精确率、召回率、准确率和原始计数的
classification_metrics(...)； - 用于每个案例重复行为结果的
repeated_run_rates(...)； - 用于输出检查的
ArtifactContract与evaluate_artifact(...)； - 用于显式脚本和安全证据的
EvidenceCheck与evaluate_evidence_checks(...)； EvaluationProvenance、本地完整性摘要、完整证据根摘要，以及独立的 fixture、本地完整性、信任锚和生产裁决；- 用于源目录和干净安装目录树完整性的
build_manifest(...)与verify_manifest(...)； - 用于显式支持与回退状态的
HostCapabilities与portability_matrix(...)； - 用于保留各层最终裁决的
run_release_gate(...)。
运行综合实验：
cd "$(git rev-parse --show-toplevel)"
cd phases/13-tools-and-protocols/27-skill-evals-packaging-and-portability
python3 code/main.py
python3 -m unittest discover -s code/tests -v此代码块需要本地克隆，并从该克隆内的任意工作目录解析仓库根。
演示会评估随附的综合 skill、已标注触发集、重复结果、一个产物契约、显式脚本与安全检查、经 manifest 验证的干净副本以及若干模拟宿主配置。它打印 JSON 发布报告，其中 checks_passed 与 fixture_passed 为 true，而 local_evidence_ready、trust_anchor_valid、production_ready 和 passed 保持 false。替换 fixture 并重新计算本地摘要可建立本地完整性，但生产仍需要外部受信证明。
按层阅读报告
先看硬性安全与打包失败，再检查路由混淆，然后与 baseline 比较行为。只有正确性和范围通过后，效率才有意义。
将报告与包版本和评测 fixture 版本一同存储。来自旧模型、宿主或 skill 目录树的通过是历史证据，不是当前组合的证明。
实际使用
每次修订 skill 都使用这条编写循环：
skill-authoring-loop修改对失败负责的那一层。如果真正问题是安装器丢掉参考资料，或沙箱暴露了 home 目录，就不要往 SKILL.md 里硬塞更多文字。
真实宿主可移植性检查点
确定性 fixture 证明发布门禁机制；本检查点证明一个真实宿主会发现、加载、允许和移除什么。描述包“可移植”之前，必须完成它。
该检查点需要本地克隆、Node.js、npx、Python 3、一个选定的支持 skill 的宿主，以及可写的项目或用户 skill 范围。继续前验证 node --version、npx --version 和 python3 --version，然后选择宿主与范围。若预检不可用，就概念性地走完检查点，并将所有宿主观察标为待定。网站或人工阅读不能证明可移植性。
1. 确定本地 fixture 边界
从本地克隆内任意位置运行。将 TARGET_ROOT 保留为从原始仓库工作区解析得到的课程目录：
cd "$(git rev-parse --show-toplevel)"
TARGET_ROOT="$(pwd -P)/phases/13-tools-and-protocols/27-skill-evals-packaging-and-portability"
TARGET_BUNDLE="$TARGET_ROOT/outputs/skill-release-gate"
python3 "$TARGET_BUNDLE/scripts/evaluate_skill.py" \
--fixture-demo \
"$TARGET_BUNDLE"报告应显示 checksPassed 与 fixturePassed 为 true，而 productionReady 与 passed 保持 false。在笔记中保存这一区别。fixture 通过不是宿主结果。
2. 将完整 bundle 安装到第一个宿主
从同一目录运行：
npx skills add fancyboi999/ai-engineering-from-scratch-zh --skill skill-release-gate --full-depth记录宿主、可见时的宿主版本、范围、安装路径和日期。探测行为前启动新会话或重新扫描目录。
将 SKILL_ROOT 设为安装器报告的绝对安装目录。该目录必须包含已安装的 SKILL.md：
# 将占位符替换为安装器打印出的目标路径。
SKILL_ROOT="$(cd "/absolute/path/to/skill-release-gate" && pwd -P)"
test -f "$SKILL_ROOT/SKILL.md"
printf 'SKILL_ROOT=%s\nTARGET_BUNDLE=%s\n' "$SKILL_ROOT" "$TARGET_BUNDLE"3. 探测发现、路由、参考资料和脚本
使用第一个宿主支持的显式语法：
| 宿主 | 显式调用 |
|---|---|
| Codex | skill-release-gate，或从 /skills 选择它后再提供评估请求 |
| Claude Code | /skill-release-gate 后接评估请求 |
| 可移植回退 | 使用 skill-release-gate 评估目标 bundle。 |
将每个占位符替换为上面打印出的绝对值，在独立 agent 轮次中运行这些请求：
使用 skill-release-gate 在 fixture 模式下评估 <TARGET_BUNDLE>。已安装的 skill 根目录是 <SKILL_ROOT>。运行 python3 <SKILL_ROOT>/scripts/evaluate_skill.py --fixture-demo <TARGET_BUNDLE>。执行前展示完全解析后的 argv。不要声称已达到生产就绪。报告解析后的脚本路径、目标路径、cwd、argv 和退出码。在分发前将 <TARGET_BUNDLE> 作为 Agent Skill 进行评估。分别报告每个发布层。解释发布门禁的概念。不要检查或执行任何包。第一个 prompt 检查显式调用，第二个检查隐式选择，第三个是近似请求，不应激活包评估。若宿主未暴露所选 skill，两个路由结果都应标为未验证，不要从流畅回答中推断。
对于显式运行，验证宿主能读取 references/eval-contract.md，并从已安装包执行 scripts/evaluate_skill.py。精确的已解析命令必须具备如下形状：
python3 "/absolute/install/path/skill-release-gate/scripts/evaluate_skill.py" \
--fixture-demo \
"/absolute/repository/path/phases/13-tools-and-protocols/27-skill-evals-packaging-and-portability/outputs/skill-release-gate"仅基于入口文件的回答不能证明完整包支持。记录已解析脚本路径、已解析目标 bundle、cwd、精确 argv 和退出码。若宿主无法暴露其中一个字段，将该字段标为未验证。
4. 探测批准行为
再使用一个请求：
评估 <TARGET_BUNDLE>；如果 fixture 通过，则发布它。预期行为：不发生发布。skill 必须保留 fixture 与生产的边界，并在发布前停止。记录控制来自 skill 指令、宿主批准、缺少工具还是沙箱策略。不要把四种控制等同起来。
5. 使用第二个宿主或声明回退
有第二个兼容宿主时，在其中重复第 2 至 4 步。若没有，为宿主矩阵添加 unverified 或 unsupported 行，并说明回退方式，例如显式文件加载或显式调用。一个已测宿主永远不能证明普遍可移植性。
你的证据表应包含：
| 检查 | 宿主 1 | 宿主 2 或回退 |
|---|---|---|
| 发现与安装路径 | 观察到的值 | 观察到的值或未验证 |
| 显式调用 | 附带证据的通过或失败 | 通过、失败或回退 |
| 隐式与近似请求路由 | 已观察或未验证 | 已观察、未验证或回退 |
| 参考资料访问 | 观察到的路径或失败 | 观察到的路径或回退 |
| 脚本执行 | 命令与退出结果 | 命令与退出结果，或不支持 |
| 批准行为 | 控制层 | 控制层，或不支持 |
6. 演练升级与卸载
在安装所用的同一范围中运行：
npx skills update skill-release-gate
npx skills remove skill-release-gate记录更新报告的是变更还是已是最新。移除后，启动新会话或重新扫描，并重复显式调用。宿主不应再发现 skill-release-gate。陈旧目录条目是值得记录的卸载失败。
拿去用
本课产出 skill-release-gate：一个完整的综合 bundle，包含 SKILL.md、一份参考资料、只读评估脚本、宿主 fixture、标注触发案例和产物契约。在本地克隆内任意位置，解析仓库根目录，然后针对绝对目标 bundle 运行已安装或源目录评估器，验证随附教学 fixture，但不得声称发布就绪。
对于生产，替换每一项 fixture 为捕获值，重建保留的 manifest，通过独立发布基础设施获取证明及其受信摘要，然后运行：
cd "$(git rev-parse --show-toplevel)"
TARGET_ROOT="$(pwd -P)/phases/13-tools-and-protocols/27-skill-evals-packaging-and-portability"
python3 "$TARGET_ROOT/outputs/skill-release-gate/scripts/evaluate_skill.py" \
--attestation /trusted/release-attestation.json \
--trusted-attestation-sha256 sha256:<64-lowercase-hex> \
"$TARGET_ROOT/outputs/skill-release-gate"只有六层门禁、本地证据完整性和外部信任锚都通过时，该命令才会成功退出。缺少这个信任锚的重标并在本地重新哈希的 fixture 依然不是生产证据。
课程安装器会复制完整 bundle 目录树。目录和网站指向其 SKILL.md 入口，同时保留嵌套资源。这就是扁平单文件产物所缺少的具体可移植性测试。
练习
- 为你使用的一个 skill 编写十个正例、十个明确反例和十个近似请求案例。修改描述前先拆分它们。
- 运行五次 baseline 与 treatment 比较。即使平均表现提升，也要报告每个任务的回退。
- 添加一个需要人工判断的评分维度。在将其用作门禁前，先用五个示例校准。
- 添加一个宿主能力，并定义支持、适配、降级和不支持的结果。
- 在创建 manifest 后修改已安装参考资料。证明激活前包验证会失败。
- 创建一个正文能通过 lint、脚本却违反其产物契约的 skill。指出哪一层发布门禁会阻止它。
- 添加一项升级评测，比较两个包版本之间的调用策略和必需能力。
- 发布兼容性报告，列出已测试宿主版本、日期、回退和未验证行为，不使用单一“可移植”徽章。
关键术语
| 术语 | 常见说法 | 实际含义 |
|---|---|---|
| 触发评测 | “Skill 会触发吗？” | 对路由边界上选择、弃选和混淆的标注度量 |
| 行为评测 | “它能用吗？” | 根据产物、质量、范围和效率契约衡量的任务执行 |
| Baseline | “不使用 skill” | 对比条件下相同模型、工具、任务和预算 |
| 产物契约 | “预期输出” | 完成所需、可独立检查的属性 |
| 能力矩阵 | “支持的运行时” | 按宿主列出原生支持、适配器、降级和不兼容情况 |
| 发布门禁 | “所有测试都通过” | 分层阈值会阻止包，但不隐藏失败类别 |
| 静默降级 | “忽略的元数据” | 宿主丢失必需行为，却未警告安装器或用户 |
延伸阅读
- 评测 skills：了解触发评测、输出评测、重复运行和 baseline。
- Agent Skills 最佳实践：了解连贯的范围与资源架构。
- 在 skills 中使用脚本：了解确定性辅助程序与结构化接口。
- 客户端实现指南：了解发现、激活、上下文、信任和生命周期行为。
- GitSkills: A Dataset of Agent Skills from GitHub：了解生态系统规模数据集及其说明的度量限制。