upskill

upskill — 将 Agent 失败经验提炼为经过验证的技能

关键词：upskill · flash to pro · teacher student distillation · ralph loop skill validation

HKUDS/UpSkill（MIT）可以在不升级模型的情况下，将廉价／较弱的「Flash」模型变成「Pro」级表现。会话失败时，它会捕获完整上下文，让强大的 Teacher 模型分析失败并起草技能，然后在封闭的 Ralph Loop 中，使用较弱的 Student 模型对该技能进行验证（最多 3 轮），之后再存储。经过验证的技能会通过 CLAUDE.md 索引（始终处于上下文中）自动注入每个后续会话，并按需加载完整的 SKILL.md。在 Terminal-Bench 2.0 上，Flash 模型 + UpSkill 的通过率为 51.6%，每项任务成本为 $0.04，胜过作为验证基准的 Pro 模型（通过率 50.0%，每项任务成本 $0.06）——成本降低了 41%。结果记录在 tb_harbor_2.0/RESULTS.md 中。

此技能是一个优先路由的封装工具：它会安装工具、配置三个角色（Daily / Teacher / Student），并引导用户完成每日的捕获 → 构建 → 验证 → 提供服务循环。

何时使用此技能

• 用户想安装 UpSkill 或运行任何 /upskill-* 斜杠命令
• 用户想让廉价模型（「Flash」、Haiku、mini、DeepSeek-Flash）在重复性任务类别上的表现接近 Pro 模型
• 会话刚刚失败，用户想将失败经验转化为可复用、经过验证的技能，而不是只手动重试
• 用户想将成功的会话提炼为可复用的技能（不只是失败会话——/upskill-build 两者都适用）
• 用户询问 Ralph Loop、Teacher／Student 角色，或技能存储的提供服务模式（interactive 与 auto）如何运作

何时不使用此技能

• 用户想了解如何从头编写或规范化 SKILL.md 的通用指导 → 使用 write-a-skill 或 skill-standardization
• 用户想为本地仓库的技能质量创建逐步提高门槛的循环（冻结基准、每次修改一处，根据评分保留或还原），用于此 jeo-skills 仓库 → 使用 skill-autoresearch
• 用户想要通用的模型微调／RLHF 流程 → 这会更改权重；UpSkill 只会在前面添加上下文，不会训练任何内容
• 用户未使用 Claude Code，且没有等效的会话钩子／上下文注入机制 → 请先查看移植；不要承诺未适配框架的效果一致

三个角色

角色	设置位置	用途
Daily model	Claude Code settings.json	用户日常运行的模型——UpSkill 不会修改它
Teacher	~/.claude/upskill.conf	强大的模型——分析失败、起草技能（例如 claude-opus-4-7、deepseek-v4-pro[1m]）
Student	~/.claude/upskill.conf	较弱的模型——每项技能都必须先通过它的验证才能存储（例如 claude-haiku-4-5、deepseek-v4-flash）

前提条件

要求	备注
Claude Code	参考集成位于 cc-integration/
bash、python3、git	钩子和构建流水线所需
curl	仅用于远程单行安装程序
可访问 Teacher 和 Student 模型的 API	上游推荐使用 Anthropic 或 DeepSeek

说明

第 1 步 — 安装

# Remote (recommended)
curl -sSL https://raw.githubusercontent.com/HKUDS/Upskill/main/cc-integration/install.sh | bash -s -- --remote

# Local (from a cloned repo)
git clone https://github.com/HKUDS/UpSkill && cd UpSkill/cc-integration && bash install.sh

# Or via this skill's wrapper script (adds jeo-skills plugin registration too)
bash scripts/install.sh                 # remote install (default)
LOCAL_REPO=/path/to/UpSkill bash scripts/install.sh   # install from an existing clone

此操作会写入 ~/.claude/{hooks,skills,upskill-store}/ 和 ~/.claude/upskill.conf。之后如需更新，请在 Claude Code 中运行 /upskill-init——它会重新运行安装程序并迁移旧配置。

第 2 步 — 配置 Teacher / Student 模型

编辑 ~/.claude/upskill.conf：

UPSKILL_TEACHER="deepseek-v4-pro[1m]"   # or: claude-opus-4-7
UPSKILL_STUDENT="deepseek-v4-flash"     # or: claude-haiku-4-5
UPSKILL_SERVE_MODE="interactive"        # interactive (default) | auto

Daily 模型不会受影响——它仍由 Claude Code 自己的 settings.json 决定。运行 /upskill-model 查看当前预设，或在手动编辑后运行 bash ~/.claude/hooks/upskill-store.sh sync。

第 3 步 — 启用项目级构建

/upskill-configure

将 UserPromptSubmit、SessionStart 和 SessionEnd 钩子以及一个 claudeMd 指针合并到当前项目的 .claude/settings.local.json 中—— 仅作增量修改，绝不覆盖现有钩子条目。

第 4 步 — 正常使用 Agent；技能会自动构建

SessionEnd 钩子会捕获失败的会话（存在 verify.sh，且退出码非零）， 并设置待处理标记。下次会话开始时，Claude Code 会显示：

[upskill] ⚠ 1 pending failure(s) ready for building. Run /upskill-build to generate skills.

