Build once, run on any agent：Agent Skills 實用指南

Agent Skills 核心概念與定義

作者與 Procore 資料工程資深經理 Shishir Tewari 在 GitHub Universe 2026 期間現場介紹了 Agent Skills 概念，要解決的是開發者重複向 AI 代理解釋相同任務，或得仰賴特定同事腦中的機構知識。此機制透過 SKILL.md 檔案，將重複性任務的指令納入版本控制，讓開發者能跨不同 AI 代理共用經驗。一個 Agent Skill 是以 SKILL.md 檔案為中心的版本化目錄，檔案中詳細描述何時以及如何執行某項可重複的任務。

這些指令雖然能在多個代理之間共享，執行過程仍高度依賴環境提供的工具、憑證與權限。例如，一個 Skill 可以描述如何查詢資料庫，但本身不會授予該資料庫的存取權限。這項技術讓個人或團隊的領域知識轉為可重用的指令，但實際運作仍需外部環境支援。

明確界定任務與驗證邏輯

要讓 Skill 發揮最大效用，必須清楚定義任務、輸入與輸出。以 Proof Agent 為例，它的設計初衷是檢查 AI 產生的變更是否符合原始請求。該 Skill 的 frontmatter 明確將任務命名為 proof-agent，並說明目的是對 AI 產生的工作進行對抗性驗證，spawn 出獨立的驗證器，檢查虛假聲明、程式碼錯誤及安全問題。

Proof Agent 的核心規則是「自我驗證不等於驗證」。因此，其 SKILL.md 中的「When to Verify」區塊會明確指出何時調用該 Skill，其餘指令則說明驗證器應審查的內容，以及 findings 中需包含的證據。這種設計是因為若由同一個代理評估自身工作，其說明可能會影響審查，因此改用獨立的驗證器。

協調多個 Skill 以建構工作流程

當讓數據管線正確的判斷邏輯分散在四個人的腦中時，這四個人就是路線圖，管線的每項變更都取決於他們的可用性與對資料的了解。Data Forge 展示了如何把部分判斷邏輯寫進協同運作的 Skill。在支援桌面的管線範例中，流程從 forge-init Skill 開始，它負責找出來源資料表與命名慣例等細節，並寫入已解析的 manifest。其他 Skill 則讀取該 manifest，取得所需的專案背景。

接著，forge-builder Skill 負責協調從問題到 pull request 的工作。它使用 forge-dbx 查詢數據平台，並透過 forge-lint 套用團隊標準。過程中由人類審查提出的決策，最終產生的 pull request 包含管線程式碼、結構變更與測試。每個 Skill 各有明確職責，並共享專案背景，而不是各自重新探索，因此某個步驟有變動時，只需修改單一 Skill，不必動到其他部分。

專案配置與發現細節的分離

Skill 不應把每個專案的名稱、資料庫或慣例直接寫死。Data Forge 範例用 manifest 描述專案、指標儲存庫與平台，讓 Skill 能取用正確的專案細節，而不必把這些資訊寫進指令。manifest 內容包含專案名稱、store_name、平台引擎（如 duckdb）及 pipeline_framework 等設定。

已發現的細節與團隊標準應分開處理。forge-init 初始化 Skill 可檢查現有結構與程式碼模式，forge-lint Skill 則提供程式碼生成前需遵循的規則。儲存庫中發現的模式不會自動變成必須保留的規則，因此應讓已發現的細節可供審查，並讓人類在需要商業判斷之處確認或更改。要檢查 Skill 的可移植性，可以問：其他團隊能不能搭配自己的 manifest 使用相同的 Skill，而不必重寫？

共享執行路徑與工作流程檢查

Data Forge 中的 forge-dbx Skill 為其他 Skill 提供單一的數據平台存取方式。它讀取 manifest 並選擇 Databricks 或 DuckDB 適配器，讓每個 Skill 不必自行處理連線與查詢邏輯。manifest 可以選擇 DuckDB 用於本地演示，但無法安裝 DuckDB CLI，也無法授予資料庫存取權，這些仍由環境與使用者自行設定。

Data Forge 支援桌面的工作流程包含七個階段，每個階段都設有人類檢查點。進入下一階段前，工作流程會檢查前一階段是否完成；執行結構變更前，則要求批准。Proof Agent 範例把相同原則用在程式碼審查上。GitHub Actions 工作流程會提供驗證器原始請求與程式碼變更，但不提供編碼代理的自我評估。驗證器會回傳 PASS、FAIL 或 PARTIAL，並必須引用變更檔案中的證據。GitHub Action 只對 diff 做靜態審查，不執行程式碼，也不跑測試。

打包與驗證設定

支援多個客戶端，代表得讓多份相同指令保持同步。Data Forge 範例以 skills/*/SKILL.md 作為來源，再用打包腳本產生客戶端專用檔案，包括 .claude-plugin/plugin.json、.cursor-plugin/plugin.json 及 .github/agents/*.agent.md。該腳本也有供 CI 使用的檢查模式，執行指令為 node scripts/package.mjs --check。

由於各客戶端在可用模型、工具、憑證與權限上可能不同，安裝 Skill 後，需確認客戶端是否能辨識該 Skill 並用於預期任務、載入其參考資料、使用所需工具，並回傳 Skill 要求的證據。

建構 Agent Skills 的三項實踐

第一，將商業背景集中放在單一檔案。把專案特定的名稱、結構與慣例留在 manifest 中，讓每個 Skill 讀取它，而不是複製這些事實，團隊就有一個看得見、可更新的配置位置。第二，為相關 Skill 提供使用平台的單一一致方式。讓相關 Skill 以相同路徑執行查詢、作業與結構變更，而不是各自定義命令與連線邏輯，這樣工作流程的存取更容易理解，行為也更容易在每個客戶端中檢查。第三，用指令引導工作，用檢查來驗證。Skill 可以告訴代理要遵循哪些標準、何時請求批准。在需要背景或判斷的決策處加入人類審查，並用測試與 CI 檢查，在變更往下走之前攔截問題。若檢查必須阻止合併或部署，請在儲存庫的規則中設定這項要求。

建議從最讓人疲憊的解釋任務開始，寫下它的需求、終止點及審查者會看到的內容，然後試著與其他代理合作，並根據學到的結果持續改進。