SkillOpt 詳細教學

一份足以讓團隊評估「能不能整合進我們的 agent pipeline」的精讀教學。 對應 paper：arXiv 2605.23904（Yang et al., 2026）

1. 專案定位

SkillOpt 是 Microsoft Research 推出的 agent skill 優化框架。它的核心信念可以用一句話表達：

與其調 model weights，不如把「skill」當成可訓練的純文字物件，用神經網路訓練的概念（epoch / batch / learning rate / validation gate）在 text space 迭代優化。

2. 安裝指南

2.1 需求

• Python 3.10+
• 至少一個 LLM API（Azure OpenAI 推薦 / OpenAI / Anthropic / Qwen vLLM）
• ALFWorld benchmark 需額外資料（alfworld-download）

2.2 標準安裝

 1git clone https://github.com/microsoft/SkillOpt.git
 2cd SkillOpt
 3python3.10 -m venv .venv  # 或 uv venv
 4source .venv/bin/activate
 5pip install -e .
 6
 7# 選用：ALFWorld
 8pip install -e ".[alfworld]"
 9alfworld-download
10
11# 選用：WebUI
12pip install -e ".[webui]"

2.3 設定 API 金鑰

1cp .env.example .env
2# 編輯 .env 填入你的 endpoint / API key
3set -a; source .env; set +a

最小可用組合（Azure OpenAI + API Key）：

1export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
2export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
3export AZURE_OPENAI_API_KEY="your-key"

也支援 AZURE_OPENAI_AUTH_MODE=azure_cli（無需金鑰）或 managed_identity。

2.4 資料準備

SkillOpt 不附 benchmark dataset，需自行準備 split 目錄：

1data/my_split/
2├── train/items.json
3├── val/items.json
4└── test/items.json

各 benchmark 的 schema 在 skillopt/envs/<benchmark>/dataloader.py。

3. 核心架構解析

SkillOpt 由「ReflACT (Reflective Agent Tuning)」六階段 pipeline 構成。

flowchart TD
    A[Training Data Split] --> B[1. Rollout
envs/<benchmark>/rollout.py]
    B --> C[2. Reflect
gradient/reflect.py]
    C --> D[3. Aggregate
gradient/aggregate.py]
    D --> E[4. Select
optimizer/clip.py rank_and_select]
    E --> F[5. Update
optimizer/skill.py apply_edit]
    F --> G[6. Evaluate
evaluation/gate.py]
    G -->|accept| H[best_skill.md]
    G -->|reject| I[rollback to previous skill]
    H --> J[Slow Update
optimizer/slow_update.py]
    J --> K[Meta Skill
optimizer/meta_skill.py]
    K --> B
    M[Model Backend Router
model/router.py] -.->|LLM calls| B
    M -.-> C
    M -.-> D

3.1 六階段對應

額外的「跨 epoch」模組：

• Slow Update（optimizer/slow_update.py, 393 行）— 用 <!-- SLOW_UPDATE_START --> … <!-- SLOW_UPDATE_END --> 標記保護長期記憶區域，避免被短期 patch 蓋掉。
• Meta Skill（optimizer/meta_skill.py, 87 行）— 把跨 epoch 的「學會的 meta-pattern」抽出。
• LR Autonomous（optimizer/lr_autonomous.py, 108 行）— 自主調整 edit step size，類似 adaptive learning rate。

3.2 Model Backend 抽象

skillopt/model/router.py 統一路由到：

• azure_openai.py（31.9KB）— Azure OpenAI（含 Azure CLI / Managed Identity 兩種 auth）
• claude_backend.py（17.6KB）— Anthropic API
• codex_backend.py（20.0KB）— OpenAI Codex CLI
• codex_harness.py（37.3KB）— claude-code CLI / codex CLI 子進程封裝
• qwen_backend.py（9.3KB）— 本地 vLLM

engine/trainer.py 是中樞（1912 行）— 把 6 階段串起來、管 batch / epoch / checkpoint / resume。

3.3 Edit 操作集合

optimizer/skill.py 定義 4 種 edit op：

• append — 在文件尾部加
• insert_after — 在指定 target 後插入
• replace — 整段替換
• 還有 update_modes.py 控制 partial vs full rewrite

所有 edit 都會跳過 SLOW_UPDATE 保護區域，且自動 strip 標記避免重複。

4. Helper Scripts 詳細用法

4.1 訓練（scripts/train.py, 494 行）

 1python scripts/train.py \
 2    --config configs/searchqa/default.yaml \
 3    --split_dir /path/to/searchqa_split \
 4    --azure_openai_endpoint https://your-resource.openai.azure.com/ \
 5    --optimizer_model gpt-5.5 \
 6    --target_model gpt-5.5 \
 7    --num_epochs 4 \
 8    --batch_size 40 \
 9    --workers 8 \
