Pg skill forge

pg-skill-forge

Peter Gao 的 opencode 技能工厂。创建 / 评估 / 优化 agent skill。

已验证事实 (spike 2026-06-20)

• ✅ subagent 能调用 Skill tool: dispatch 的 general subagent 拥有 skill 工具,成功加载过 ce-commit。Executor 自然触发机制架构可行。
• ✅ subagent 的 skill 调用被 DB 记录: part 表捕获到 subagent 调 ce-commit 的记录 (tool='skill', state.input.name='ce-commit')。eval 链路完整: subagent 调 skill → DB part 表 → db_query 可查。
• ✅ 主 agent 用 task 工具 dispatch subagent (主 agent 工具集有 task; Executor subagent 用 Skill tool, 不用 task)。

何时不要用

• 一次性问答、解释、翻译、总结 (直接回答)
• 已有领域 skill 能做的事 (docx/pdf/xlsx)
• 头脑风暴 (用 brainstorming)

两条路径

路径	触发	流程
fast-path (日常沉淀)	"做成一个 skill" / "把这个流程沉淀"	①②③④ → init_skill 直出
eval 闭环 (认真打磨)	"优化触发率" / "测准不准" / "触发不准"	+ ⑤评估闭环

默认 fast-path。仅当显式要求优化/度量触发时进 eval 闭环。

---

A. 创建 skill (fast-path)

1. 捕获意图: 这 skill 让 opencode 能做什么? 何时触发(用户说什么话)? 输出格式? 何时不该触发(近邻陷阱)?
2. 写 description (frontmatter, 触发依据): 先写, 这是触发准确度的根。
3. 脚手架: python scripts/init_skill.py <name> --archetype scaffold|production --desc "<description>"
4. 填 SKILL.md (按 TODO)。Production 额外填 evals/evals.json。
5. 校验: python scripts/quick_validate.py ./<name>

---

B. eval 闭环 (评估 + 优化触发率)

物理证据架构: 触发判定不查 LLM, 而是查 opencode.db 的 part 表 (tool='skill')。Executor subagent 跑 query, 运行时记录它是否调了 Skill tool, 脚本读 DB 判定。消除自评偏差。指标用 accuracy=(TP+TN)/total, 避免选出 over-triggering 的 description。

三角色

角色	谁来做	工具
Executor (被测)	你用 task 工具 dispatch 的 general subagent	Skill tool (自然触发)
Proposer	你用 task 工具 dispatch 的 general subagent	生成候选 description
Judge	你(主 agent)自己, 不 dispatch	读 run_trigger_eval select-best 输出按 test accuracy 选最高

Judge 是机械决策(按 held-out test accuracy 排序), 无主观判断, 主 agent 自己做无偏差问题。阶段2 才抽出独立 grader.md。

执行步骤 (主 agent 编排)

Step 1 — 确保 eval 集 (<skill>/evals/evals.json):

• 必须: 每条有唯一 id; pos(应触发)/neg(不该触发的 near-miss) 各 ≥5 条, 总 N≥15 (推荐 ≥30)。
• prepare 会校验, 不满足直接拒绝。

Step 2 — 生成调度单:

python scripts/run_trigger_eval.py prepare ./<skill> --runs 3

产出 eval_plan.json (60/40 train/test 切分)。

Step 3 — 跑 baseline (当前 description): 对 eval_plan.json 每个 query, 用 task 工具 dispatch general subagent, prompt 见下方 Executor 模板, runs_per_query 次。每次 dispatch 后, 从 task 返回结果里取 session_id (确定性来源, 勿用"取最新"以免并发竞态), 追加到 <skill>/results.jsonl:

{"query_id":"q1","run":1,"session_id":"ses_xxx","candidate":"baseline"}

每行必须含 candidate 字段, 漏填会被归入 default 组导致对比失败。

Step 4 — 统计 baseline:

python scripts/run_trigger_eval.py score ./<skill>/eval_plan.json --results ./<skill>/results.jsonl

看 test accuracy / TPR / FPR。

Step 5 — 优化迭代 (≤5 轮): 多候选对比用物理复制 skill 目录方案 (DB 的 skill_name 固定, 同 skill 不同标签无法区分, 必须不同 name):

