Agent Skills 架構解剖學：終結上下文膨脹 (Anatomy of Agent SKILLS)

原始來源與檔名：20260512_2026-04-28T092536+0800-Anatomy of Agent SKILLS.md

來源：[[@Saboo_Shubham_]] / X (Twitter) — 2026-04-27 原始檔名：2026-04-28T092536+0800-Anatomy of Agent SKILLS.md

NAPKIN | 餐巾紙

餐巾紙公式

Context Bloat Death = Stuffing everything into the System Prompt. Skill Architecture = Folder -> SKILL.md (Trigger Description + Logic) -> references/ (Loaded on demand). Result: Progressive Disclosure. The LLM acts as its own router, loading only what it needs, keeping token cost low and accuracy high.

為什麼 Agent 在生產環境中經常失敗？不是因為模型不夠聰明，而是因為關鍵指令被淹沒在 20 萬 tokens 的垃圾參考資料中。作者提出「Skills 架構」是解決上下文膨脹的最佳方案。一個 Skill 本質上就是一個資料夾，透過 YAML 定義搜尋索引，並採用「漸進式披露」的三層載入機制（元資料 -> 說明 -> 參考檔案）。這使得 LLM 成為自己的路由器，實現了無成本堆疊組合 (Composition)。

一句話

這是一篇定義了 Agent 擴充套件「物理結構」的核心技術文。文章指出，Agent 失控的元兇是過度擁擠的提示詞視窗。解法是「Skill 資料夾架構」：第一層 YAML 描述用於路由，第二層 Markdown 主體提供核心邏輯，第三層 References 作為隨選加載。這套架構讓 Agent 能像人類看標籤挑工具一樣運作，且各團隊能獨立開發 Skill 而不互相干擾。「Skills 對 Agent 的意義，就像 npm 對 JavaScript 的意義。」

餐巾紙草圖

[ Progressive Disclosure Loading Tiers ]

L1: Metadata (Always loaded)
    YAML Frontmatter: Name + Description (100 tokens, acts as the Search Index/Router)

L2: Instructions (Loaded only on match)
    The body of SKILL.md (Core logic, steps)

L3: References (Loaded on demand)
    Files in /references, /assets, /scripts (Deep docs, examples, heavy context)

ROUND 1: SKELETON | 骨架掃描

“這篇文章在說什麼”

• 核心問題: Agent 失敗是因為關鍵指令在巨大的上下文視窗中被淹沒（Context Bloat）。
• 什麼是 Skill: 不是一段 Python class，而是硬碟上的一個資料夾，包含核心的 SKILL.md，可選的 references/, assets/, scripts/。它是跨框架兼容的。
• 第一/二行是搜尋索引: SKILL.md 開頭的 YAML（名稱與描述）是 LLM 選擇是否呼叫該 Skill 的依據。寫好描述比寫好內文更重要。
• 漸進式披露 (Progressive Disclosure):
  • L1 (Metadata): 始終載入（100 tokens）。
  • L2 (Instructions): 只有當描述匹配時才載入 SKILL.md 內文。
  • L3 (References): 只有當 L2 指示需要時，才去讀取外部檔案。
• LLM 作為路由器: 不是透過外部的向量檢索 (Vector Retrieval) 來決定呼叫誰，而是 LLM 自己閱讀 L1 的目錄來做出唯一排他性的選擇。
• 解耦組合 (Composition): 團隊可以獨立開發各自的 Skills（如資料清洗、品牌語氣），無需合併 Prompt，達成了像 npm 套件管理器一樣的模組化。

ROUND 2: DISSECTION | 血肉解剖

“憑什麼這麼說”

核心論證鏈

1. 注意力機制的物理限制: 儘管現代模型號稱有 200k+ 的視窗，但「大海撈針 (Needle in a haystack)」的準確率依然隨著雜訊增加而下降。減少視窗內的無關資訊是提昇準確率最直接的物理手段。
2. 延遲載入 (Lazy Loading) 的經濟學: 如果把所有工具和規則都塞進 System Prompt，每一次對話都在燒錢。漸進式披露保證了「你只為你當下使用的 Skill 付費」。
3. 沒有向量檢索的優勢: 傳統 RAG 使用 Embedding 比對相似度，這在尋找「工具」時極易出錯（因為工具描述往往相似但用途迥異）。讓具有完整推理能力的 LLM 自己讀目錄做選擇，準確率遠高於單純的數學向量比對。

關鍵證據

• 透過跨團隊協作場景證明：Data 團隊更新了 SQL-runner，Design 團隊更新了 Brand-voice。在 Skills 架構下，雙方只需 Git Push 自己的資料夾，Agent 就能無縫升級，完全不需要一個「系統架構師」去調和兩者在 System Prompt 中的衝突。

邊界條件

• 這種依賴 LLM 自行路由的機制，高度依賴於「描述 (Description)」的準確度。如果兩個 Skill 的 YAML 描述寫得過於模糊或重疊（例如：一個叫「處理數據」，一個叫「清理CSV」），LLM 就會選錯。這要求極高的文件寫作紀律。

ROUND 3: SOUL | 靈魂提取

“還能怎么用”

• 知識連結: 完美對應了《Harness 不是目的，知识才是护城河》中提到的「漸進式披露」策略。也與《MCP vs CLI was the wrong debate》中的「動態引入工具 (Code Mode)」殊途同歸，都是為了解決上下文膨脹。
• 深層洞見: “People spend hours on the body and ten seconds on the description, then wonder why their skill never gets used.” 這不僅是 Agent 的問題，也是人類管理的問題。主管寫了一堆 SOP（內文），但沒有明確定義觸發場景（描述），導致員工從來不去查閱。
• 行動呼籲: 立刻檢查你提供給 AI 的所有工具與 Prompt：
  1. 把落落長的範例和參考文件移出主 Prompt，變成單獨的文件。
  2. 重寫你所有 Agent Tool/Skill 的 description：不要寫「這是一個資料清洗工具」，要寫「當你需要去除 CSV 空值、去重或標準化欄位格式時，載入此技能」。讓觸發條件極度具體。