10    --out_root outputs/my_run

重要參數：

4.2 純評估（scripts/eval_only.py, 451 行）

1python scripts/eval_only.py \
2  --config configs/searchqa/default.yaml \
3  --skill outputs/my_run/best_skill.md \
4  --split valid_unseen \
5  --split_dir /path/to/searchqa_split

--split 可選：train / valid_seen / valid_unseen / all。

4.3 Benchmark Wrapper（scripts/run_*.sh）

提供 3 個現成 wrapper：

• scripts/run_alfworld.sh（60 行）
• scripts/run_searchqa.sh（40 行）
• scripts/run_spreadsheetbench.sh（39 行）

每個都假設你已準備好對應 split 目錄並設好環境變數。

4.4 WebUI

1python -m skillopt_webui.app --port 7860 --host 0.0.0.0
2# 加 --share 開 Gradio public link（注意安全）

5. 應用場景

5.1 SkillOpt 真正擅長的 5 種情境

1. Agent prompt 自動演化：有 ground-truth 評估訊號（accuracy / F1 / pass-rate），想自動找出最佳 system prompt / few-shot。
2. Domain skill 萃取：把 expert demonstration 蒸餾成可分享的 markdown，比 fine-tune 更輕量。
3. 多模型 portability：產出的 best_skill.md 可在 Azure OpenAI / Claude / Qwen 之間移植測試。
4. Tool-use 策略優化：OfficeQA / SpreadsheetBench 都是 tool-augmented 場景，SkillOpt 學到的是「何時呼叫什麼工具」。
5. 跨 session 經驗累積：Slow Update + Meta Skill 設計就是為了「不要每個 epoch 都從零學起」。

5.2 不建議使用 SkillOpt 的情境

• 沒有自動化 reward signal（純人類偏好）→ 改用 RLHF / DPO。
• 需要修改模型行為深層偏見 → fine-tune / RLHF 更有效。
• Domain 沒有可量化的 success criteria → 結果不可信。

5.3 Apotek 內部適配草圖（評估用）

6. 資安掃描報告

範圍：scripts/、skillopt/（總計約 100+ Python 檔，3000+ 行核心邏輯） 工具：grep -rn -E "eval|exec|subprocess|shell=True|os.system|pickle|api_key|password|token"

6.1 紅燈（🔴 高風險）

1. skillopt/envs/spreadsheetbench/react_agent.py:257 使用 subprocess.run(shell=True) 執行 LLM 生成的 bash 指令

1proc = subprocess.run(cmd, shell=True, capture_output=True, ...)

• 風險：cmd 來自 LLM 輸出。雖然限定在 work_dir（單一 ReAct agent 工作目錄），但若被 prompt injection 控制可在 host 上執行任意指令。
• 影響面：執行 run_spreadsheetbench.sh 才會觸發；其他 5 個 benchmark 不受影響。
• 緩解：必須在隔離容器（docker / podman）或 firejail / nsjail 內執行 SpreadsheetBench。生產環境禁止裸跑。

2. skillopt/envs/spreadsheetbench/executor.py 直接執行 LLM 生成的 Python 程式碼

1script = RUNNER_TEMPLATE.format(user_code_indented=indented)
2proc = subprocess.run([sys.executable, tmp], ...)

• 風險：把 LLM 產出的 code 寫到 tmpfile 後用 sys.executable 跑。Sandbox 僅靠 timeout（120s）。
• 緩解：同上 — 容器隔離 + 限制檔案系統權限 + 限網。

6.2 黃燈（🟡 中風險）

3. 多個 backend 透過 subprocess.run 呼叫 CLI（codex / claude-code）

• claude_backend.py:261、codex_backend.py:327、codex_harness.py:699/912
• 屬於合理設計（封裝 CLI），但 cmd + [prompt_for_cli] 把使用者輸入 / LLM 輸出當 argv 傳。沒用 shell=True，相對安全，但仍要注意 prompt_for_cli 不會被 shell-meta 解析（list 形式正確）。
• 建議：定期 audit 這幾個 backend，確保未引入 shell=True 回歸。

4. azure_openai.py:259 透過 subprocess.check_output 呼叫 az CLI 取 token

• 用於 AZURE_OPENAI_AUTH_MODE=azure_cli。argv 形式，安全。
• 建議：CI / 自動化環境改用 managed_identity 模式。

5. WebUI --share 選項會建立 Gradio 公開連結

• python -m skillopt_webui.app --share 會把本機 WebUI 暴露到公網 tunnel。內含訓練監控資訊（可能含 prompt / 部分 trajectory）。
• 建議：團隊環境永遠不要加 --share，僅限本機 / VPN 內網。

