upskill

upskill — エージェントの失敗を検証済みスキルに蒸留する

キーワード：upskill · flash to pro · teacher student distillation · ralph loop skill validation

HKUDS/UpSkill（MIT）は、モデルをアップグレードせずに、低コストで性能の低い「Flash」モデルを「Pro」相当のパフォーマンスに引き上げます。セッションが失敗すると、コンテキスト全体を記録し、強力なTeacherモデルが失敗を分析してスキルを作成します。その後、閉じたRalph Loop（最大3ラウンド）で、性能の低いStudentモデルに対してそのスキルを検証してから保存します。検証済みスキルは、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 に記録されています。

このスキルは、ルーティングを優先するラッパーです。ツールをインストールし、3つの役割（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 リポジトリ向けに、スキル品質を段階的に引き上げるループ（ベンチマークを固定し、変更を1つ加えて、スコアに応じて維持または差し戻し）を求めている場合 → skill-autoresearch を使用してください
• ユーザーが一般的なモデルのファインチューニング／RLHF パイプラインを求めている場合 → これは重みを変更します。UpSkill はコンテキストを先頭に追加するだけで、トレーニングは行いません
• ユーザーが Claude Code を使用しておらず、同等のセッションフック／コンテキスト挿入機能もない場合 → まず他のエージェントハーネスへの移植を参照してください。適応されていないハーネスでも同等に動作すると約束してはいけません

3つの役割

役割	設定場所	目的
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 を実行してください。

Step 3 — プロジェクトごとのビルドを有効にする

/upskill-configure

現在のプロジェクトの .claude/settings.local.json に、UserPromptSubmit、SessionStart、SessionEnd フックと claudeMd ポインターをマージします。追加のみを行い、既存のフックエントリーを上書きすることはありません。

Step 4 — エージェントを通常どおり使用する。スキルは自動で作成されます

SessionEnd フックが失敗したセッション（verify.sh が存在し、終了コードが 0 以外）を捕捉し、保留フラグを設定します。次のセッションの開始時に、Claude Code は次のように表示します。

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

/upskill-build を実行します（失敗時も成功時も機能します）。パイプラインは隔離された git worktree で 5 つのフェーズを実行します。Teacher → generate → Ralph-validate の全工程については、references/pipeline-and-ralph-loop.md を参照してください。

Step 5 — 提供する

検証済みのスキルは、グローバルな ~/.claude/upskill-store/CLAUDE.md インデックス（スキルあたり約 5 行）を通じて、エージェントのコンテキストに自動的に表示されます。interactive モード（デフォルト）では、/upskill-run を実行して候補を確認し（★ はおすすめ）、適用するスキルを選びます。auto モードでは、すべてのプロンプトでスキルがキーワード照合され、先回りして提案されます。/upskill-mode auto|interactive でモードを切り替えます。

Step 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 Loop

ほとんどの蒸留アプローチは、「Teacher がアドバイスを書き、役立つことを期待する」段階で止まります。UpSkill は代わりに、Student が下書きのスキルを適用してタスクを再試行することでループを完結させます。それでも失敗した場合は、Teacher が「ガイダンスがあっても何がうまくいかなかったか」に基づいて最大 3 ラウンドまで修正し、合格しないスキルは破棄します。これにより、一般的なベストプラクティスではなく、Student モデルが実際に従える内容に合わせて、保存されるすべてのスキルが調整されます。アーキテクチャ、worktree の分離、3 ファイルのスキル形式（Domain Knowledge／Step-by-Step／Feedback-Lessons）の詳細については、references/pipeline-and-ralph-loop.md を参照してください。

他のエージェントハーネスへの移植

コアパイプライン（ビルドスクリプト、Ralph Loop、スキルストア）はハーネスに依存しません。フック連携とコンテキスト注入のレイヤーのみが 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 Loop が Haiku で最大 3 ラウンドまで再試行します。合格すると、スキルはグローバルな CLAUDE.md インデックスに自動で追加され、次回、同様の CSV タスクが始まったときに /upskill-run（interactive）または自動キーワード照合で提示されます。

例 3: 成功したセッションの蒸留

/upskill-build は失敗時だけの機能ではありません。うまくいったセッションでも実行し、パターンを忘れる前に、機能した手法を再利用可能な Student 検証済みスキルとして記録します。

ベストプラクティス

1. Teacher と Student を同じにしないでください。 失敗を分析するモデルと、評価対象のモデルが同じでは、検証に意味がありません。
2. 失敗だけでなく、成功からも構築してください。/upskill-build はどちらも受け付けます。うまく機能するパターンも、抽出する価値は同じです。
3. Ralph Loop による破棄を信頼してください。3 ラウンドすべてで失敗したスキルは、仕様上破棄されます。検証されていないドラフトを手動で無理に保存しないでください。
4. レビューにかける手間に応じてサーブモードを選んでください。interactive（デフォルト）ではタスクごとに人間が介在し、auto では手間なくマッチングできる代わりに、その関与がなくなります。
5. 上流のリリース後は、~/.claude/hooks/*.sh を手動で修正せず、/upskill-init を再実行してください。レガシー設定を安全に移行できます。
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 を参照）