1. dispatch Proposer subagent (模板见下): 给当前 description + 触发失败的 query, 生成 1-2 个改进候选。
2. 每个候选复制一个 skill 目录: cp -r ./my-skill ./my-skill-v1, 改 my-skill-v1/SKILL.md 的 name=my-skill-v1 + description=候选1。不同 name → DB 的 skill_name 不同 → 可区分。
3. 对每个候选目录重复 Step 2-3 (evals 可复用, candidate 字段标为 v1/v2)。
4. python scripts/run_trigger_eval.py report ./eval_plan.json --results ./results.jsonl 按 test accuracy 对比。
5. Judge (你自己): 按 held-out test accuracy 选最高; 平局偏好 FPR 更低(更保守)的。
6. 把 best 候选的 description 写回原 <skill>/SKILL.md。迭代直到 test accuracy 不再提升。

Step 6 — 收尾 + 治理闭环:

1. run_trigger_eval.py select-best ... 确认最优候选, description 写回 SKILL.md。
2. eval-viewer/generate_review.py <plan> --results <r> --output report.html 生成 HTML 评审 (人/agent 复核 DB 证据)。
3. (多 run) aggregate_benchmark.py run1.json run2.json --baseline baseline 看跨 run 稳定性 (stddev 大 = flaky)。
4. (治理) governance_check.py ./<skill> --eval-report <score.json> --promote stable — pass_rate≥0.8 可晋升 stable。

阶段2 可选增强 (dispatch subagent)

阶段1 Judge 主 agent 自任 (机械决策)。以下场景 dispatch 独立 subagent (task 工具, prompt = agents/<role>.md 内容 + eval 数据):

• 候选≥3 且 test accuracy 平局 → dispatch agents/grader.md 独立裁决 (4 条决策规则)。
• 排除 baseline 偏见 → dispatch agents/comparator.md 盲测 A/B (不告知哪个是 baseline)。
• 找系统性盲点 → dispatch agents/analyzer.md 配合 aggregate 挖模式 (non-discriminating / flaky / 系统性 FP/FN)。

执行预算 (spec §7.3)

• dispatch 总数硬上限 200 (超限停止用 best-so-far)。
• Executor 并发上限 4。
• 单 subagent 120s 超时 = 记为该 query 未完成(不计入统计)。
• results.jsonl 每条 flush; score 支持断点续跑(自动跳过损坏行 + 按 query_id/run/candidate 去重)。

Executor subagent prompt 模板

用户发来一条消息, 请自然地处理它 (可以调用任何可用的 skill/tool, 也可以不调)。不要提及"测试""评估""触发"。

用户消息: {prompt}

不告知在测试、不点名目标 skill。测的就是自然触发。spike 已证 subagent 有 Skill tool 且调用会被 DB 记录。

Proposer subagent prompt 模板

你是 skill description 优化专家。给定当前 description 和触发表现, 生成 1-2 个改进版 description。
目标: 提高 accuracy (应触发的更易触发, 不该触发的 near-miss 不触发)。
当前 description: {desc}
漏触发 (应触发但没触发, FN): {missed_pos}
误触发 (不该触发却触发了, FP): {false_pos}
输出: 每行一个候选 description (只输出 description 文本)。

---

工具速查

命令	用途
init_skill.py <name> --desc "..."	创建 skill
quick_validate.py ./<name>	校验
db_query.py --session <sid>	查某 session 调用了哪些 skill
db_query.py --session <sid> --skill <name>	判定 skill 是否触发 (退出码 0/1)
run_trigger_eval.py prepare ./<skill>	evals.json → eval_plan.json
run_trigger_eval.py score <plan> --results <r>	统计 accuracy/TPR/FPR
run_trigger_eval.py report <plan> --results <r>	多候选对比 (按 test accuracy 排序)
run_trigger_eval.py select-best <plan> --results <r>	选最优候选
cross_packager.py ./<skill> --targets opencode,trae	跨平台打包 (opencode/claude/trae/generic)
governance_check.py ./<skill>	治理状态 + 晋升 gate (pass_rate>=0.8)
eval-viewer/generate_review.py <plan> --results <r> --output report.html	生成 HTML 评审报告 (Benchmark+DB证据)
aggregate_benchmark.py run1.json run2.json --baseline X	跨 run 聚合 mean/stddev (稳定性)

脚本相对本 skill 的 scripts/。零第三方依赖 (Python 3.10+ stdlib)。

参考

• references/skill-engineering-method.md — 7 阶段工程法
• references/skill-archetypes.md — Scaffold / Production 原型
• docs/design.md — 完整设计 (评审决策 + Open Questions)
• docs/solutions.md — DB 物理证据 / 踩坑记录