developing-gbrain-skill

能力目标

让 Agent 走完一个 GBrain 自定义 skill 的完整生命周期：scaffold 生成骨架 → 填写业务规则并替换强制占位标记 → 过 check-resolvable 与 routing-eval 两个质量门 → 在路由表注册 trigger → 真实触发并写入 brain，得到一个可路由、可测试、可用的 skill。

前置

• 一个 skill = 一份 SKILL.md（YAML frontmatter 声明 name/description/triggers/writes_to 等 + Markdown body 声明业务规则）+ 一份 .mjs 实现脚本，通过 RESOLVER.md / AGENTS.md 的 trigger 行映射到自然语言触发短语。
• 设计意图是分离「可自动生成的骨架」与「需领域专家判断的业务逻辑」：scaffold 出骨架、开发者填空、机械检查器验收，不让任何一步「看起来完成实际空洞」。
• gbrain 命令用 timeout 包裹（exit 124 正常）。

实操流程

1. scaffold 骨架。--description 是必填（省略报错 exit 2）：

   gbrain skillify scaffold my-meeting-action-extractor \
     --description "Extract action items from meeting notes and write them to attendee Open Threads" \
     --triggers "extract action items,meeting action items,process meeting notes" \
     --writes-to "people/" --writes-pages --mutating
   

   产出 4 新文件（SKILL.md / scripts/<name>.mjs / routing-eval.jsonl / test/<name>.test.ts）+ 追加 1 个路由文件。scaffold 写到当前 workspace 的本地 skills/ 目录（如 ~/.openclaw/workspace/skills/）、不是全局安装路径——自定义 skill 是 workspace-local 的。

2. 确认 SKILLIFY_STUB sentinel 已植入（强制手工介入标记，只要它还在任何文件里、check-resolvable 就报 skillify_stub_unreplaced error）：

   grep -r "SKILLIFY_STUB" ~/.openclaw/workspace/skills/my-meeting-action-extractor/
   

3. 填空——这是唯一需要领域判断的环节。编辑 SKILL.md body 写完整业务规则（## The rule 段：如识别 TODO: / Action: / Follow up: 前缀行、提取 owner + task + due），编辑 scripts/<name>.mjs 实现核心函数（解析 markdown → 正则匹配 action item → 结构化 JSON → gbrain put 写入对应 person 的 Open Threads），替换掉两处 SKILLIFY_STUB。确认清除：

   grep -r "SKILLIFY_STUB" ~/.openclaw/workspace/skills/my-meeting-action-extractor/ 2>/dev/null \
     && echo "还需替换" || echo "sentinel 已清除"
   

4. 过质量门 1（check-resolvable，路由完整性）：

   cd ~/.openclaw/workspace && gbrain check-resolvable --strict; echo "exit: $?"
   

   替换 sentinel 后 skillify_stub_unreplaced 应从报告消失（D-CX-9 gate 通过）。若 workspace 有其他 skill 的历史积压问题（pre-existing errors）或本 skill 尚有 routing_miss，exit 仍为 1——干净 workspace 里替换 sentinel + 解决 routing_miss 后才 exit 0。

5. 过质量门 2（routing-eval，路由准确率）。先写 routing-eval.jsonl fixture（每行 {"intent":"...","expected":"<skill-name>"}、≥3 条、用多样措辞），跑评测：

   cd ~/.openclaw/workspace && gbrain routing-eval
   

   若 Top-1 accuracy 低（如只 20%），说明 trigger 短语覆盖不足——只注册了 1 个短语而 fixture 用了其他措辞。

6. 注册 trigger 补全覆盖：在 RESOLVER.md（source of truth、优先于 AGENTS.md）与 AGENTS.md 补多个措辞变体的 trigger 行，重跑 routing-eval 直到 100%。保持 MECE：每个 entity type / signal source 有且只有 1 个 owner skill。

7. 触发验证。dream 不触发自定义 skill；正式触发走 MCP Server（gbrain serve），手动验证走 deterministic script：

   cd ~/.openclaw/workspace && bun \
     skills/my-meeting-action-extractor/scripts/my-meeting-action-extractor.mjs \
     meetings/q3-kickoff < q3-kickoff-meeting.md
   gbrain get people/tom-wells   # 看 Open Threads 是否写入新条目
   

校验回路

• grep -r SKILLIFY_STUB 无输出（sentinel 全部清除）。
• gbrain check-resolvable --strict 报告里不再含 skillify_stub_unreplaced。
• gbrain routing-eval 的 Top-1 accuracy ≥ 80%（理想 100%，5 条 fixture 全命中目标 skill）。
• deterministic script 产出结构化结果、gbrain get <目标 page> 的 ## Open Threads 含 skill 写入的新条目。

常见陷阱

• --description 是必填：省略直接 exit 2。命令示例里必须带。
• skillify_stub_unreplaced 是 error 级、advisory 模式也不放过：即使不加 --strict，只要 sentinel 还在，check-resolvable 就 exit 1。它是硬阻塞门。
• exit 1 未必是本 skill 的问题：有历史积压问题（其他 skill 的 unreachable / mece_gap）的 workspace，替换 sentinel 后 exit 仍 1；判断本 skill 是否合格看「报告里本 skill 的条目是否清空」，不是看整体 exit code。
• routing-eval 是量化回归测试、不是形式检查：它能暴露 trigger 覆盖不足（fixture 用了未注册的措辞就 miss）。fixture 应用多样自然语言、不要逐字复制 trigger 短语（会触发 lint:intent_copies_trigger 提醒）。
• check-resolvable 检测 mece_gap（frontmatter 缺 triggers 数组）、但 MECE 语义正确性靠人判：两个 skill 是否真的不重叠（各 own 不同 entity type 与工作阶段）需开发者自己保证。
• dream 不触发自定义 skill：dream 有自己独立的 phase 列表。自定义 skill 靠 MCP Server 或 deterministic script 触发。