技能

技能（Skill）解決的是「讓 Agent 按你的方法做事」：把固定流程、內部規範、專用腳本寫進技能，Agent 在需要時讀取並照做。沿用 Agent Skills 通用的 SKILL.md 格式；平台只讀取開頭的 name 和 description，其他欄位忽略。

什麼時候用技能，什麼時候用別的：

技能的結構

一個技能是一個目錄，SKILL.md 必需，其餘按需：

pdf-tools/
├── SKILL.md          必需：frontmatter + 操作說明
├── scripts/fill.py   可選：說明中讓 Agent 執行的腳本
└── reference.md      可選：較長的參考資料，Agent 需要時才讀

被調用時，整個目錄會出現在沙箱的 /workspace/.skills/{skill_id}/ 下，Agent 會被告知這個絕對路徑。所以：

• 說明裡的命令和檔名用相對於技能目錄的路徑寫，例如 python3 scripts/fill.py <輸入> <輸出>，Agent 會補上目錄。
• 腳本在沙箱裡以 bash 執行，可用沙箱預裝的 Python、Node.js 等（見沙箱）；壓縮包裡的可執行權限會保留。腳本需要額外的包時，在說明裡寫明安裝命令（pip install 的包在同一會話裡會保留）。
• 參考資料放在單獨的檔案裡，在 SKILL.md 裡說明「什麼情況下去讀哪個檔案」，Agent 需要時用 read_file 讀取。

SKILL.md 的寫法

SKILL.md 以 YAML frontmatter 開頭，然後是給 Agent 的說明：

---
name: pdf-tools
description: 填寫和合併 PDF 表單。用戶需要處理 PDF 時使用。
---

# PDF 工具

## 填寫表單
1. 先用 `python3 scripts/inspect.py <檔案>` 列出表單欄位。
2. 把用戶給的值整理成 JSON，執行 `python3 scripts/fill.py <輸入> <輸出> <JSON>`。
3. 把輸出檔案用 deliver_file 交付。

## 合併
……

遇到加密的 PDF，先讀 reference.md 的「加密檔案」一節。

• name：必填，1–64 個小寫字母、數字和連字元，不能以連字元開頭或結尾，也不能連續兩個連字元；在項目內唯一。
• description：說明這個技能做什麼、什麼時候用。Agent 在決定是否調用一個技能時，只看到名字和描述，所以描述要能讓它判斷「這個任務該不該用它」。未填寫時取正文第一行，正文也沒有時取 name；超過 1024 字元的部分會被截掉。
• frontmatter 裡只讀取 name 和 description 兩個鍵，且必須是字串；其餘鍵忽略。
• 整個 SKILL.md 不超過 32 KiB。被調用時它會整份進入 Agent 的上下文，所以只寫「怎麼做」，把大段資料放進參考檔案。
• 正文建議按步驟寫，每步說明用什麼命令、輸入輸出是什麼、結果要怎麼交付；有分支時寫清判斷條件。寫給一個能讀檔案、能執行命令但不瞭解你業務的助手看。

打包與上載

• 上載技能目錄打成的 .zip（或改了副檔名的 .skill），SKILL.md 在壓縮包根目錄，或在唯一的頂層目錄裡（從 GitHub 下載的壓縮包就是這種）；也可以只上載一個 SKILL.md。
• 平台會把它整理成統一的形式（SKILL.md 在根目錄的 zip），去掉 macOS 打包時附帶的 __MACOSX/，保留每個檔案的權限位。
• 限制：技能包 50 MiB；解壓後單個檔案 ≤ 25 MiB、總計 ≤ 200 MiB、壓縮包條目（含目錄）≤ 500 個；不能含符號連結、絕對路徑或 ..。超限返回 413 skill_bundle_too_large，其他問題返回 422 invalid_skill_bundle，message 說明具體原因。
• 項目內名字唯一，重名返回 409 skill_name_taken。

cd pdf-tools && zip -r ../pdf-tools.zip . && cd ..
curl -s "$AXON_API/skills" -H "Authorization: Bearer $AXON_KEY" -F "file=@pdf-tools.zip"

{
  "id": "skill_4e9a1c7b2d5f4a6e8c0b3d7f9a2e4c6b",
  "name": "pdf-tools",
  "description": "填寫和合併 PDF 表單。用戶需要處理 PDF 時使用。",
  "size_bytes": 18342,
  "created_at": "2026-10-09T03:20:11.512930Z"
}

size_bytes 是平台整理後存儲的壓縮包大小。接口細節見上載技能。

在訊息中選用

發送訊息時把技能 ID 放進 skills（每條訊息最多 10 個，需要 skills:read 權限）。技能只對這一輪有效，下一輪需要時再次放進 skills。

curl -s "$AXON_API/sessions/$SESSION/messages" \
  -H "Authorization: Bearer $AXON_KEY" -H "Content-Type: application/json" \
  -d "{\"content\": \"把 form.pdf 的表單填上附件裡的資訊\", \"files\": [\"$FILE\"], \"skills\": [\"$SKILL\"]}"

這一輪裡發生的事：

1. 輪次開始時，Agent 拿到本輪可用技能的名字和描述（你選用的，加上平台內置的），並被提醒你選用了哪些。此時不下載任何東西。
2. Agent 判斷任務需要某個技能時，調用 use_skill 工具：agent.tool_use 的 name 是 use_skill，input 是 {"skill": "pdf-tools"}。平台這時才把技能包放進沙箱（下載、解壓，60 秒內完成），把 SKILL.md 的內容交給 Agent，agent.tool_result 的 content 為 Launching skill: pdf-tools。
3. Agent 按說明執行：執行腳本、讀參考檔案、交付結果，這些照常以 bash、read_file、deliver_file 等工具的事件出現。
4. 同一會話裡已經放進沙箱的技能，下一輪再被調用時直接複用，不再下載；沙箱回收重建後也仍在（/workspace 會保留）。

要注意的幾點：

• 選用是建議，不是命令。 Agent 根據任務和技能描述決定是否調用；只是閒聊的一輪不會調用。想要它一定用某個技能時，在訊息裡明確說「用 pdf-tools 技能處理」。
• 技能放進沙箱失敗（例如技能已被刪除、網絡問題）時，這次 use_skill 調用返回錯誤（agent.tool_result 的 is_error 為 true），Agent 能看到這個錯誤，輪次不會因此失敗。
• 平台內置的技能所有輪次都可用，不需要選用；與你選用的技能同名時，以你選用的為準。

更新與刪除

技能上載後內容不會變，同一個 ID 在任何一輪裡都是同一份說明。要更新：先刪除舊技能（釋放名字），再上載新版本，新技能有新的 ID；也可以換一個名字上載，再把客戶端改成新 ID。

刪除後：

• 之後的訊息不能再選用它（返回 404 skill_not_found），名字可以給新上載的技能使用；
• 已經發出的事件中的 skills 保持不變；
• 正在執行、已經選用了它的那一輪，如果此時才調用 use_skill，會得到「無法載入」的錯誤。請在沒有輪次在用它時刪除。

排查技能問題