evolve-skill-from-tracesEvolve SKILL.md files from agent execution traces using a three-stage pipeline: trajectory collection from observed runs, parallel multi-agent patch proposal for error and success analysis, and conflict-free consolidation of overlapping edits via prevalence-weighting. Based on the Trace2Skill methodology.
Independent GitHub snapshot · Automated classification · Original documentation governs
透過三階段管線將原始代理執行軌跡轉為已驗之 SKILL.md：軌跡採集、並行多代理之 patch 提議、無衝突之合併。此技架接所觀察之代理行為與所文檔之程，化成功執行為可復現之技能。
traces — 代理執行日誌或會話抄本之集（建議至少 10 次成功運行）target_skill — 待演既有 SKILL.md 之路徑，或 "new" 以自頭抽技能analyst_count — 並行分析者代理之數（預設：4）held_out_ratio — 保留供驗證、不用於起草之軌跡比（預設：0.2）集代理會話日誌、工具呼叫序列或演示目標行為之對話抄本。濾標為成功之運行。歸一為標準軌跡格式：帶時戳之 (state、action、outcome) 三元組之序列。
trace_entry:
state: <context before the action>
action: <tool call, command, or decision made>
outcome: <result, output, or state change>
timestamp: <ISO 8601>
held_out_ratio（預設 20%）以供步驟七之驗證，餘供步驟二至六# Example: count available traces and compute partition
total_traces=$(ls traces/*.json | wc -l)
held_out=$(echo "$total_traces * 0.2 / 1" | bc)
drafting=$((total_traces - held_out))
echo "Drafting: $drafting traces, Held-out: $held_out traces"
預期： 歸一之軌跡集分為起草（80%）與保留（20%）子集。每軌跡項含 state、action、outcome、timestamp 欄。
失敗時： 若可得之成功軌跡少於 10，採更多前勿進。小軌跡集生過擬之技能，於新輸入上敗。若軌跡缺時戳，改以序數賦之。
以結果模式群歸一之軌跡。識不變之核（所有成功軌跡皆有之步）與變之分支（跨運行異之步）。不變之核成技能程之骨架。
invariant_core:
- action: "read_input_file"
frequency: 100%
- action: "validate_schema"
frequency: 100%
- action: "transform_data"
frequency: 100%
variant_branches:
- action: "retry_on_timeout"
frequency: 35%
condition: "network latency > 2s"
- action: "fallback_to_cache"
frequency: 15%
condition: "API returns 503"
預期： 不變核動作（所有成功軌跡皆有）與變之分支（條件性，見於子集）之明分。每變之分支有頻計與觸發條件。
失敗時： 若無不變之核現（軌跡過異），則目標行為或實為多獨立技能。以結果類型分軌跡為連貫子組並分別處之。
自不變核生初 SKILL.md，含 frontmatter、When to Use（由跨軌跡入口條件導之）、Inputs（跨運行變之參數）、以一不變動作一步之 Procedure 節。
# Scaffold the skeleton if creating a new skill
mkdir -p skills/<skill-name>/
# Skeleton structure
## When to Use
- <derived from common entry conditions>
## Inputs
- **Required**: <parameters present in all traces>
- **Optional**: <parameters present in some traces>
## Procedure
### Step N: <invariant action label>
<most common implementation from traces>
**Expected:** <most common success outcome>
**On failure:** <placeholder -- refined in Steps 4-6>
預期： 語法有效之 SKILL.md 骨架，含 frontmatter、When to Use、Inputs 及含一不變核動作一步之 Procedure 節。Expected 區反所觀察結果；On failure 區為占位。
失敗時： 若骨架於加變之分支前逾 500 行，不變之核過細。將常共現之相鄰動作合為單步。目標 5-10 程步。
啟 N 分析者代理（建議 4-6），各以異之分析視角對草稿骨架審全軌跡集。各代理出結構化 patch：節、舊文、新文、理由。
予各分析者一視角：
| 分析者 | 視角 | 焦點 |
|---|---|---|
| 1 | Correctness（正確） | 骨架是否捕所有成功路？是否缺不變步？ |
| 2 | Efficiency（效率） | 是否有冗步？步是否可合或並行？ |
| 3 | Robustness（韌性） | 何敗模式未處？On failure 區當含何？ |
| 4 | Edge Cases（邊緣情） | 何變之分支當成條件步或陷阱？ |
| 5（選擇性） | Clarity（清） | 各步是否明？代理可機械循之？ |
| 6（選擇性） | Generalizability（通化） | 是否有應抽之軌跡特定產物？ |
各分析者代理收：
各分析者返結構化 patch 清單：
patch:
analyst: "robustness"
section: "Procedure > Step 3"
old_text: "**On failure:** <placeholder>"
new_text: "**On failure:** If the API returns 503, wait 5 seconds and retry up to 3 times. If retries are exhausted, fall back to the cached response from the previous successful run."
rationale: "Traces #4, #7, #12 show 503 errors resolved by retry. Trace #15 shows cache fallback when retries fail."
supporting_traces: [4, 7, 12, 15]
預期： 各分析者返 3-10 結構化 patch 含節引、舊/新文、理由及支援軌跡 ID。所有 patch 集於一 patch 集。
失敗時： 若分析者無 patch 返，其視角或不適於此技能。此可接——非每視角皆顯問題。若分析者返含糊 patch 而無軌跡引，拒之並以須具體 supporting_traces 之要求再問。
比步驟四之所有 patch 之重疊編輯。將每對重疊 patch 分為三類之一。
| 衝突類 | 定義 | 解決 |
|---|---|---|
| Compatible（相容） | 異節，無疊 | 直合 |
| Complementary（互補） | 同節，疊加（皆加內容，無矛盾） | 合文 |
| Contradictory（相矛） | 同節，互斥（一加 X，一移 X 或改加 Y） | 於步驟六解決 |
conflict_report:
total_patches: 24
compatible: 18
complementary: 4
contradictory: 2
contradictions:
- section: "Procedure > Step 5"
patch_a: {analyst: "efficiency", action: "remove step"}
patch_b: {analyst: "robustness", action: "add retry logic"}
supporting_traces_a: [2, 8, 11]
supporting_traces_b: [4, 7, 12, 15]
預期： 衝突報告列所有 patch 對、其分類，且於矛盾者列各方之支援軌跡計。
失敗時： 若分類含糊（patch 於同節既加且改文），分為二 patch：一加，一改。再分類較小之 patch。
以三層解決策將所有 patch 合為單一 SKILL.md。
argumentation 技評何 patch 更服於技能所述之目的consolidation_log:
applied_directly: 18
combined: 4
resolved_by_prevalence: 1
resolved_by_argumentation: 1
rejected_alternatives_documented: 2
合後，驗所成 SKILL.md：
預期： 納所有分析者 patch 之單一合之 SKILL.md。矛盾以文檔之理由解決。每矛盾之遭拒替代顯為陷阱或註。
失敗時： 若合生內部不一致之文檔（如 Step 3 假檔存而 Step 2 遭效率 patch 移），回衝突之編輯並於該節保原骨架文。旗標不一致以人工審。
心對保留軌跡（步驟一所保之 20%）行合之技能。驗 Expected/On failure 區配技能未見之軌跡中所觀察結果。
validation_results:
held_out_traces: 5
full_match: 4
partial_match: 1
no_match: 0
mismatches:
- trace_id: 23
step: 4
expected: "API returns 200"
actual: "API returns 429 (rate limited)"
action: "Add rate-limit handling to On failure block"
create-skill 建目錄、登記項、symlinkevolve-skill 升版與譯同步# Final validation: line count
lines=$(wc -l < skills/<skill-name>/SKILL.md)
[ "$lines" -le 500 ] && echo "OK ($lines lines)" || echo "FAIL: $lines lines > 500"
預期： 至少 80% 之保留軌跡端至端合技能程。技能已於 skills/_registry.yml 以正確元數據登記。
失敗時： 若驗敗（>20% 不合），技能已過擬起草軌跡。將不合軌跡加入起草集並自步驟二再行。若二迭代後仍敗，行為或過變以至不能為單一技能——考慮以結果類型分為多技能。
evolve-skill — 較簡之人導演化（互補：軌跡不可得時用）create-skill — 為新抽尚不存之技能；於步驟七登記所用review-skill-format — 合之後之驗證以確 agentskills.io 合規argumentation — 於步驟六當頻次平時解相矛 patch 所用verify-agent-output — patch 提議之證據軌跡；於步驟四驗分析者輸出