起因

工作上有個需求：把散落在多個內部 API 的資料整合成一份分析報告。涉及的資料源有好幾個，每個 API 的認證方式、資料格式、存取路徑都不一樣。

我手上有兩個 AI agent 環境——一個跑 Claude（Opus），是我自己長期使用的個人 agent；另一個跑 OpenAI 的模型，是公司環境。需求最終要在公司環境執行，但探索和開發的過程在個人 agent 上進行比較順手。

問題來了：怎麼把我跟個人 agent 討論出來的知識，有效地交給公司 agent 使用？

不能只丟一段文字

最直覺的做法是把對話結論複製貼上，寫個文件丟過去。但實際試了就知道——一份平鋪直敘的文件，agent 讀完還是會問你一堆問題：

  • 「這個 API 的 base URL 是什麼？」
  • 「認證 token 放哪裡？」
  • 「回傳格式是 JSON 還是 Parquet？」
  • 「欄位名稱是 revenue 還是 acc_R100？」

每個問題都合理，但每次來回都是時間成本。尤其在 Telegram 這種非同步介面上，一個問題可能要等你看到、回覆、agent 再繼續，中間過了好幾分鐘。

Skills 作為 Agent 間的介面

後來採用的做法是把知識打包成一個 Skills 專案。這是 OpenClaw 生態系的一個概念，但核心想法跟框架無關：

skills/
├── my-skill/
│   ├── SKILL.md          # 入口：agent 第一個讀的文件
│   └── references/       # 詳細參考資料
│       ├── api-guide.md
│       └── data-sources.md
└── knowledge/
    └── domain-logic.md   # 領域知識和判斷邏輯

SKILL.md 是關鍵。它不是寫給人看的文件，是寫給 agent 看的操作手冊。結構大概長這樣：

  1. 觸發條件 — 什麼時候該用這個 skill
  2. 快速開始 — 最小可執行的步驟（通常是一行指令）
  3. 資料來源表 — 每個資料源的 URL、認證方式、備援方案
  4. 工作流程 — 逐步操作，包含實際的 curl/python 範例
  5. 注意事項 — 已知的坑和 workaround

重點在 progressive disclosure：agent 先讀 SKILL.md（< 500 行），大部分情況這就夠了。需要深入某個 API 的細節時，再去讀 references/ 下的對應文件。不需要一次把所有資訊塞進 context。

對話驅動的開發過程

整個 Skills 專案是在一天的對話中逐步成形的。流程大概是：

  1. 探索階段 — 我跟 agent 說「幫我查這個 API 有什麼 endpoint」，它去打 API、讀文件、回報結果
  2. 踩坑修正 — 發現某個 API 的文件跟實際回傳不一樣（欄位名對不上），agent 自己 debug 找出正確的欄位名
  3. 知識沉澱 — 每搞定一個資料源，就把結論寫成 reference 文件
  4. 整合測試 — 把所有資料源串起來跑一次，產出報告
  5. 打包交付 — 整理成 Skills 結構，產出 zip

這個過程裡，agent 不只是執行工具，它在做的是知識轉化 — 把零散的 API 探索結果，轉化成結構化的、可被其他 agent 消費的知識。

自主性的差異

後來把 Skills 交給公司環境（跑 OpenAI 模型）的 agent 執行時，遇到了一個有趣的對比。

公司 agent 在執行過程中，每遇到一個小障礙就會停下來問：

Agent: 執行需要 pyarrow 套件，是否要安裝？
我: 是
Agent: 安裝完成。接下來需要下載 72MB 的資料檔案，是否繼續？
我: 是
Agent: 下載完成。檔案中的欄位名稱是 acc_R112，但 SKILL.md 中提到的是 EPS，要用哪個？
我: SKILL.md 有寫對照表，你看 references/api-guide.md
Agent: 了解。正在讀取...

每一步都沒有錯，每個問題都合理。但這些都是不需要人類決策的執行細節。

相比之下，我的個人 agent（Opus）在開發階段的行為是：缺 library 就裝，API 回 401 就檢查 token 是不是過期然後嘗試替代方案，欄位名對不上就自己去 preview 資料找正確的名字。它只在真正需要決策的時候才會問我——比如「這個 API 需要 VPN 才能連，要不要幫你開？」或「這筆資料看起來異常，要繼續用還是跳過？」

這不是模型能力的差異（兩邊都能完成任務），而是自主性邊界的設定不同。一個把「裝套件」當成需要確認的操作，另一個把它當成執行的一部分。

自主性的設計哲學

想了一下，agent 的自主性大概可以分成三層：

可以自己做的：

  • 安裝依賴套件
  • 重試失敗的 API 呼叫
  • 在已知的替代方案間切換
  • 修正格式錯誤、型別不符

應該告知但不需等確認的：

  • 資料有延遲（標註即可，繼續執行）
  • 某個資料源不可用，已改用備援
  • 執行時間比預期長

必須問的：

  • 涉及外部發送（email、訊息、公開發文）
  • 涉及刪除或不可逆操作
  • 需要業務判斷（這個數字合理嗎？這個建議要發給客戶嗎？）

在 Skills 設計上，這意味著 SKILL.md 應該把備援方案寫清楚，讓 agent 自己判斷切換，而不是每個失敗都拋回給人類。比如：

## 資料來源
| 面向 | 主要來源 | 備援 | 
|------|---------|------|
| 價格 | 內部資料庫 | Yahoo Finance |
| 事件 | 內部 API（需 VPN）| 跳過此面向（--no-event）|

Agent 看到這個表，VPN 斷了就知道自己加 --no-event，不用問。

三段式 Pipeline

最後定型的架構是把產出報告拆成三步：

Step 1: Python 腳本（抓資料、算指標）→ JSON
Step 2: Agent 讀 JSON → 寫分析評論 → JSON
Step 3: Python 腳本（合併資料 + 評論）→ HTML 報告

腳本負責確定性的工作（API 呼叫、數學計算），agent 負責需要判斷力的工作（風險評估、行動建議）。這樣做的好處：

  1. 腳本部分可靠可重現 — 同樣的輸入永遠得到同樣的輸出
  2. Agent 部分有明確的輸入輸出 — 讀 JSON、寫 JSON，不需要自己去打 API
  3. 可以獨立測試 — 腳本壞了改腳本，agent 的分析品質不好改 prompt
  4. 跨模型相容 — 任何能讀寫 JSON 的 agent 都能做 Step 2

結論

這次經驗讓我覺得，AI agent 的生產力瓶頸往往不在模型能力，而在兩個地方：

  1. 知識的結構化程度 — 同樣的知識，散落在對話裡 vs 整理成 Skills，對 agent 的執行效率差異巨大
  2. 自主性的邊界設計 — agent 該在哪裡自己做決定、在哪裡停下來問人，這個邊界設對了，能省下大量不必要的來回

Skills 本質上是一種 agent-to-agent 的知識傳遞協議。寫得好的 SKILL.md，能讓接收端的 agent 像一個有經驗的新人一樣——拿到 SOP 就能幹活，只在真正模糊的地方才來找你確認。

而自主性的設計，最終是一個信任問題：你願意讓 agent 自己決定到什麼程度？裝一個 pip 套件是信任的最低門檻。如果連這個都要問，那 agent 就只是一個需要你逐行確認的腳本執行器，不是真正的助手。