6.3 綠燈（🟢 低風險）

• API 金鑰一律走環境變數 / .env，未發現 hard-coded secret。
• .env.example 提供 3 種 auth 模式（API key / Azure CLI / Managed Identity），鼓勵不存 key 的方案。
• 無 pickle.load(untrusted) / eval(user_input) / os.system 直接拼接 user input 模式。
• MIT License + Microsoft SECURITY.md 明確的揭露管道。

6.4 部署建議

7. FAQ

Q1：跟 GEPA / EvoSkill / Trace2Skill 有什麼差別？ A：見 Issue #12 — SkillOpt 用 GPT-5.5 當 optimizer，幾個 baseline 是 self-contained。Validation gate + slow update 是 SkillOpt 獨有設計。

Q2：可以不用 Azure OpenAI 嗎？ A：可以。設定 OPENAI_API_KEY 或 ANTHROPIC_API_KEY，或本地 QWEN_CHAT_BASE_URL（vLLM）。但 paper 數據是用 Azure GPT-5.5 跑的。

Q3：訓練要多久？ A：依 benchmark 而異。SearchQA 4 epoch / 40 batch / 8 workers 估計幾小時到一天（依 API rate limit）。會消耗大量 API token。

Q4：能 resume 嗎？ A：可以。重複跑同一指令會讀 outputs/<run_name>/runtime_state.json 自動續跑。

Q5：產出的 best_skill.md 怎麼用？ A：把它當系統 prompt / 預先載入的 context 注入到目標 agent。eval_only.py 提供測試入口。

Q6：Benchmark dataset 在哪？ A：不附。Issue #10 / #14 都在要求 release，目前需自備或自寫 dataloader。

8. 進階技巧

1. 混用 optimizer / target 模型：--optimizer_model gpt-5.5 --target_model qwen3.5-4b — 用強模型優化弱模型的 skill。
2. 自寫 env：照 skillopt/envs/_template/ 補 4 個檔（dataloader / rollout / scorer / config）即可加新 benchmark。
3. 調 --rewrite_reasoning_effort：較高的 reasoning effort 可在 patch 階段產生更精準的 edit，代價是 token 成本上升。
4. 觀察 outputs/<run>/steps/step_XXXX/：每步的 patches / eval results 都會留下，是 debug 的金礦。
5. Slow update 區域：在 base skill markdown 中手動加 <!-- SLOW_UPDATE_START --> … <!-- SLOW_UPDATE_END --> 可保護「人類手動寫死、不准被 LLM 動」的內容。

9. 整合進其他工作流

9.1 與 paper-qa-lite（Layer 10）

把 SkillOpt paper + 此 tutorial 一起餵 paper-qa-lite，可快速詢問「ReflACT 第 X 階段在做什麼」。

9.2 與 graphify（Layer 4）

graphify init 對 SkillOpt 原始碼跑一遍，可拿到 module call graph，方便理解 1912 行的 engine/trainer.py。

9.3 與 Apotek RANK pipeline

潛在整合 stub（非立即可上線）：

1RANK LLM hop (cell-line annotation)
2  → 抽出 prompt → skill_v0.md
3  → SkillOpt train (需準備 200+ annotation ground-truth split)
4  → best_skill.md → 替換回 RANK pipeline

風險：annotation ground-truth 收集成本高、API token 預算需評估。

10. 重點摘要 Checklist

• 核心定位：text-space optimizer for frozen LLM agent skills，非 fine-tune。
• 產出物：best_skill.md（可移植 markdown），不是模型 checkpoint。
• 6 階段 ReflACT pipeline：Rollout / Reflect / Aggregate / Select / Update / Evaluate。
• 支援 6 個 benchmark：但 dataset 不附，需自備。
• 多 backend：Azure OpenAI（首選）/ OpenAI / Claude / Qwen vLLM / Codex CLI / claude-code CLI。
• 可 resume：repeat 相同指令自動續跑。
• 資安等級：🟡 中（SpreadsheetBench env 有 shell=True + LLM code exec，需 sandbox）。
• License：MIT，企業可用。
• 成熟度：v0.1.0，主動維護（每日 commit），但 release 與 dataset 尚未齊備。

11. 進一步閱讀

• 論文：arXiv 2605.23904 — SkillOpt: Executive Strategy for Self-Evolving Agent Skills
• Project Page：https://microsoft.github.io/SkillOpt/
• Demo Video：YouTube
• 比較對象：GEPA、Trace2Skill、EvoSkill（見 Issue #12 討論）
• 相關概念：ReflACT, Reflexion, Self-Refine, Self-Discover
• Apotek 內部關聯：docs/superpowers/specs/（若日後評估整合）