AI编程智能体技能生成工具upskill完整入门:为什么让昂贵的教师模型为廉价学生模型"备课"

原创2026-10-28 20:51:561,628 阅读

AI编程智能体技能生成工具upskill完整入门:为什么让昂贵的教师模型为廉价学生模型"备课"

如果你正在使用 Claude Code、OpenAI Codex 等 AI 编程智能体,一定遇到过这个矛盾:强模型又贵又慢,廉价模型便宜但经常做不对。upskill 是一款开源的 AI 编程智能体技能生成与评估工具:它让昂贵的"教师模型"自动撰写可复用的 SKILL.md 技能文档(相当于"备课"),再自动出题、评分、迭代打磨,让廉价的"学生模型"照着讲义也能稳定完成高难度任务。一次"备课",长期使用,成本立省。

💡 upskill 是什么:把教师模型的经验变成"讲义"

传统做法是直接调用最贵的模型完成每次任务;而 upskill 的思路是知识蒸馏:

  1. 教师模型(teacher):如 Claude Sonnet/Opus,能力强但贵,只负责"写讲义"——生成结构化的技能文档;
  2. 学生模型(student):如 Claude Haiku,便宜快速,日常任务交给它 + 技能文档执行;
  3. 自动评分:upskill 会生成测试用例,分别跑"无技能(baseline)"和"带技能(with-skill)"两轮,用数据验证学生模型到底提升了多少。

upskill 内部通过三个"智能体卡片(agent card)"分工协作,这也是它的核心设计:

角色 文件 职责
技能生成器 skill_gen.md 把任务描述写成 SKILL.md 讲义
出题器 test_gen.md 自动生成 3~5 个测试用例
评估器 evaluator.md 按测试用例执行并打分

📌 核心源码:技能生成与打磨逻辑在 generate.py,评估与基线对比在 evaluate.py,命令行入口在 cli.py。

🎯 "备课"的核心流程:四个阶段自动闭环

upskill 把工作拆成四个显式阶段,模型角色各归各位:

阶段 做什么 默认模型角色
技能生成 创建/打磨 SKILL.md 讲义 教师模型(--model)
测试生成 产出合成评测用例 出题模型(--test-gen-model)
评估 用例 × 评估模型实测打分 学生模型(--eval-model / -m)
基准测试 多模型、多轮重复评估 多个模型(benchmark 模式)

妙处在于自动打磨循环:如果学生模型带着讲义还答错,upskill 会把失败案例反馈给教师模型重写讲义(默认最多 2 轮,由 max_refine_attempts 控制),直到通过。整个过程你只需要一句话。

生成的技能长什么样?

技能按标准目录格式保存(默认在 ./skills/{skill-name}/):

./skills/git-commit-messages/
├── SKILL.md          # 主技能讲义
├── references/       # 参考文档(可选)
└── scripts/          # 可执行脚本(可选)

SKILL.md 包含 YAML 前置元信息(name、description)+ 正文(概述、步骤、2~3 个代码示例、最佳实践),可直接放入 ~/.claude/skills/ 被 Claude Code 自动发现。仓库里有一份示例:example-skill/SKILL.md。

⚡ 5分钟快速上手:安装并生成第一个技能

一键安装(要求 Python ≥ 3.13):

uv pip install upskill
# 或者免安装直接用 uvx
uvx upskill

然后确保环境变量中已配置 ANTHROPIC_API_KEY(或其他模型对应密钥),就能生成第一个技能:

upskill generate "write good git commit messages"

教师备课 + 学生验收的组合拳(本文标题里的主角):

upskill generate "write good git commit messages" --model sonnet --eval-model haiku

这行命令的意思是:用 sonnet 写讲义,让 haiku 来考。运行后终端会输出类似这样的结果:

baseline   ████████████░░░░░░░░   60%
with skill ████████████████████  100%  (+40%)

tokens: 1200 → 800  (-33%)
Saved to ./skills/git-commit-messages

看到 +40% 提升和 token 下降,说明这份"备课"值回票价。

💡 小技巧:upskill generate "document the pattern" --from ./trace.md 还能基于你之前智能体的真实对话轨迹提炼技能,把踩过的坑直接固化成讲义。

📊 技能评估与多模型基准测试:学生到底值不值得"报名"

技能生成后,用 eval 命令对它做体检:

# 单模型评估(自动对比 baseline)
upskill eval ./skills/git-commit-messages/ -m haiku

# 多模型基准测试:一张表格横向对比
upskill eval ./skills/git-commit-messages/ -m haiku -m sonnet --runs 5

⚠️ 注意:传入多个 -m 或 --runs > 1 时会自动进入基准测试模式,此时基线对比自动关闭。输出的表格会列出每个模型的通过率(Pass Rate)、平均断言得分与平均 token 消耗,让你直观判断"换大模型"和"小模型+技能"哪个更划算。

想回头看历史数据,用 runs 命令:

upskill runs --skill git-commit-messages     # 可视化柱状图
upskill runs --metric tokens                 # 看 token 消耗
upskill runs --csv ./results.csv             # 导出 CSV

所有运行记录默认归档在 ./runs/ 目录(按时间戳批次保存 metadata 与结果 JSON),可用 --no-log-runs 关闭。

各命令模型参数速查表

命令 参数 含义
generate --model 技能生成/打磨模型(教师)
generate --eval-model 额外跨模型评估(学生)
eval / benchmark -m, --model 评估模型,可重复传多个
eval / benchmark --test-gen-model 出题模型(不填则回退到教师模型)
runs / plot -m 仅用于筛选历史数据

⚙️ 配置与进阶:从本地到 Hugging Face Jobs

配置文件 upskill.config.yaml

项目根目录的 upskill.config.yaml 是主要配置入口,常用字段:

skill_generation_model: sonnet   # 教师模型
test_gen_model: opus             # 出题模型
eval_model: haiku                # 学生模型
max_refine_attempts: 2           # 自动打磨轮数
executor: local                  # local | jobs

配置查找顺序:环境变量 UPSKILL_CONFIG → 项目内 ./upskill.config.yaml → ~/.config/upskill/config.yaml。配套的 fastagent.config.yaml 则控制底层 FastAgent 的日志、流式输出与 MCP 服务器。

远程执行:把评估搬到云端

v2 版本推荐把评估跑在 Hugging Face Jobs 上:把 executor 改为 jobs,设置好 HF_TOKEN,并指定产物仓库即可:

upskill generate "parse invoices" --executor jobs --artifact-repo <user>/upskill-tests

提交任务的逻辑见 hf_jobs.py,远程作业入口脚本在 scripts/hf/submit_hf_job.sh。批量评测时云端并行(--max-parallel 可调)比本地快得多。

本地模型也支持

通过任意 OpenAI 兼容端点(llama.cpp、vLLM、Ollama)接入本地模型:

upskill eval ./skills/my-skill/ -m generic.my-model

模型命名遵循 FastAgent 格式 <provider>.<model>.<reasoning_effort?>,解析逻辑在 model_resolution.py。

🧰 更多玩法

  • 从对话历史挖掘技能:仓库自带的 propose-skills.sh 脚本会扫描你的 Claude Code 对话历史,让 Claude 自动提出 3~5 个值得固化的技能提案,选中的直接生成 SKILL.md。
  • Python API 集成:generate_skill、generate_tests、evaluate_skill、refine_skill 四个异步函数可直接在代码中编排,拿到 skill_lift(技能提升幅度)与 token_savings(token 节省率)指标。
  • 改进已有技能:upskill generate "add error handling examples" --from ./skills/api-errors/ 会自动识别为目录并进入"增强"模式。

📁 项目结构速览

模块 说明
src/upskill/cli.py 命令行入口(generate/eval/list/runs)
src/upskill/generate.py 技能生成、出题、打磨
src/upskill/evaluate.py 评估编排与基线对比
src/upskill/agent_cards/ 三个智能体卡片定义
src/upskill/executors/ 本地 / 远程(HF Jobs)执行后端
upskill.config.yaml 项目配置示例
README.md 完整文档与命令参考

🚀 总结:什么时候该用 upskill?

✅ 适合:你高频使用廉价模型但总被难题卡住;需要把团队最佳实践沉淀成可评估、可复用的智能体技能;想量化"技能到底带来多少提升"。

❌ 不必用:任务一次性且简单、或者你本来就只用顶配模型。

一句话记住 upskill 的价值:让最贵的模型只干活(备课),让最便宜的模型只上课(执行)——用一次性的教师成本,换长期的学生产出。现在就可以打开终端,敲下 upskill generate "你的第一个技能描述" 试试。

登录后查看全文
upskill