skillify

Skillify — 元技能

与 /cross-modal-review 的关系： 该技能是手动的流程中“第二意见”关卡（在提交前由一个模型审阅工作成果）。本技能下面的第 3 阶段则改用 gbrain eval cross-modal——由三个不同提供方的前沿模型依据一份有文档记录的维度列表进行打分并迭代，且发生在测试固化行为之前。临时的第二意见请使用 /cross-modal-review；为功能做 skillify 时请使用本技能的第 3 阶段。

约定

当全部 15 个检查项（0 + 1–14；3b 附属于第 3 项）均通过时，一个功能即被视为“已正确 skill 化”。gbrain skillify check 审计机械性检查项（1–11）；第 0、3b、12、13 和 14 项属于程序性关卡，由 Agent 直接验证。第 3 项（跨模态评估）在审计中仅作参考信息——它不会限制 gbrain skillify check 的通过，但若回执缺失或已过期，会予以提示，以便用户了解关卡当前状态。

幂等性保证： skillify 可对同一技能运行任意次。每次运行时：

1. 检测已有产物（SKILL.md、测试、评估、代码、解析器条目）
2. 识别新内容：缺陷报告、用户反馈、新输入或质量缺口
3. 改进已有文件，而非从头重写
4. 保留有效部分，修复有问题的部分
5. 重新运行检查清单，且只处理未通过的检查项

不退化原则： 对技能的任何修改，在同一任务和维度上的跨模态评估得分都必须 ≥ 上一迭代。只向前推进，绝不后退（第 3.5 阶段）。

检查清单

其他技能和工作流会委托给本检查清单——请按编号引用检查项（例如“对 skills/skillify/SKILL.md 运行 skillify 第 4–6 项”）。编号保持稳定，仅允许增量式变更。

□ 0.  Eval contract      — skill declares goal + skill-specific dimensions + hard-fails (Phase 2.5)
□ 1.  SKILL.md           — skill file with frontmatter + contract + phases
□ 2.  Code               — deterministic script if applicable
□ 3.  Cross-modal eval   — 3 frontier models from 3 providers critique output vs the contract; informational in the audit
□ 3b. No-regression gate — new eval scores ≥ the previous iteration (forward only; Phase 3.5)
□ 4.  Unit tests         — cover every branch of deterministic logic
□ 5.  Integration tests  — exercise live endpoints
□ 6.  LLM evals          — quality/correctness cases for LLM-involving steps
□ 7.  Resolver trigger   — entry in skills/RESOLVER.md with real user trigger phrases
□ 8.  Resolver eval      — test that triggers route to this skill
□ 9.  Check-resolvable   — DRY + MECE audit, no orphans
□ 10. E2E test           — smoke test: trigger → side effect
□ 11. Brain filing       — if it writes pages, entry in brain/RESOLVER.md
□ 12. Scheduled-run observability — if the skill backs a cron/recurring job, runs route through minions so they are logged and inspectable (Phase 6)
□ 13. Scheduled-task re-run — if the skill backs a cron, an edit re-runs a representative task + evals it (Phase 3.5)
□ 14. Plugin membership   — record the skill in openclaw.plugin.json OR skills/plugin-exclusions.json (the membership test requires exactly one)

第 0 阶段：确定模式（新建还是改进）

在开始任何工作之前，先确定模式。

模式 A：新建技能（不存在 SKILL.md）

检查：

• 该功能是否会被调用 2 次及以上？（一次性工作 ≠ 技能）
• 逻辑是否超过 20 行？（琐碎的辅助函数不需要完整基础设施）
• 是否有用户会实际说出的、清晰的触发短语？

如果任一答案为否，则它是脚本而非技能——在此停止。不要为其搭建脚手架、编写 SKILL.md、运行评估或编写测试。告知用户原因并继续其他工作。

范围检查（上限）：一个技能 = 一种能力 = 一个连贯的触发族。如果目标跨越多个用户会分别调用的不同意图（“运行构建” / “回滚部署” / “通知团队”是三个意图，而非一个），不要构建一个覆盖所有意图的技能。应停止，建议拆分为独立的 skillify 目标，并询问用户先 skillify 哪一个。