运行 /upskill-build（失败和成功的会话都适用），流水线便会在隔离的 git worktree 中执行 5 个阶段——完整的 Teacher → 生成 → Ralph 验证 流程，请参阅 references/pipeline-and-ralph-loop.md。

第 5 步 — 使用技能

经过验证的技能会通过全局 ~/.claude/upskill-store/CLAUDE.md 索引（每个技能约 5 行）自动出现在 Agent 的上下文中。在交互 模式（默认）下，运行 /upskill-run 浏览匹配项（★ = 推荐）并应用技能。在自动模式下，每次提示词都会进行关键词匹配，并主动推荐技能。使用 /upskill-mode auto|interactive 切换模式。

第 6 步 — 管理技能库

/upskill-list                                   # browse skills by category
/upskill-status                                 # skill count + active builds
/upskill-remove --category data-analysis --skill-id skill_20260605_001
/upskill-uninstall                              # remove hooks/skills/config

完整命令参考请参阅：references/commands.md。

工作原理 — Ralph 循环

大多数蒸馏方法止步于“Teacher 编写建议，希望能有所帮助”。 UpSkill 则通过闭环来改进：Student 应用草稿技能后重试任务；如果仍然失败，Teacher 会根据“即使有指导，问题仍出在哪里”来修订技能，最多进行 3 轮——如果始终未通过，就丢弃该技能。这样能校准每个存储的技能，使其符合 Student 模型实际能够遵循的内容，而非泛泛的最佳实践。架构、worktree 隔离以及 3 文件技能格式（领域知识／分步指南／反馈经验）详见 references/pipeline-and-ralph-loop.md。

移植到其他 Agent 框架

核心流水线（构建脚本、Ralph 循环、技能库）与框架无关；只有钩子集成和上下文注入层是 Claude Code 专用的。 移植到 Codex、OpenClaw 或 Cursor 需要：（1）等效的会话前／会话后钩子，（2）可自动加载上下文的 CLAUDE.md 等效机制，（3）等效的斜杠命令，（4）用于 Teacher／Student 运行的 worktree／沙箱隔离。不要声称未适配的框架完全兼容——应明确说明差距。

输出格式

当用户请求 upskill 提供帮助时，返回一份简洁的概要：

# upskill Routing Brief

## Scope
- Stage: install | configure-models | configure-project | build | serve | manage
- Roles: Teacher=<model> Student=<model> (Daily model unaffected)
- Serve mode: interactive | auto

## Recommended next move
- one concrete `/upskill-*` command or install step

## Why
- 2-3 bullets grounded in the user's packet

## Route-outs
- `skill-autoresearch` for repo-local skill-quality ratcheting
- `write-a-skill` / `skill-standardization` for hand-authoring a SKILL.md

示例

示例 1：注重成本的团队首次设置

使用远程一行命令安装，在 ~/.claude/upskill.conf 中设置 UPSKILL_TEACHER="claude-opus-4-7" 和 UPSKILL_STUDENT="claude-haiku-4-5"，然后在每个活跃项目中运行 /upskill-configure。Daily 模型仍使用团队在 settings.json 中原本配置的模型。

示例 2：重复出现的 CSV 解析任务在 Haiku 上屡屡失败

发生失败后，/upskill-build 会选取失败的会话，由 Teacher 起草技能，再由 Ralph 循环针对 Haiku 重试，最多进行 3 轮。通过后，该技能会自动出现在全局 CLAUDE.md 索引中，并通过 /upskill-run（交互模式）提供，或在下次类似 CSV 任务开始时通过关键词自动匹配。

示例 3：蒸馏成功的会话

/upskill-build 并非只能用于失败的会话——在一次顺利完成的会话上运行它，也能在有效方法被遗忘前，将其保存为可复用且经过 Student 验证的技能。

最佳实践

1. Teacher 绝不能等于 Student。 如果分析失败的模型与作为验证依据的模型相同，验证就毫无意义。
2. 也要从成功案例中构建技能，而不只是从失败案例中构建——/upskill-build 两者都接受，值得提炼的还有良好的工作模式。
3. 相信 Ralph Loop 的丢弃机制。 技能在 3 轮中全部失败，就会按设计被丢弃——不要手动强行保存未经验证的草稿。
4. 根据审核意愿选择服务模式。 interactive（默认）会让人工逐项参与每个任务；auto 则以零摩擦匹配为代价，省去人工参与。
5. 上游发布新版本后，重新运行 /upskill-init，不要手动修改 ~/.claude/hooks/*.sh——它能安全迁移旧版配置。
6. 纯粹的技能编写或规范合规请求应转交给其他工具——此技能负责提炼流程，而不是编写通用的 SKILL.md。

参考资料

• 上游仓库：https://github.com/HKUDS/UpSkill
• 完整的 CC 集成文档：https://github.com/HKUDS/UpSkill/blob/main/cc-integration/README.md
• Terminal-Bench 2.0 结果：https://github.com/HKUDS/UpSkill/blob/main/tb_harbor_2.0/RESULTS.md
• 命令参考：references/commands.md
• 流程与 Ralph Loop 详情：references/pipeline-and-ralph-loop.md
• 安装脚本：scripts/install.sh
• 相关技能：../skill-autoresearch/SKILL.md、../write-a-skill/SKILL.md、 ../skill-standardization/SKILL.md
• 许可证：MIT（参见上游 LICENSE）