AI编程智能体技能生成工具upskill完整入门:为什么让昂贵的教师模型为廉价学生模型"备课"
AI编程智能体技能生成工具upskill完整入门:为什么让昂贵的教师模型为廉价学生模型"备课"
如果你正在使用 Claude Code、OpenAI Codex 等 AI 编程智能体,一定遇到过这个矛盾:强模型又贵又慢,廉价模型便宜但经常做不对。upskill 是一款开源的 AI 编程智能体技能生成与评估工具:它让昂贵的"教师模型"自动撰写可复用的 SKILL.md 技能文档(相当于"备课"),再自动出题、评分、迭代打磨,让廉价的"学生模型"照着讲义也能稳定完成高难度任务。一次"备课",长期使用,成本立省。
💡 upskill 是什么:把教师模型的经验变成"讲义"
传统做法是直接调用最贵的模型完成每次任务;而 upskill 的思路是知识蒸馏:
- 教师模型(teacher):如 Claude Sonnet/Opus,能力强但贵,只负责"写讲义"——生成结构化的技能文档;
- 学生模型(student):如 Claude Haiku,便宜快速,日常任务交给它 + 技能文档执行;
- 自动评分: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 "你的第一个技能描述" 试试。