DRY/MECE 预检：在搭建脚手架之前，在 skills/RESOLVER.md 和技能清单中搜索重叠的触发短语及近似重复的描述。如果拟定的触发与现有技能冲突，优先合并——在现有技能中添加一个触发、模式或阶段，提升其次版本号，并对合并后的结果运行本检查清单——而不是创建近似重复的技能。如果尽管存在重叠仍需创建独立技能，则须在新的 SKILL.md 中记录一句话说明二者的区别。gbrain check-resolvable（第 5 阶段）是兜底手段，用于捕获预检遗漏的问题。

模式 B：改进现有 Skill（SKILL.md 已存在）

这是幂等路径。适用于对已有 SKILL.md 的 Skill 运行 skillify、发现 bug、用户给出反馈或新输入，或需要进行质量检查的情况。

改进流程：

1. 读取所有现有产物：skills/<slug>/SKILL.md、该 Skill 的脚本（路径以 SKILL.md 中引用的为准）、routing-eval.jsonl 和 test/<slug>.test.ts。
2. 确定变更差异（delta），即有什么变化？
   • Bug 修复： 用户报告了具体故障。针对该确切 bug 添加测试，修复代码，并在 SKILL.md 中添加一条 HARD RULE 以防止再次发生。
   • 新输入： 用户提供了新的上下文或需求。扩展 SKILL.md，更新代码，为新行为添加测试。
   • 质量检查： 没有具体 bug，只是重新运行检查清单。审计、跨模态评估、补齐缺口。
3. 精准修改：编辑现有文件，不要重写。
4. 重新运行所有现有测试，确保没有回归。
5. 更新 frontmatter 中的版本号（bug 修复用补丁版本，新增能力用次版本）。
6. 发布前运行无回归门禁（Phase 3.5）。

Bug 修复模板（添加到 Skill 的 SKILL.md 中）：

## Bug: [Date] — [Short description]
- **What happened:** [Concrete failure]
- **Root cause:** [Why]
- **Fix:** [What changed]
- **Hard rule added:** [New constraint to prevent recurrence]
- **Tests added:** [List of new test cases]

Phase 1：审计

Feature: [name]
Code: [path]
Missing items: [check each of the 15]

Phase 2：编写 SKILL.md + 代码（第 1-2 项）

SKILL.md frontmatter 模板（可直接复制）：

---
name: my-skill
version: 1.0.0
description: |
  One paragraph. What it does, when to use it.
triggers:
  - "trigger phrase users actually say"
  - "another real trigger"
tools:
  - exec
  - read
  - write
mutating: false  # true if it writes to brain/disk
---

正文必须包含：Contract（保证了什么）、Phases（分步流程）、Output Format（产出什么）。

