AI 에이전트가 쓰는 '스킬 문서'가 실제로 도움이 되는 이유는 사실을 알려주는 게 아니라 행동을 안정시키기 때문이다
arXiv:2608.140362026-08-13
Demystifying Agent Skills: Why They Work-Until They Don't
AI 에이전트가 쓰는 '스킬 문서'가 실제로 도움이 되는 이유는 사실을 알려주는 게 아니라 행동을 안정시키기 때문이다
이 연구는 LLM 에이전트에게 주어지는 SKILL.md 같은 '스킬' 문서가 왜, 언제, 어떻게 도움이 되고 실패하는지를 8,135건의 실행 기록과 240개 트라젝토리 분석으로 파헤친다. 결론은 스킬이 몰랐던 정보를 알려주는 게 아니라 반복되는 설정·명령·검증 절차를 안정시키는 '절차적 앵커' 역할을 한다는 것이다. 동시에 스킬 저장소가 커질수록 실제로 맞는 스킬을 찾아 쓰는 정밀도는 급격히 떨어지지만, 그렇다고 다운스트림 성공률이 함께 떨어지지는 않는다는 점도 보였다.
METAL MEDIA 해설 도표
스킬 vs Workflow Memory vs Raw: 같은 경험, 다른 표현 방식이 만드는 차이
증거 상태측정 결과가 보고됨
1. 원본 실행 기록 수집동일 과제에 대해 성공·실패한 실행 기록을 고정된 Docker 환경에서 균형 있게 수집해 공통 트레이스 풀을 구성한다
2. 세 가지 표현으로 증류같은 트레이스 풀을 가공 없이(Raw), 정리된 절차 기록(Workflow Memory), 표준화된 SKILL.md(Skill)로 각각 만든다
3. 동일 조건에서 재실행동일한 과제와 프로토콜로 세 조건을 실행하고 성공률과 트라젝토리를 수집한다
4. 대조 분류(taxonomy) 분석세 조건의 실행 결과를 짝지어(paired triple) 사람과 LLM이 함께 12개 세부 유형으로 라벨링해 무엇이 달라졌는지 규명한다
5. 검색 난이도 실험스킬 풀 크기와 방해 요소를 바꿔가며 임베딩 검색, 명시적 선택, 실제 실행 세 방식으로 검색-실행 관계를 별도로 측정한다
METAL MEDIA이 원문을 바탕으로 재구성한 해설 도표이며, 논문 저자의 원문 figure가 아닙니다.
무엇을 했나
같은 원본 실행 기록(트라젝토리)을 가공하지 않은 상태(Raw), 정리된 절차 기록(Workflow Memory), 표준화된 SKILL.md 문서(Skill) 세 가지 형태로 만들어 동일한 과제에 투입하고 성공률을 비교했다
성공/실패 실행 기록 240개를 사람이 직접 읽고 코드화(open coding)한 뒤, 238개의 유효한 라벨을 뽑아 3개 대분류·12개 세부 유형의 분류체계(taxonomy)로 정리했으며, 사람 검증에서 LLM 분류와 95.8% 일치(Cohen's κ=0.952)를 확인했다
Codex+GPT-5.3-Codex, Gemini CLI+Gemini-3.1-Pro-Preview 등 서로 다른 에이전트 프레임워크·모델 조합으로 같은 실험을 반복해 결과가 특정 모델에만 국한되지 않는지 확인했다
스킬 후보 풀의 크기(5개~100개)와 헷갈리는 방해 요소(distractor) 종류를 바꿔가며 임베딩 기반 검색, 명시적 에이전트 선택, 실제 실행 세 가지 방식으로 스킬 검색 성능을 따로따로 측정했다
Figure 1: Experimental pipelines. Top: skill versus procedural memory. We execute each task in a fixed Docker environment, collect successful and failed trajectories, and form a fixed-budget composition grid. The same trace pool is distilled either into Workflow Memory or into a reusable SKILL.md, which are then evaluated on matched tasks under the same protocol. Bottom: skill retrieval. Each task is paired with a candidate pool containing its ground-truth skill and k−1 real distractors (random, similar, or dissimilar). Matched pools are evaluated independently in three procedures: (A) embedding-based ranking without task execution, (B) explicit agent selection without Docker execution or verification, and (C) full-pool real execution with skill-use parsing after task verification. Outputs from (A) and (B) are not passed to (C).
Table 1: Task success rates for Workflow Memory and Skill injection across trajectory mixtures. Gray rows denote Raw baselines. Green, red, and unshaded cells indicate values above, below, and equal to the corresponding Raw baseline, respectively; bold marks the row-wise maximum across mixture settings. Mixture labels denote the numbers of successful (s) and failed (f) source trajectories. Terminal-Bench-Pro rates use 130 trials per condition, with infrastructure or verifier errors counted as failures.
Agent + Model
Trajectory Mix
Terminal-Bench-2
SkillsBench
Terminal-Bench-Pro
Workflow
Skill
Workflow
Skill
Workflow
Skill
Codex + GPT-5.3-Codex Raw
0.5935
0.5083
0.5394
Codex GPT-5.3-Codex
5s0f
0.4452
0.7548
0.5250
0.7250
0.7333
0.7455
4s1f
0.4000
0.7290
0.5667
0.6167
0.7333
0.7939
3s2f
0.4194
0.7806
0.6417
0.6250
0.6970
0.7333
2s3f
0.3677
0.6839
0.6083
0.7083
0.6667
0.6667
1s4f
0.2710
0.7097
0.5167
0.6167
0.6121
0.5818
0s5f
0.2839
0.5161
0.5833
0.4500
0.4788
0.4303
Gemini CLI + Gemini-3.1-Pro-Preview Raw
0.5000
0.4762
0.5615
Gemini CLI Gemini-3.1-Pro-Preview
5s0f
0.6231
0.7923
0.5524
0.7429
0.5308
0.6692
4s1f
0.5308
0.7615
0.5238
0.6190
0.6923
0.6308
3s2f
0.6462
0.7462
0.5619
0.6667
0.6462
0.5462
2s3f
0.6000
0.7000
0.5524
0.6762
0.6846
0.5077
1s4f
0.5846
0.6923
0.4857
0.6000
0.5923
0.5692
0s5f
0.5231
0.4769
0.4286
0.4095
0.4769
0.4615
(b) Three-experiment skill-retrieval evaluation.
Table 2: Mechanism labels used to characterize how injected prior experience affects execution.
Mechanism
Meaning
procedural_anchor
The artifact gives a usable procedure, ordering, checklist, tool sequence, or verification plan.
knowledge_ injection
The artifact supplies concrete domain knowledge that the agent otherwise lacked.
failure_warning
The artifact warns about a pitfall that the agent avoids.
none
The artifact is not used in a meaningful way.
counterproductive
The artifact misleads the agent or makes the run worse.
Figure 2: Taxonomy label distribution across trajectory mixtures and experimental arms. Stacked bars show trajectory-level labels for Raw, Workflow Memory, and Skill across the six source-trajectory mixtures from 5s0f to 0s5f. Labels are grouped into three high-level categories; per-mode percentages are reported in Appendix Table 11.
Table 3: Human validation of the taxonomy construction pipeline. The first stage checks whether raw labels are supported by their source trajectories; the second independently maps those labels to the 12 canonical modes.
Validation stage
Evaluation units
Result
Trajectory grounding
714 checks (238 labels × 3 trajectories)
All labels confirmed
Taxonomy aggregation
238 valid unique labels
95.8% exact; Cohen’s κ=0.952
Figure 3: Skill retrieval and execution-time skill use on SkillsBench. Left: precision for the two offline diagnostics. Right: parsed actual-use precision (solid lines) and downstream success (dashed lines) for Arm 3. Curves average over random, similar, and dissimilar pool regimes; outputs are not passed between experiments.
Table 4: Effect of pool composition and size on SkillsBench. Entries report percentages for the indicated retrieval arm, pool composition, and pool size. Arms 2 and 3 are arithmetic means over the reported agent–model pairings. Full recall and F1 values are given in Appendix Table 15.
Pool / metric
Skill-pool size k
5
10
20
50
100
Random
Arm 1 P
97.7
95.5
95.5
92.0
84.1
Arm 2 P
78.1
77.9
82.1
76.5
69.8
Arm 3 P
25.9
23.2
19.5
8.6
4.4
Arm 3 Succ.
31.8
36.8
40.1
36.3
41.9
Similar
Arm 1 P
70.5
63.6
60.2
56.8
53.4
Arm 2 P
53.1
52.9
47.1
48.6
43.7
Arm 3 P
34.5
22.3
15.7
7.3
3.7
Arm 3 Succ.
41.7
39.6
39.2
39.5
39.6
Dissimilar
Arm 1 P
96.6
96.6
96.6
94.3
93.2
Arm 2 P
78.9
81.6
82.6
78.4
77.8
Arm 3 P
28.6
19.2
9.0
4.4
1.7
Arm 3 Succ.
35.7
36.9
33.7
38.8
36.4
(b) Arm 3 skill-use precision and downstream success.
Table 5: Experimental arms in the contrastive trajectory analysis.
Arm
Injected prior experience
Purpose
Raw
No injected prior trajectory or skill
Baseline behavior of the agent on the task.
Workflow memory
Cleaned prior workflows are appended as procedural memory
Tests whether direct trajectory-like procedural memory improves execution.
Skill
The same prior workflows are distilled into a standardized reusable skill
Tests whether compact skill representation improves over direct workflow memory.
Figure 4: Cross-framework transfer of procedural experience. Prior-experience artifacts constructed in one agent framework are evaluated in another. Dashed lines indicate the target framework’s Raw baseline.
Table 6: Input artifacts used by the taxonomy pipeline.
Stores the terminal/tool-use trajectory and the agent’s reasoning-visible interaction record.
Task instruction
Defines the task objective and, for workflow-memory arms, may include injected workflow content.
Skill artifact
Stores the injected skill used in the skill arm.
Task-side files
Used only as contextual artifacts when present; the main taxonomy labels are based on execution trajectories and verifier outcomes.
Figure 5: Effect of outcome labels during skill creation. Panels compare skills created with outcome labels visible (normal) or withheld (no-hint) across trajectory mixtures and benchmarks. Dashed lines indicate the corresponding Raw baselines. Terminal-Bench-Pro entries use 130 trials per condition; missing or infrastructure-error trials count as failures.
Table 7: Coverage statistics after manifest construction and artifact linking.
Dimension
Count
Terminal-Bench 2.0 trials
3,254
Terminal-Bench-Pro trials
2,993
SkillsBench trials
1,888
Raw-arm trials
1,883
Workflow-memory trials
2,658
Skill-arm trials
3,594
Successful trials
4,541
Failed trials
3,594
Records with available agent transcript
7,837
Records with available task instruction
6,210
Skill-arm records with linked skill artifact
3,570
Table 8: Paired triple sample used for contrastive taxonomy labeling.
Split
Count
SkillsBench triples
144
Terminal-Bench 2.0 triples
186
Terminal-Bench-Pro triples
198
Triples per mixture setting
88
Total triples
528
Table 9: Oracle-status success rates across the three execution arms.
Arm
Success / total
Success rate
Raw
312 / 528
59.1%
Workflow memory
295 / 528
55.9%
Skill
327 / 528
61.9%
Table 10: Paired success-rate deltas between execution arms.
Comparison
Mean paired delta
95% bootstrap CI
WM vs Raw
−0.0322
[−0.0814,+0.0208]
Skill vs Raw
+0.0284
[−0.0227,+0.0795]
Skill vs WM
+0.0606
[+0.0076,+0.1136]
Table 11: Contrastive skill-use taxonomy over 528 paired triples. SC abbreviates Skill-use Category, the top-level taxonomy label assigned to a trajectory; each SC groups the fine-grained modes listed in the table. Percentages are computed within each arm over the same paired-triple sample. SC1 denotes successful procedural anchoring, SC2 execution-layer and verification failures, and SC3 invocation, applicability, and boundary failures.
SC
Mode
Raw
WF
Skill
SC1
skill_guided_success
10.4%
0.4%
61.6%
SC1
workflow_guided_success
0.0%
54.5%
0.0%
SC1
autonomous_clean_success
48.7%
0.8%
0.2%
SC2
environment_infrastructure_failure
5.3%
1.7%
0.2%
SC2
output_format_schema_mismatch
7.4%
3.8%
3.2%
SC2
background_service_lifecycle_failure
2.7%
2.5%
0.8%
SC2
shell_code_corruption
1.1%
1.9%
0.2%
SC2
algorithmic_logic_error
8.3%
11.0%
7.4%
SC2
static_verification_without_runtime
12.5%
12.5%
11.7%
SC3
timeout_budget_exhaustion
1.7%
10.6%
4.4%
SC3
skill_guidance_misapplied_or_ignored
0.8%
0.4%
10.0%
SC3
capability_or_safety_limit
1.1%
0.0%
0.4%
Table 12: Lightweight compact procedural baselines on selected Terminal-Bench-2 tasks. Entries report downstream success for Raw, short-plan, test-first, Workflow Memory, and Skill conditions over 26 tasks with five trials per task.
Condition
Source
Success / total
Success rate
Raw
None
65 / 130
50.0%
Short plan
Task instruction
62 / 130
47.7%
Test-first template
Workflow
77 / 130
59.2%
Workflow Memory
Workflow
81 / 130
62.3%
Skill
Workflow
103 / 130
79.2%
Table 13: Matched success and token-cost comparison. Entries are computed on the 83-task intersection with equal task weighting. Token counts are per-task averages reported in thousands (K); “pp” denotes percentage points.
Absolute metrics on the matched 83-task intersection
Representation
Success
Input
Output
Total
Δ succ. vs Raw
Cost profile
Raw trajectories
64.1%
541.5K
14.2K
555.7K
–
Full prior traces provide broad evidence but carry the largest context load.
Workflow Memory
64.8%
417.9K
8.3K
426.2K
+0.7 pp
Most token-efficient representation after cleaning trajectory noise.
Skill
69.6%
511.7K
9.8K
521.5K
+5.5 pp
Highest success rate, with lower token use than Raw but higher token use than Workflow Memory.
Pairwise trade-offs
Comparison
Δ success
Δ input
Δ output
Δ total
Direction
Interpretation
Workflow Memory vs Raw
+0.7 pp
-123.6K
-5.9K
-129.5K
cheaper
Workflow Memory substantially reduces token cost with nearly unchanged success.
Skill vs Raw
+5.5 pp
-29.8K
-4.4K
-34.2K
better and cheaper
Skill improves success while still reducing token use relative to Raw trajectories.
Skill vs Workflow Memory
+4.8 pp
+93.8K
+1.5K
+95.3K
better but costlier
Skill trades additional context for stronger execution performance.
Table 14: Complete Arm 1 embedding-retrieval results on SkillsBench. Entries report ranking metrics from Qwen3-Embedding-0.6B using task–skill-description similarity. Top-5 is omitted for k=5 because it covers the full candidate pool.
Pool
k
Top-1
Top-3
Top-5
P
P
R
F1
P
R
F1
Random
5
97.7
33.0
98.9
49.4
–
–
–
10
95.5
32.6
97.7
48.9
19.5
97.7
32.6
20
95.5
32.2
96.6
48.3
19.5
97.7
32.6
50
92.0
32.2
96.6
48.3
19.5
97.7
32.6
100
84.1
30.7
92.0
46.0
19.1
95.5
31.8
Similar
5
70.5
31.8
95.5
47.7
–
–
–
10
63.6
29.2
87.5
43.8
19.3
96.6
32.2
20
60.2
26.9
80.7
40.3
17.5
87.5
29.2
50
56.8
24.2
72.7
36.4
16.4
81.8
27.3
100
53.4
22.7
68.2
34.1
15.7
78.4
26.1
Dissimilar
5
96.6
33.0
98.9
49.4
–
–
–
10
96.6
32.2
96.6
48.3
19.8
98.9
33.0
20
96.6
32.2
96.6
48.3
19.5
97.7
32.6
50
94.3
32.2
96.6
48.3
19.5
97.7
32.6
100
93.2
32.2
96.6
48.3
19.3
96.6
32.2
Table 15: Complete Arm 2 and Arm 3 retrieval results on SkillsBench. Rows correspond to agent–model, distractor regime, and pool size. Arm 2 reports explicit-selection precision, recall, and F1; Arm 3 reports parsed actual-use precision, recall, F1, and downstream success. Dashes indicate excluded entries.
Agent / Model
Pool
k
Arm 2: Agent Selection
Arm 3: Real Execution
P
R
F1
P
R
F1
Succ.
Gemini CLI Gemini-3.1-Pro-Preview
Random
5
74.4
75.0
74.7
18.6
69.4
29.3
39.2
Random
10
72.7
72.7
72.7
7.1
66.4
12.9
38.1
Random
20
80.1
81.8
81.0
3.6
66.0
6.8
39.2
Random
50
81.2
84.1
82.6
1.4
65.8
2.8
37.6
Random
100
77.4
83.0
80.1
0.7
66.0
1.4
39.0
Similar
5
54.3
69.3
60.9
17.6
70.1
28.1
38.8
Similar
10
61.3
79.5
69.2
7.0
67.3
12.6
38.5
Similar
20
58.4
77.3
66.6
3.7
66.2
6.9
34.0
Similar
50
59.3
76.1
66.7
1.4
66.2
2.7
36.7
Similar
100
55.4
73.9
63.3
0.7
66.7
1.4
36.1
Dissimilar
5
74.4
76.1
75.3
14.6
63.2
23.7
34.0
Dissimilar
10
80.1
81.8
81.0
8.7
66.0
15.3
38.8
Dissimilar
20
82.4
83.0
82.7
5.1
65.5
9.5
35.6
Dissimilar
50
79.3
80.7
80.0
1.6
64.4
3.1
38.1
Dissimilar
100
83.5
84.1
83.8
0.7
61.6
1.5
34.5
Codex GPT-5.4
Random
5
81.8
84.1
82.9
33.1
41.6
36.8
24.3
Random
10
83.0
86.4
84.6
39.2
59.7
47.3
35.5
Random
20
84.1
87.5
85.8
35.3
69.3
46.8
40.9
Random
50
71.7
87.5
78.8
15.8
63.5
25.4
35.0
Random
100
62.2
85.2
71.9
8.1
73.6
14.6
44.8
Similar
5
51.9
81.8
63.5
51.3
72.4
60.0
44.5
Similar
10
44.4
83.0
57.8
37.5
66.0
47.9
40.7
Similar
20
35.8
77.3
48.9
27.7
66.1
39.1
44.3
Similar
50
37.8
76.1
50.5
13.1
61.8
21.6
42.3
Similar
100
31.9
70.5
43.9
6.7
54.3
11.9
43.0
Dissimilar
5
83.3
85.2
84.3
42.5
63.0
50.7
37.3
Dissimilar
10
83.0
85.2
84.1
29.7
61.3
40.0
35.0
Dissimilar
20
82.8
85.2
84.0
12.7
60.5
21.0
31.8
Dissimilar
50
77.5
85.2
81.2
7.2
65.1
12.9
39.5
Table 16: Complete numerical results for the outcome-annotation ablation. Entries report downstream success for skills constructed under the indicated trajectory mixture. normal exposes source-trajectory outcomes during construction; no-hint withholds them. Terminal-Bench-Pro entries use 130 trials per condition, with missing or infrastructure-error trials counted as failures.
스킬이 작동하는 메커니즘 중 절차적 앵커링(procedural_anchor)이 65.7%를 차지했고, 명시적 지식 주입(knowledge_injection)은 4.5%에 불과했다
후보 스킬 풀이 5개에서 100개로 커지자 실제로 실행 중 사용된 스킬의 정밀도(actual-use precision)는 29.6%에서 3.3%로 급락했다
헷갈리는 방해 스킬(confusable distractor)은 오프라인 스킬 식별 정확도를 떨어뜨렸지만, 다운스트림 과제 성공률은 크게 변하지 않았다
오라클 상태 성공률은 Skill 61.9%, Raw 59.1%, Workflow Memory 55.9%였고, SC2(실행층·검증 실패) 비율은 Raw 37.3%, Workflow 33.3%에서 Skill 23.5%로 줄었지만 SC3(호출·적용 실패) 비율은 Raw 대비 크게 늘었다(78/528 vs 19/528)
어디에 쓸 수 있나
코딩·터미널 작업을 수행하는 LLM 에이전트에 재사용 가능한 절차 지침(SKILL.md)을 설계할 때 무엇을 담아야 효과적인지 판단하는 기준으로 참고할 수 있다
에이전트가 스스로 경험을 쌓아 개선하는 '자기진화형' 시스템을 만들 때, 단순히 기록을 축적하는 대신 절차를 표준화된 형태로 정제하는 방향을 검토할 수 있다
스킬 라이브러리가 커질 때 검색 정밀도가 떨어지는 문제를 인지하고, 검색 단계와 실행 단계를 분리해 평가하는 설계에 참고할 수 있다
한계와 남은 검증
실험은 Terminal-Bench, Terminal-Bench-Pro, SkillsBench 등 터미널·소프트웨어 작업 위주 벤치마크와 Codex+GPT-5.3-Codex, Gemini CLI+Gemini-3.1-Pro-Preview 등 특정 에이전트-모델 조합에 한정되어 다른 도메인에 그대로 일반화된다고 보장하지 않는다
RQ4 실험은 GPT-5.3-Codex 대신 GPT-5.4를 사용해 RQ1~RQ3 결과와 절대값으로 직접 비교할 수 없으며, 세 가지 실험군 내부 비교로만 해석해야 한다
algorithmic_logic_error(논리 오류)나 static_verification_without_runtime(런타임 검증 부재) 같은 실패 유형은 스킬로도 크게 줄지 않아, 깊은 문제 재구성이나 강한 런타임 검증이 필요한 경우에는 스킬의 효과가 제한적이다
스킬은 잘못 적용되거나 과도하게 적용되거나 무시되는 새로운 실패 유형(SC3, 호출·적용 실패)을 만들어낼 수 있어 도입 시 이 부분에 대한 별도 점검이 필요하다
왜 중요한가
지금까지 스킬 문서의 효과는 '과제를 더 많이 맞췄는가'라는 결과만으로 평가돼 왔는데, 이 연구는 그 결과가 나온 이유를 행동 단위로 쪼개 보여준다. 스스로 경험을 축적해 개선하는 자기진화형 에이전트를 설계하거나 스킬 라이브러리를 운영하는 사람에게, 언제 스킬이 통하고 언제 실패하는지에 대한 실질적인 근거를 제공한다.
이 논문의 용어
스킬(Skill) · 무엇을 할지, 무엇을 점검할지, 어떤 함정을 피할지를 표준화된 형식(SKILL.md)으로 압축해 담은 절차 지침 문서
Workflow Memory · 과거 실행 기록을 다듬어 절차의 흐름을 그대로 보존한 형태의 기억으로, 스킬보다 원본에 더 가까운 형태
절차적 앵커링(Procedural anchoring) · 스킬이 새로운 사실을 알려주는 게 아니라 설정 단계, 명령 순서, 점검 항목 등 행동 자체를 일관되게 유지시켜 실행을 안정시키는 작동 방식
오픈 코딩(Open coding) · 미리 정해진 분류 없이 실행 기록을 사람이 직접 읽고 관찰된 실패·성공 양상을 서술적으로 표시하는 정성 분석 방법
오라클 상태 성공률(Oracle-status success rate) · 검증기(verifier)가 실제로 과제 성공 여부를 판정한 결과를 기준으로 집계한 성공률
