Turn a weak/cheap "Flash" model into a "Pro" performer by wrapping HKUDS UpSkill — captures agent session failures, has a strong Teacher model analyze them and draft a skill, then validates it against the weak Student model in a closed Ralph Loop (up to 3 rounds) before storing it for automatic reuse. Use when the user wants to install UpSkill, run `/upskill-init`, `/upskill-configure`, `/upskill-build`, `/upskill-run`, `/upskill-list`, `/upskill-status`, `/upskill-mode`, `/upskill-model`, `/upskill-remove`, or `/upskill-uninstall`, wants a cheap model to perform closer to a Pro model without switching, or wants a good session (success or failure) distilled into a validated skill. Triggers on: upskill, up-skill, flash to pro, teacher student distillation, ralph loop skill validation, distill agent failures into skills. Routes skill-quality ratcheting to `skill-autoresearch`, scaffolding to `write-a-skill`, and spec-compliance rewrites to `skill-standardization`.
Turn a weak/cheap "Flash" model into a "Pro" performer by wrapping HKUDS UpSkill — captures agent session failures, has a strong Teacher model analyze them and draft a skill, then validates it against the weak Student model in a closed Ralph Loop (up to 3 rounds) before storing it for automatic reuse. Use when the user wants to install UpSkill, run `/upskill-init`, `/upskill-configure`, `/upskill-build`, `/upskill-run`, `/upskill-list`, `/upskill-status`, `/upskill-mode`, `/upskill-model`, `/upskill-remove`, or `/upskill-uninstall`, wants a cheap model to perform closer to a Pro model without switching, or wants a good session (success or failure) distilled into a validated skill. Triggers on: upskill, up-skill, flash to pro, teacher student distillation, ralph loop skill validation, distill agent failures into skills. Routes skill-quality ratcheting to `skill-autoresearch`, scaffolding to `write-a-skill`, and spec-compliance rewrites to `skill-standardization`.
allowed-tools
Bash Read Write Edit Glob Grep WebFetch
compatibility
Reference implementation targets Claude Code (session hooks + skills + CLAUDE.md context injection). Requires bash, python3, git, and curl (for remote install). The Teacher/Student roles are model presets in `~/.claude/upskill.conf`, independent of the daily driver model set in Claude Code `settings.json`. The core building pipeline (worktree isolation, Ralph Loop, skill store) is harness-agnostic per upstream docs; porting to Codex/OpenClaw/Cursor needs an equivalent session-hook + context-injection layer.
upskill — Distill Agent Failures Into Validated Skills
Keyword: upskill · flash to pro · teacher student distillation · ralph loop skill validation
HKUDS/UpSkill (MIT) turns a cheap/weak
"Flash" model into a "Pro" performer without a model upgrade. When a session
fails, it captures the full context, has a strong Teacher model analyze
the failure and draft a skill, then validates that skill against the weak
Student model in a closed Ralph Loop (up to 3 rounds) before storing
it. Validated skills auto-inject into every future session via a CLAUDE.md
index (always in context) plus a full SKILL.md loaded on demand. On
Terminal-Bench 2.0, a Flash model + UpSkill (51.6% pass rate, $0.04/task)
beat the Pro model it was validated against (50.0%, $0.06/task) — a
41% lower cost result documented in tb_harbor_2.0/RESULTS.md.
This skill is the routing-first wrapper: it installs the tool, wires the
three roles (Daily / Teacher / Student), and walks the daily
capture → build → validate → serve loop.
When to use this skill
The user wants to install UpSkill or run any /upskill-* slash command
The user wants a cheap model ("Flash", Haiku, mini, DeepSeek-Flash) to
perform closer to a Pro model on recurring task categories
A session just failed and the user wants to turn that failure into a
reusable, validated skill instead of just retrying manually
The user wants to distill a successful session into a reusable skill
(not just failures — /upskill-build works on either)
The user asks how the Ralph Loop, Teacher/Student roles, or skill-store
serve modes (interactive vs auto) work
When not to use this skill
The user wants generic guidance on writing or standardizing a SKILL.md
from scratch → use write-a-skill or skill-standardization
The user wants a repo-local skill-quality ratcheting loop (freeze a
benchmark, mutate one change, keep/revert by score) for this jeo-skills
repo → use skill-autoresearch
The user wants a general model fine-tuning / RLHF pipeline → that changes
weights; UpSkill only prepends context, it never trains anything
The user is not on Claude Code and has no equivalent session-hook /
context-injection surface → see Porting
first; do not promise parity with an unadapted harness
The three roles
Role
Set in
Purpose
Daily model
Claude Code settings.json
Whatever the user runs day to day — untouched by UpSkill
Teacher
~/.claude/upskill.conf
Strong model — analyzes failures, drafts skills (e.g. claude-opus-4-7, deepseek-v4-pro[1m])
Student
~/.claude/upskill.conf
Weak model — every skill must be validated against it before storage (e.g. claude-haiku-4-5, deepseek-v4-flash)
Prerequisites
Requirement
Notes
Claude Code
Reference integration lives in cc-integration/
bash, python3, git
Required by hooks and the build pipeline
curl
Only for the remote one-line installer
API access to a Teacher and a Student model
Anthropic or DeepSeek recommended by upstream
Instructions
Step 1 — Install
# 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
This writes ~/.claude/{hooks,skills,upskill-store}/ and
~/.claude/upskill.conf. To update later, run /upskill-init inside Claude
Code — it re-runs the installer and migrates legacy config.
The Daily model is unaffected — it stays whatever Claude Code's own
settings.json selects. Run /upskill-model to view the current preset, or
bash ~/.claude/hooks/upskill-store.sh sync after a manual edit.
Step 3 — Enable building per project
/upskill-configure
Merges UserPromptSubmit, SessionStart, and SessionEnd hooks plus a
claudeMd pointer into .claude/settings.local.json for the current
project — additive, never overwrites existing hook entries.
Step 4 — Use the agent normally; skills build themselves
A SessionEnd hook captures a failed session (verify.sh present, non-zero
exit) and sets a pending flag. Next session start, Claude Code prints:
[upskill] ⚠ 1 pending failure(s) ready for building. Run /upskill-build to generate skills.
Run /upskill-build (works on failures and successes) and the pipeline
runs through 5 phases in an isolated git worktree — see
references/pipeline-and-ralph-loop.md
for the full Teacher → generate → Ralph-validate sequence.
Step 5 — Serve
Validated skills appear automatically in the agent's context via the global
~/.claude/upskill-store/CLAUDE.md index (~5 lines/skill). In interactive
mode (default), run /upskill-run to browse matches (★ = recommended) and
apply one. In auto mode, skills are keyword-matched on every prompt and
proactively suggested. Switch modes with /upskill-mode auto|interactive.
Most distillation approaches stop at "Teacher writes advice, hope it helps."
UpSkill closes the loop instead: the Student retries the task with the
draft skill applied, and if it still fails, the Teacher revises based on
"what went wrong even with guidance" — up to 3 rounds — discarding the skill
if it never passes. This calibrates every stored skill to what the Student
model can actually follow, not generic best practices. Architecture,
worktree isolation, and the 3-file skill format (Domain Knowledge /
Step-by-Step / Feedback-Lessons) are detailed in
references/pipeline-and-ralph-loop.md.
Porting to other agent harnesses
The core pipeline (build script, Ralph Loop, skill store) is harness-agnostic;
only the hook-integration and context-injection layer is Claude Code-specific.
Porting to Codex, OpenClaw, or Cursor needs: (1) before/after-session hook
equivalents, (2) a CLAUDE.md-equivalent auto-loaded context mechanism, (3)
slash-command equivalents, (4) worktree/sandbox isolation for Teacher/Student
runs. Do not claim full parity on an unadapted harness — state the gap.
Output format
When the user asks upskill for help, return a compact brief:
# 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
Examples
Example 1: First-time setup for a cost-conscious team
Install with the remote one-liner, set UPSKILL_TEACHER="claude-opus-4-7" and
UPSKILL_STUDENT="claude-haiku-4-5" in ~/.claude/upskill.conf, then run
/upskill-configure in each active project. The Daily model stays whatever
the team already uses in settings.json.
Example 2: A recurring CSV-parsing task keeps failing on Haiku
After a failure, /upskill-build picks the failed session, the Teacher
drafts a skill, and the Ralph Loop retries it against Haiku up to 3 rounds.
Once it passes, the skill auto-appears in the global CLAUDE.md index and is
offered via /upskill-run (interactive) or auto keyword-match next time a
similar CSV task starts.
Example 3: Distilling a successful session
/upskill-build is not failure-only — run it on a session that went well to
capture the working approach as a reusable, Student-validated skill before
the pattern is forgotten.
Best practices
Never let Teacher == Student. Validation is meaningless if the model
analyzing failures is the same one being validated against.
Build from successes too, not only failures — /upskill-build accepts
both, and good working patterns are just as worth distilling.
Trust the Ralph Loop's discard. A skill that fails all 3 rounds is
dropped by design — do not manually force-save an unvalidated draft.
Match serve mode to review appetite.interactive (default) keeps a
human in the loop per task; auto trades that for zero-friction matching.
Re-run /upskill-init after upstream releases instead of hand-patching
~/.claude/hooks/*.sh — it migrates legacy config safely.
Route pure skill-authoring or spec-compliance asks elsewhere — this
skill owns the distillation pipeline, not generic SKILL.md writing.