将确定性代码提取到 scripts/*.ts 中。

Phase 2.5：评估契约（第 0 项）— 在评估前先定义目标与评分标准

跨模态评估的质量取决于你要求它评判的内容。通用维度能捕捉粗制滥造的内容，却可能遗漏输出是否达成该 Skill 的特定目的。每个 Skill 都应携带明确的评估契约：说明该 Skill 的用途，以及如何判断某个输出是优秀还是失败。

每个 Skill 都在 frontmatter 中声明其评估契约

eval_contract:
  goal: |
    One or two sentences: what this skill is supposed to achieve, for whom, and what
    "excellent" looks like in the real world. Be concrete and skill-specific.
  dimensions:
    - "DIMENSION_NAME — the specific question this dimension answers for THIS skill"
    # 3-6 dimensions, tuned to the skill. Example for a per-subject news briefing skill:
    # - "FACTUAL_INTEGRITY — is every claim true and verifiable?"
    # - "SUBJECT_ANCHOR — is each item tied to something concretely THIS subject's?"
    # - "WHY_IT_MATTERS — is the relevance real and specific, not a templated lane label?"
    # - "CLICKWORTHY — would the reader actually want to open these links?"
  hard_fails:
    - "A failure mode that auto-zeroes the eval regardless of other scores."
    # e.g. "Any fabricated fact = automatic 1."

获取评估契约的方式（按优先级排列）

1. 从 Skill 中读取。 如果 frontmatter 中已存在 eval_contract（或正文中有清晰的 Goal/Contract 章节），则直接使用。幂等运行会复用同一契约，使各轮评分可以横向比较，这正是无回归门禁有意义的原因。
2. 从上下文推断。 如果没有声明契约，则根据 SKILL.md 正文（Contract/Output Format）、调用该 Skill 的定时任务提示词、近期用户反馈（尤其是投诉，例如某个事实错误的投诉会将 FACTUAL_INTEGRITY 确立为一票否决的维度），以及代表性输出的受众，推导出目标和维度。
3. 目标或“优秀”标准不明确时询问用户。 如果目标或“优秀”的标准确实含糊，且无法有把握地推断，就提出一个精炼的问题，然后继续。对于高风险 Skill（输出会发布到线上渠道或会被他人阅读的 Skill），不要猜测评分标准。错误的评分标准会产生一个看似可信、实则毫无意义的分数。
4. 回写。 确定后，将契约持久化到该 Skill 的 eval_contract frontmatter 中，以便复用并进行版本管理。修改契约本身也是一次 Skill 编辑，需要重新评估，以确认新的评分标准仍能对当前输出给出正确评分。

将契约接入评估

将契约的目标作为 --task 传入，将其维度作为 --dimensions 传入 gbrain eval cross-modal。这样评估衡量的是 Skill 是否达成其既定目的，而非通用检查清单。在任务文本中写明一票否决条件，使评判者在条件触发时直接将分数归零（例如“如果任何断言是捏造的，则输出失败，无论其他质量如何”）。

Phase 3：跨模态评估（第 3 项）— 质量门禁

为什么它排在测试之前

测试会固化行为。如果行为本身平庸，测试就会把平庸固定下来。跨模态评估应先确立质量标准，然后由测试加以巩固。

Step 1: 选择一个有代表性的输入

选择能覆盖该 skill 最难的已文档化用例的输入。如果拿不准：使用 SKILL.md 中的主要触发示例，或最近 7 天 memory 文件中最复杂的真实输入。

Step 2: 运行 skill，捕获输出

对有代表性的输入运行该 skill。被评估的是 OUTPUT FILE。

Step 3: 运行 eval 门禁

gbrain eval cross-modal \
  --task "The eval contract's goal, including its hard-fail conditions" \
  --dimensions "dim_one,dim_two,dim_three" \
  --output skills/<slug>/SKILL.md

该命令会并行运行 3 个 judge 模型（来自 3 个不同提供商的前沿模型），依据给定维度（省略 --dimensions 时默认为 5 个标准维度）将 OUTPUT 与 TASK 进行打分，并在 ~/.gbrain/.gbrain/eval-receipts/<slug>-<sha8>.json 下写入一份 receipt（sha-8 将 receipt 与当前 SKILL.md 内容绑定——编辑后重新运行会写入新的 receipt，因此每次迭代都会留下自己的基线）。

Judge 模型按以下顺序为每个槽位解析：

槽位	1. 参数	2. brain 配置键	3. 回退
A	--slot-a-model <provider:model>	models.eval.cross_modal.slot_a	gbrain 为槽位 A 内置的默认值
B	--slot-b-model <provider:model>	models.eval.cross_modal.slot_b	gbrain 为槽位 B 内置的默认值
C	--slot-c-model <provider:model>	models.eval.cross_modal.slot_c	gbrain 为槽位 C 内置的默认值

brain 配置键与夜间质量探针读取的键相同，因此只需固定一次（gbrain config set models.eval.cross_modal.slot_a <provider:model>），每次运行——无论是 CLI 还是探针——都会使用同一组评审面板。gbrain models 会显示探针解析出的评审面板。内置默认值是来自三家提供商的三个当前前沿模型；它们会随 gbrain 发布而变化，因此不要把字面 id 复制进 skill——如果某槽位的默认提供商在此没有密钥，则会用已配置的聊天模型替代（#4636），receipt 会记录实际参与评判的模型。

这些必须是来自不同提供商的前沿模型。 使用单一提供商的同系列或经济型模型会失去意义——不同模型系列的盲点相关性更低。模型名称会变化；运行时请固定当前可用的别名。持久有效的原则是仅限前沿模型、提供商必须不同。

通过标准（两项必须同时成立）：

1. 每个维度在所有成功模型上的平均分 ≥ 7。
2. 没有任何单个模型在任何维度上的分数 < 5（底线）。

结果不确定（Inconclusive）： 少于 2 个模型（共 3 个）返回了可解析的分数。仍会写入 receipt（用于留痕分析），但该门禁结果不具权威性。退出码为 2；CI 封装脚本应将其视为"未能正常运行"，而非"未通过质量门禁"。

Step 4: 循环直至通过（最多 3 轮）

CYCLE 1:
  Eval → scores + top 10 improvements
  IF pass: → done, write tests
  ELSE:
    Apply top 10 improvements to the actual file
    Log: which improvements applied, what changed

CYCLE 2:
  Re-eval the FIXED output (same 3 models, same dimensions)
  Compare: before/after scores per dimension (track delta)
  IF pass: → done, write tests
  ELSE: apply remaining improvements + new ones

CYCLE 3 (final):
  Re-eval
  IF pass: → ship
  ELSE: → ship with KNOWN_GAPS section listing:
    - Which dimensions are still below 7
    - Which improvements couldn't be resolved
    - Why (e.g., "would require architectural change")

轮次与成本护栏

• 默认 --cycles 3（TTY 环境），非 TTY 环境下默认 --cycles 1（限制 CI 循环中脚本化的批量开销）。
• 每轮运行前，该命令会根据一个小型定价常量打印每轮的估算最大成本。实际成本随提示词大小而变化；请将该估算视为默认 --max-tokens 4000 下的上限。
• --budget-usd N 硬性上限是 v0.27.x 的后续 TODO。

提供商配置

模型通过 gbrain AI 网关解析。配置一次即可：

gbrain providers test    # see what's configured
gbrain config            # set keys

每个槽位都需要其提供商的密钥：gbrain providers test --model <provider:model> 会说明某槽位的模型是否可达，gbrain providers env <provider> 会列出该 recipe 读取的环境变量或 <vendor>_api_key 配置键（来自 ~/.gbrain/config.json 与 process.env）。请将槽位固定到你已有密钥的提供商，而不是为默认值去申请密钥。

成本预期

每次运行最多 3 轮 × 3 个模型 = 9 次前沿模型调用。使用前沿级模型、默认 --max-tokens 4000 时，一次完整运行预计花费 $1–3。receipt 会包含每次调用的模型标识符，便于事后审计。

以下情况跳过跨模态 eval：

• 输出少于 200 个 token（过于简单——不值得花 9 次 API 调用）。
• 该 skill 只是对单次 API 调用的薄封装（一轮即已足够）。

第 3.5 阶段：无回归门禁 + 定时任务重跑（第 3b 项、第 13 项）—— 只进不退法则

定时运行的 skill 可能悄无声息地退化，在有人重新检查其质量之前就把糟糕的输出发送到线上渠道。法则是：我们只向前推进。若某次编辑的得分低于上一次迭代，即为回归，绝不可发布——必须回滚或重新修复。

3b. 无回归门禁（每次 skill 编辑，强制执行）

绝对及格线（各维度均值 ≥ 7，且任一单项得分不低于 5）是必要条件，但并不充分。编辑后的输出还必须超过上一次迭代在同一任务和同一维度上的评估结果。

1. 找到最近一次的历史回执。回执与 SKILL.md 的内容 sha 绑定，因此每次迭代都会生成各自的文件：

   ls -t ~/.gbrain/.gbrain/eval-receipts/<slug>-*.json | head -5
   

2. 从上一次回执中读取基线数值：

   jq '{overall: .aggregate.overall, dims: (.aggregate.dimensions | map_values(.mean))}' <prior-receipt>
   

3. 使用与上一次运行相同的 --task 和 --dimensions 对编辑后的输出运行新的评估——确保比较基准一致。复用评估契约（第 2.5 阶段）可自动满足这一点。
4. 进行比较：
   • 前进（发布）： 新的总分 ≥ 上一次总分，且没有任何维度均值下降超过 0.5。
   • 回归（阻止）： 新的总分 < 上一次总分，或任一维度回退超过 0.5。不得发布。应用最重要的改进并重新评估，或回滚该编辑。记录此次回归。
5. 若不存在历史回执（首次评估），则以绝对及格线（≥ 7）为标准，本次运行即成为基线。
6. 将前后对比（上一次总分 → 新总分，以及结论）记录在提交或 PR 信息中，以使只进不退的历史可供审计。

例外：对于行为已由新测试完全锁定的纯确定性缺陷修复，可以跳过重新评估——但第 7 阶段的重新验证仍须执行。任何改变文字、提示词或输出结构的编辑都需要重新评估。

13. 定时任务重跑（由定时任务驱动的 skill，编辑时强制执行）

许多 skill 由定时任务调用（简报、每日摘要、监控、周期性报告）。编辑此类 skill 后，只有在通过编辑后的 skill 重新运行一个具有代表性的真实任务，并对其实际会产生的输出完成评估之后，才算完成。

1. 检测定时任务绑定： 检查是否有 cron 条目或周期性 minion 任务调用该 skill（gbrain jobs list，以及 skills/conventions/cron-via-minions.md 中的调度器配置）。若至少有 1 个任务引用了该 skill，则本门禁适用。
2. 选择要求最高的代表性任务——即质量最为明显、回归后果最严重的输入（用户最挑剔阅读的报告、最困难的已记录路径）。原则是固定的；具体输入由你的部署环境决定——切勿将其硬编码到 skill 正文中。
3. 真实运行，捕获其将会产生的内容。 写入文件——在 skillify 测试期间，不得向线上渠道发送。将发送重定向到临时文件，或使用 dry-run 参数。
4. 对该输出进行跨模态评估（第 3 阶段），并针对此任务相对于上一次迭代回执执行无回归门禁（3b）。使用 --slug <skill>-<task> 保持各任务基线相互独立，以免回执与 skill 自身的 SKILL.md 回执发生冲突。
5. 仅在前进时发布。 新得分 ≥ 该任务的上一次得分。得分更低意味着编辑导致定时输出回归——必须阻止并重新修复。
6. 幂等性重新验证（“skill 绝不静默失效”）： 编辑后，重新运行第 1 阶段审计与第 7 阶段验证，使每一项检查清单都被重新核对，而不仅仅是你修改的那一项。确认：
   • 所有被引用的脚本仍然存在且可以运行（无失效路径），
   • 定时任务仍然调用正确的 skill 路径，
   • 测试仍然通过（无回归），
   • 解析器条目仍然能够正确路由。 如果任何此前通过的项目现在失败，说明该编辑破坏了某些内容——须先修复再发布。

硬性规则（添加到任何由定时任务驱动的 skill 的 SKILL.md 中）

⛔ NO-REGRESSION + RE-RUN GATE: Any edit to this skill must (1) re-run a
representative scheduled task, (2) cross-modal eval the real output,
(3) score ≥ the previous iteration's receipt. A worse score does NOT ship.
We only go forward.

第 4 阶段：测试（第 4-6 项）

现在 eval 已证明质量达标，编写测试把它固定下来：

单元测试：覆盖确定性逻辑的每个分支。模拟外部调用。 集成测试：调用真实端点。捕获 mock 掩盖的缺陷。 LLM evals：针对 LLM 步骤的质量与正确性。比跨模态 eval 更轻量，针对特定行为进行测试。

第 5 阶段：Resolver 与可解析性检查（第 7-9 项）

1. 在 skills/RESOLVER.md 中添加用户实际会输入的触发短语
2. Resolver eval：输入触发短语，断言路由正确
3. 可解析性检查：
   • 可从 skills/RESOLVER.md 访问该 Skill（不是孤立的）
   • 与其他 Skill 不存在 MECE 重叠
   • 不存在 DRY 违规（共享逻辑放在 lib/ 中，而非复制粘贴）
   • 不存在模糊的触发路由

创建或更新 Skill 后，重新运行 gbrain check-resolvable --json，并处理每一个标记：若两个 Skill 被同一触发词混淆，则为其添加用于区分的触发词，或将其合并；若某个 Skill 的触发词是另一个 Skill 的子集，则将其合并或使其更具体。

第 6 阶段：E2E、Brain 归档与定时运行可观测性（第 10-12 项）

• E2E 冒烟测试：从触发到副作用的完整流水线
• Brain 归档：若该 Skill 会写入 brain 页面，则添加到 brain/RESOLVER.md
• 定时运行可观测性：见下文

定时运行可观测性（第 12 项）——适用于任何由定时任务驱动的 Skill

若该 Skill 驱动 cron 或周期性任务，则该任务必须通过 minions 运行（从 cron 行调用 gbrain jobs submit），而不能使用裸 shell 管道，这样每次运行都会留下包含状态、进度和日志的任务记录——静默运行的幽灵 cron 是可观测性问题的头号来源。

验证：

gbrain jobs list             # the scheduled job appears with a status
gbrain jobs get <id>         # per-run progress + result is inspectable

调度模式见 skills/conventions/cron-via-minions.md 和 skills/cron-scheduler/SKILL.md；任务通道机制见 skills/minion-orchestrator/SKILL.md。

第 7 阶段：验证

bun test test/<skill>.test.ts                    # unit tests
gbrain skillify check skills/<slug>/scripts/<slug>.mjs --json | \
  jq '.[] | .items[] | select(.name | contains("Cross-modal"))'
ls -t ~/.gbrain/.gbrain/eval-receipts/<slug>-*.json | head -2   # receipt landed; prior baseline visible
gbrain check-resolvable --json | jq .ok          # resolver clean

完整示例：将 "summarize-pr" 功能 Skill 化

Phase 0: Mode A — invoked weekly, 50+ lines, clear trigger "summarize this PR"
Phase 1: Audit → SKILL.md missing, no tests, no resolver entry. Score: 1/15
Phase 2: Write SKILL.md + extract script to scripts/summarize-pr.ts
Phase 2.5: Declare eval_contract — goal: reviewer-ready PR summary;
  dimensions: file_coverage, test_plan, specificity;
  hard-fail: any fabricated claim about the diff
Phase 3: Cross-modal eval cycle 1 (dimensions from the contract; slots from
  models.eval.cross_modal.slot_*) →
  slot A (<provider-1 model>): file_coverage=6, test_plan=4, specificity=5 → "misses file-level diffs"
  slot B (<provider-2 model>): file_coverage=7, test_plan=5, specificity=5 → "no test plan in summary"
  slot C (<provider-3 model>): file_coverage=6, test_plan=5, specificity=5 → "template feels generic"
  Aggregate: file_coverage=6.3 FAIL, test_plan=4.7 FAIL
  Top improvements: add file-level changes, include test plan, use PR context
  → Apply fixes → Cycle 2: file_coverage=8, test_plan=7.5, specificity=7 → PASS
Phase 3.5: First-ever eval → the cycle-2 receipt becomes the baseline
Phase 4: Write 12 unit tests locking in the improved behavior
Phase 5: Add "summarize this PR" trigger to skills/RESOLVER.md
Phase 6: E2E test: feed a real PR URL → verify brain page created.
  Not schedule-backed → items 12–13 N/A
Phase 7: All green. Score: every applicable item passing

完整示例：改进现有 Skill（缺陷修复）

Input: the user reports the skill labeled a date with the wrong weekday
Skill: travel-brief (already has SKILL.md, code, an eval receipt)

Phase 0: Mode B (Improve) — SKILL.md exists, this is a bug fix
  Delta: the LLM composed day-of-week from reasoning instead of code

Phase 1: Audit existing artifacts
  SKILL.md ✓, code ✓, eval receipt ✓ (but weak — no day-of-week tests)
  Unit tests: ✗ (none existed)
  Integration tests: ✗ (none existed)
  → Missing: items 4, 5, 6. Plus the actual bug.

Phase 2: Fix the code
  - Added a getDayOfWeek(isoDate, tz) helper to the skill's script
  - Updated the formatter to use programmatic day names, never model output
  - Added HARD RULE to SKILL.md: "NEVER derive day-of-week from LLM reasoning"
  - Added a bug entry (template above): date, root cause, fix, tests
  - Bumped version 1.0.0 → 1.1.0

Phase 3: Cross-modal eval — skip (pure deterministic bug fix, behavior
  locked by new tests; prose unchanged)
Phase 3.5: Re-eval skipped per the 3b exception; Phase 7 re-verify still runs

Phase 4: Write tests
  - Unit tests covering every day of the week, timezone edges, formatting
  - Integration tests: state I/O, full pipeline, timezone crossing

Phase 5: Resolver — already routed ✓
Phase 6: E2E — existing pipeline still works ✓
Phase 7: All tests green. Bug fixed. Regression locked in.

质量门禁

在以下条件全部满足之前，不算完成正确的 Skill 化：

• 所有必需项通过（第 1-2 项、第 4-10 项；第 11 项仅在适用时；第 12-13 项仅在由定时任务驱动时）。
• 存在 eval 契约（第 0 项）——在 frontmatter 中声明，或在推断/询问后回写（第 2.5 阶段）。
• 跨模态 eval（第 3 项）有当前的回执，或附带理由明确豁免（第 3 项为信息性项目，不阻塞，但审计中会显示缺失的回执）。
• 无回归门禁通过（第 3b 项）：新的总分 ≥ 上一迭代的总分；任何维度的退步不超过 0.5。
• 若由定时任务驱动： 已重新运行一个代表性任务，完成 eval 并向前评分（第 13 项）。
• 所有测试通过（单元 + 集成 + LLM evals）。
• 存在带有真实触发短语的 resolver 条目。
• 可解析性检查显示没有孤立、重叠或 DRY 违规。
• 如适用，已完成 brain 归档。

输出格式

Skillify 为每个 skill 生成三个持久化产物：

1. 磁盘上的 skill 目录树。 skills/<slug>/SKILL.md（包含其 eval_contract）、scripts/<slug>.mjs、routing-eval.jsonl，以及 test/<slug>.test.ts 骨架。由 gbrain skillify scaffold <name> 生成，并由 Agent 细化为真正的实现。
2. 跨模态评测回执谱系，位于 ~/.gbrain/.gbrain/eval-receipts/<slug>-<sha8>.json。sha-8 将每份回执与生成它的 SKILL.md 内容绑定，因此历史回执会作为无回归基线被保留（见 Phase 3.5）。gbrain skillify check 会以信息形式显示当前回执的状态（found / stale / missing）。
3. 来自 gbrain skillify check 的审计结论：properly skilled | close — create: <missing items> | needs skillify — run /skillify on <target>。分数为 <passed>/<total>。必需项决定结论；跨模态项仅供参考，永远不会阻止 PASS。

JSON 输出（gbrain skillify check --json）包含相同字段，以及每项的详细说明字符串，因此 Agent 可以基于结构化信封进行路由，而无需解析文字说明。

失败时的处理

对于任何 gbrain 错误 code、退出码、[AGENT] 块或通知块，都应遵循 Agent 操作协议。针对本 skill 的具体情况：

• gbrain skillify check 报告未通过的检查项时：仅修复这些项并重新运行；任何编辑都必须保证现有测试保持通过（无回归原则）。
• gbrain eval cross-modal 失败或缺少提供方密钥时：将该评测报告为未运行；不得将该 skill 标记为已验证。
• gbrain check-resolvable 报告新 skill 不可达或与其他 skill 重叠时：修复其 RESOLVER 行并重新运行。Scaffolding 会将该行追加到占位的 ## Uncategorized 标题下；请将其移动到合适的分类中。

反模式

• ❌ 在跨模态评测之前编写测试（会锁定平庸水平）
• ❌ 使用低成本模型进行评测（C 级学生给 A 级学生打分）
• ❌ 三个评测位全部使用同一家提供方的模型系列（盲区相关联）
• ❌ 因为“输出看起来没问题”而跳过评测（你的判断不等于 3 个模型）
• ❌ 有评测但没有修复循环（虚荣指标）
• ❌ 用通用维度而非评测契约来评估高风险 skill
• ❌ 有代码却没有 SKILL.md（对解析器不可见）
• ❌ 测试重新实现生产代码（会掩盖真实缺陷）
• ❌ 解析器条目使用内部术语（必须与真实用户语言一致）
• ❌ 两个 skill 做同样的事（合并或删除其中一个）
• ❌ 对琐碎输出运行跨模态评测（少于 200 tokens，不值得 9 次 API 调用）
• ❌ 改进 skill 时从头重写（应使用 Mode B）
• ❌ 修复缺陷时不为该确切缺陷添加回归测试
• ❌ 修复缺陷时不在 SKILL.md 中添加 HARD RULE 以防止再次发生
• ❌ 交付得分低于上一次迭代的 skill 编辑（回归，我们只向前推进）
• ❌ 编辑由定时任务驱动的 skill 时，不重新运行一个有代表性的任务并评测其真实输出
• ❌ 在 skill 正文中硬编码某个部署环境的人员或渠道（应声明原则，由各部署环境填写具体信息）
• ❌ 编辑一个检查项却跳过 Phase 7 重新验证（会静默破坏以前通过的项）