Mange Context through Agent Skills

研究現有流程如何使用 Agent Skills 模組化管理上下文

@ AI

前言

使用 Agentic AI 解決問題時上下文管理至關重要，而 Anthropic 推出的 Agent Skills🔗 上下文管理模式近期也成為業界的一種主流標準，在 Claude Code🔗、Codex🔗、Opencode🔗 等工具中都有支援，透過研究如何整合進入現有的流程來增加開發效率。

現有問題

專案累積了許多有關專案的文件，在我的案例來說紀錄了一系列針對特定專案的文件，真實情況也可能不一定與程式開發相關，而是不同領域相關的知識、規則或範例：

project
├── xxx.md
├── HowToFetchData.md
├── HowToFormValidation.md
├── HowToOrganizeComponent.md
└── HowToTesting.md

舉例要寫測試，就可以把相關領域文件請出來丟給 Agentic AI：

Terminal window
Base on @HowToTesting.md, finish test in @Foobar.test.ts

可以說是最直白靈活的管理上下文手法，但這樣的工作方式還是像一盤散沙需要透過命令指派每一次的指令：

  • 上下文遺漏：可能忘記提供關鍵文件，導致 AI 產生不符合專案規範的代碼。
  • 重複性工作：每次對話都需要重新指定指派上下文。
  • 沒有特別規範：格式隨意。

透過 Agent Skills 自動管理上下文

想要更智慧地讓 Agent 自行判斷與抓取相關的上下文，就可以透過 Skills 達成。運作關鍵是「漸進式揭露」，在每次 Agent 執行時只在需要時載入 Skills 上下文：

  • 探索：Agent 僅載入每個可用技能的 name 和 description 元資料，判斷與當前任務是否相關
  • 啟動：當任務與技能描述相符時，Agent 會讀取完整的 SKILL.md 指令並將其套用到上下文中
  • 執行：依需求載入引用的檔案或執行捆綁的程式碼
Terminal window
my-skill/
├── SKILL.md          # 必要: 指示 + 元資料
├── scripts/          # 可選: 可執行代碼
├── references/       # 可選: 可動態引用文件
└── assets/           # 可選: 靜態資源

使用 Scripts 的例子

舉例我的專案有個生成 OpenAPI🔗 腳本的步驟包裝在 swagger.sh shell script 裡面，通常在開發結束後執行以便產生 API 文件，就可以透過撰寫技能與其關聯文件來揭露特定技能。

Terminal window
swagger/
├── SKILL.md
└── scripts/
    └── doc-gen.sh
SKILL.md
---
name: swagger
description: Comprehensive Swagger documentation management for Go projects using swaggo/swag
---


## What I do


This skill includes the `scripts/doc-gen.sh` script and provides instructions for managing Swagger API documentation in Go projects:


...

使用 references 和 assets 的例子

為了更好地說明 references/ 和 assets/ 的使用，以下是一個更完整的技能例子，包含了 references 與 assets 目錄：

complete-skill/
├── SKILL.md
├── scripts/
│   └── process-data.sh
├── references/
│   ├── API_REFERENCE.md
│   └── error-codes.md
└── assets/
    ├── templates/
    │   └── config-template.json
    └── diagrams/
        └── workflow.png

在 SKILL.md 中，可以這樣引用這些文件：

SKILL.md
---
name: complete-skill
description: 處理數據並生成報告的完整技能，包含參考文檔和靜態資源
---


## 功能說明


此技能用於處理數據並生成報告。


## 詳細參考


請參閱 [API 參考](references/API_REFERENCE.md) 獲取完整的 API 文檔。


如果遇到錯誤，請檢查 [錯誤代碼表](references/error-codes.md)。


## 使用範例


使用 [設定模板](assets/templates/config-template.json) 作為起點。


工作流程圖請參考 [工作流程圖](assets/diagrams/workflow.png)。

這樣，Agent 可以在需要時動態載入這些額外的資源，而不會在初始載入時佔用過多上下文。

元資料規範

元資料 = 用於描述資料的資料，被存放於 Markdown 格式開頭的 frontmatter。不同規範有自己延伸的元資料，所以可以參考使用工具的文件及可。

  • name
    • 最多 64 個字符
    • 必須只包含小寫字母、數字和連字符
    • 不能包含 XML 標籤
    • 不能包含保留字：“anthropic”、“claude”
  • description
    • 不能為空
    • 最多 1024 個字符
    • 不能包含 XML 標籤

MCP vs Agent Skills

可相互輔助的關係
  1. 用提示詞指揮 Agent
  2. 用 Skills 規劃特定領域知識上下文，傳授智能體特定流程
  3. 用 MCP 可靠統一的整合所有外部能力

使用 Agent Skills 是不是意味著無限的上下文？

大量 Skills 仍會提高 AI Agent 錯誤引用機率

使用 Agent Skills 不意味著真正無限的上下文窗口，而是透過漸進式揭露（progressive disclosure）和外部執行機制，有效管理模型上下文。

延伸閱讀