skill-eval-improve

技能评估与改进

以可衡量的方式改进技能：建立基线 → 测量 → 有界编辑 → 重新验证。结合本地工具、Codex plugin-eval（如果已安装）和基于研究的循环（SkillOpt）。

适用场景

• 技能触发错误或从不加载（描述路由）
• SKILL.md 臃肿、令牌成本高、效果不佳
• 添加新流程后，需要进行回归检查
• 将产品 MCP / plugin-eval 研究中的模式移植到 Skill Steward 技能中

不适用场景

• 批量验证仓库 — 例如“验证此仓库中的每项技能” → 只运行 pnpm run validate（审计请参阅 skill-authoring-lifecycle）；不要启动基准测试或 SkillOpt 循环。
• 自动化 SkillOpt / 集群训练 — Skill Steward 记录的是手动有界编辑循环；没有隔夜优化器流水线。
• 创建新技能 — 请先使用 skill-authoring-lifecycle；技能存在后再应用评估与改进。

Cursor 范围（可选）：编辑 skills/** 或 scripts/validate-skills.mjs 下的内容时激活。

专家混合（评估栈）

层级	专家	工具 / 方法	耗时
0 — 门槛	代码检查	pnpm run validate、skill-authoring-lifecycle	秒
0b — 规则	路由 / 文档 SSOT	pnpm run eval（T1 行为关键 YAML 用例）	秒
1 — 静态	结构	Codex plugin-eval analyze（如可用）	秒
2 — 人工	行为	使用 / 不使用技能分别测试 3–5 个提示词	分钟
3 — 测量	使用情况	plugin-eval benchmark + measurement-plan	分钟至小时
4 — 演进	文本优化	类似 SkillOpt 的有界编辑 + 留出集门槛	小时
5 — 导航	遥测 / 内部试用	当前 steward benchmark 场景的精简跟踪记录	秒

使用能回答问题的成本最低层级。不要跳过第 0 层。

第 0 层 — Skill Steward 验证器（始终运行）

pnpm run validate
pnpm run validate:json   # CI / automation

修复所有 error: 行。认真对待 warn:（缺少 sources.md、SKILL.md 过长）。

T 命名技能质量门槛（ADR 0011，ADR 0027）

层级	技能	CI
T1 — 行为关键，评估门控	路由 / 流程技能，其偏移可能改变 Agent 的决策、声明、委派、治理或证据边界	pnpm run eval + validate
T2 — 仅结构验证	其他所有技能	pnpm run validate

目前的 T1 行为关键技能包括 harness-engineering-lifecycle、mcp-harness-repo-maintainer、mixture-of-experts、multi-agent-handoff、plugin-marketplace-setup、repo-quality-system-lifecycle、repository-governance-lifecycle、skill-authoring-lifecycle、skill-eval-improve、steward-continuity-boundary-lifecycle 和 vision-alignment-foresight。每项技能都需要 evals/cases/*.yaml（≥2 个）和 references/evals.md。架构：eval-case-schema.md。

第 0b 层 — 基于规则的用例（T1 行为关键 CI）

pnpm run eval
pnpm run eval -- --skill mcp-harness-repo-maintainer
pnpm run eval:json

Chrome 评估设计（失败模式、评分标准、客观评估与评审）：references/chrome-eval-design.md。

CI 不会运行大模型评审。主观质量评估留在 references/evals.md 中（第 2 层及以上）。

第 1 层 — Codex plugin-eval（本地）

安装了 Codex plugin-eval 时（~/.codex/plugins/.../plugin-eval）：

# Chat-first router
plugin-eval start skills/<name> --request "Evaluate this skill." --format markdown

# Static report
plugin-eval analyze skills/<name> --format markdown

# Token budget explanation
plugin-eval explain-budget skills/<name> --format markdown

# Starter benchmark config
plugin-eval init-benchmark skills/<name>
plugin-eval benchmark skills/<name> --dry-run

完成 analyze --brief-out 后，将改写计划交给 plugin-eval 的 improve-skill 技能处理。

详情：references/plugin-eval.md。

第 2 层 — 人类提示词套件（实质性编辑必需）

1. 编写 3–5 条有代表性的用户提示词（应触发 + 不应触发）。
2. 不使用技能运行 Agent → 记录失败。
3. 使用技能运行 → 记录改进和新出现的失败。
4. 将提示词同步到 evals/cases/*.yaml（CI 规则）和 references/evals.md（行为日志）。

将约 60% 用作训练集（针对其编辑）/40% 用作留出集（用于验收门槛）——这与 SkillOpt 的选择门槛相呼应。

第 3 层 — 受 SkillOpt 启发的改进循环（研究）

SkillOpt 将 SKILL.md 视为可训练文本，并冻结 Agent：

Rollout (tasks + current skill) → Reflect (failures vs successes)
  → Bounded edit (add/delete/replace under budget) → Held-out gate (keep only if better)

Skill Steward 手动调整（无需 GPU 集群）：

步骤	操作
1	基线：不使用技能时的留出集通过率
2	使用技能：对相同任务记录通过率
3	反思：列出 1–3 个具体失败模式
4	有限编辑：行变更不超过 10%，或新增一个章节；不进行全面重写
5	仅重新运行留出集；只有效果有所提升时才保留编辑
6	在 references/evals.md + sources.md 中记录结果

论文：https://arxiv.org/abs/2605.23904 · 网站：https://microsoft.github.io/SkillOpt/

相关项目：SkillLens（模型生成技能研究）。

第 4 层 — 生态系统基准（2026 年及以后）

资源	用途
SkillsBench	为原生任务与增强技能的任务配对提供灵感
skillgrade	对技能质量进行回归测试（mgechev）
Claude 编写最佳实践	先评估、后编写的工作流

第 5 层 — 运行时实测基准

规模达到 10,000 倍时，由于大模型在浏览海量工具集时会遭遇认知过载，NLP 提示词评估会失效。运行时实测应使用确定性轨迹，客观断言其逻辑执行路径。

1. **捕获精简轨迹：**存储操作 ID、工具调用数量、产物摘要和脱敏摘录，而非原始产品轨迹。
2. **定义断言：**预期操作轨迹、优先使用的已声明界面、最大工具调用次数、最大修复/设置尝试次数、最大无关工具调用次数、必需的 return_to_goal_step、必需的产物，以及针对无关操作的负向检查。
3. **运行实测基准：**运行时实测场景使用 steward benchmark --scenario <id> --json。不要将产品运行时场景放入 T1 行为关键技能评估中。

当前通过 steward eval --name 注册评估的路径属于旧版/实验性功能。技能质量评估仍使用 pnpm run eval；运行时实测应使用 steward benchmark。当契约输入被修改或未跟踪时，durability_blocked 是有效的阻塞证据，而非运行时行为的证明。

改进工作流（检查清单）

- [ ] sources.md cites plugin-eval + SkillOpt if used
- [ ] pnpm run validate
- [ ] T1 behavior-critical: `pnpm run eval` + cases updated
- [ ] plugin-eval analyze (optional)
- [ ] 3+ prompt evals documented in references/evals.md
- [ ] Bounded edit applied; held-out improved
- [ ] skill-authoring-lifecycle checklist
- [ ] PR mentions eval delta

优先修复项（常见顺序）

1. name / description（路由）——必须包含内容 + 时机
2. 损坏的链接 / 缺少 references/sources.md
3. 新增章节或评估用例前，先删除或替换重复规则
4. 将大段内容移至 references/（SKILL.md < 500 行）
5. 补充 Agent 会跳过的错误处理 / 验证步骤
6. Token 成本（描述长度、始终加载的内容）

反模式

• 因一次失败就重写整个 SKILL.md（破坏有效规则）
• 不使用留出集提示词就自行编辑（过拟合）
• 仅根据一次观察到的运行添加技能规则、评估或工具，而较简短的常见问题解答、错误消息、原生命令、效果检查或删除就能解决问题
• 对重复指导新增评估项，而未先尝试压缩、删除或替换重叠规则
• 声明未附带 references/sources.md 条目
• 只通过静态分析进行评估——从不运行真实提示词
• 在 CI 中使用 LLM 评判（不稳定、成本高）——仅离线使用，参见 ADR 0011
• 通过 pnpm run eval 后就声称 Agent 行为已得到证明

Related skills

Skill	Role
skill-source-citations	Save research links
skill-authoring-lifecycle	Scaffold
skill-authoring-lifecycle	Pre-merge audit

Sources

See references/sources.md.

Install

npx skills add arenukvern/skill_steward --skill skill-eval-improve