技能不放全域:用資料夾組織 AI agent 的技能
· Sona Orbit

為什麼要這樣設計
只用一個 agent、只做一類工作時,把規則寫進全域設定檔就夠了。工作類型和 agent 一多,這個做法就會出問題:
- 一份全域檔要同時管 App 送審、影片製作、後端部署,agent 每次開工都要讀完一整份,裡面大部分和這次的工作無關。
- Claude Code 讀得到的技能,Codex 讀不到;同一份規則複製到好幾處,其中一份很快就會過時。
- 上一個 agent 做到哪裡,下一個 agent 不知道,只能重新問一遍。
所以這套設計要達成三個目標:agent 只拿到這次工作需要的規則、不同家的 agent 讀到同一份規則、做完的工作接得上。對應的做法是:用資料夾區分工作類型、把通用技能集中在一處按需讀取、做完寫紀錄。全域設定檔只剩下指標。
具體分成三層:
- 全域只放指標。每個 agent 的全域設定檔保持很短,只寫去哪裡找規則、做完要寫紀錄,以及所有工作都要守的幾條底線。
- 工作類型用專案資料夾區分。每類工作的守則和專屬技能放在它自己的資料夾。agent 進到哪個資料夾,就拿到那類工作的規則。
- 通用技能集中放在共用技能庫,用到時才讀。各家 agent 讀的都是同一份。
此外還有一條貫穿三層的規則:做完一定寫紀錄,下一次或下一個 agent 才接得上。
一、為什麼不全部放在全域
把所有技能放進全域,看起來最省事,實際用下來會遇到四個問題:
- 規則混在一起。送審規則、影片製作流程、後端的技術限制全寫在同一份檔案裡,改字幕時 agent 也得讀一遍送審規則。
- 容易誤觸發。技能靠描述觸發。全域技能一多,描述就會互相重疊,「整理一下」可能叫出做報表的技能。
- 佔 context。全域的內容每段對話一開始都會載入。和這次工作無關的內容越多,留給程式碼和文件的空間就越少。
- 不同 agent 讀不到同一份。Claude Code、Codex、Antigravity、DeepSeek harness 各讀各的位置。要大家都讀到,就得複製好幾份,其中一份很快就會過時。
二、三層結構
AGENTS.md,只有 Claude Code 讀 CLAUDE.md,所以一個資料夾放這兩份、內容相同就夠了。最下面的共用技能庫和工作紀錄,每家都讀同一份。專屬技能只放一份在 .agents/skills/;Claude Code 預設讀 .claude/skills/,用一個連結指過去就好。Antigravity 的全域也可以用 ~/.gemini/AGENTS.md。| 層 | 放什麼 | 不放什麼 |
|---|---|---|
| 全域 | 去哪裡找規則、紀錄格式、跨工作的底線 | 任何只屬於某類工作的規則 |
| 專案資料夾 | 這類工作已經定下的事、完成標準、專屬技能 | 別的工作也用得到的做法 |
| 共用技能庫 | 跨工作的做法:連線、部署、測試、設計規範 | 「現在的狀態」的快照 |
判斷一條規則放在哪一層,只要問一句:換一類工作,還用得到嗎?用不到就放專案資料夾;用得到就放共用技能庫,然後在全域或資料夾裡放一行指標。
三、資料夾就是工作類型
資料夾規則檔裡寫的是這類工作已經定下的事。每條守則都加上日期,之後才查得到是什麼時候、為什麼定的。
| 工作類型 | 資料夾給 agent 的 |
|---|---|
| App 開發 | 語言範圍、收費規則、送審前的檢查、部署指令、最近做過的事 |
| 影片製作 | 專用指令、製片流程、交件前的品質關卡、素材授權怎麼標 |
| 後端服務 | 技術限制、收工前要跑的測試、不准自己部署、金鑰放在哪裡 |
| 報表與資料 | 只能查不能改、資料口徑、只在這裡用得到的驗證技能 |
規則檔可以分成三段:
- 守則:已經定下的事,每條加日期。
- 位置:倉庫、部署方式、文件放在哪。只寫代號,不寫金鑰本身。
- 近況:做完一件事補一行,最多保留二十行,讓下一個進這個資料夾的 agent 知道最近發生了什麼。
只在某類工作有用的技能,放在那個資料夾的 .agents/skills/ 裡,不要放到全域。Codex、Antigravity 直接讀這裡;Claude Code 預設讀 .claude/skills/,做一個連結指到 .agents/skills/,技能就只有一份。
四、讓不同 agent 讀同一套規則
各家 agent 讀的檔名不同,可以用三個做法對齊:
- 同一個資料夾放兩份內容相同的檔案。Claude Code 讀
CLAUDE.md;Codex、Antigravity、DeepSeek harness 都讀AGENTS.md。兩份逐字相同,四家就讀到同一套規則。改規則時兩份一起改,改完用diff檢查。 - 全域檔只寫指標。每個 agent 的全域檔寫的是同幾件事,內容都是「去讀哪一篇」,規則本身不寫在全域檔。規則會一直更新,正本只有一份,就不會出現兩個版本。
- 共用技能庫用 HTTP 或 Git 提供。各家技能格式不同,但每個 agent 都會執行
curl和git。共用技能庫可以放在這兩種方式拿得到的地方,就不受哪家工具的限制。
外部技能也照同樣的原則處理:把它整理成共用技能庫裡的一篇文件,不要複製進某一家 agent 的技能資料夾。只有需要靠工具本身的觸發機制、而且要在本機執行的技能,才放進 agent 自己的技能資料夾。
五、共用技能庫:按需取用
共用技能庫的重點是 agent 只讀這次需要的那一篇。建議分三層索引:
GET /skills?q=<關鍵字> → 清單:每篇只有標題和一行摘要
GET /skill?id=<入口> → 入口:「要做什麼 → 讀哪篇」的對照表
GET /skill?id=<子規格> → 只讀真正需要的那一篇
入口依領域分,例如主機與部署、模型與額度、App 開發、視覺與網站、影片、自動化。數量在十個以內,agent 掃一眼就知道該從哪裡進去。
寫技能文件的規矩:
- 主檔只寫「怎麼做」和「禁忌」,控制在 8 KB 以內。
- 案例和長範例放到附件資料夾,需要時再讀。
- 同一件事只寫在一處,其他地方用連結。
- 不寫「現在的狀態」,例如哪台機器在跑什麼。這類資訊一律現場查,不然很快就過時。

六、做完寫紀錄
紀錄讓工作可以接續。每次做完,寫一筆到同一個地方:
{
"agent": "<工具>@<主機>",
"ask": "<交代時的原話,一字不改>",
"task": "<做了什麼>",
"summary": "<結果一兩句>",
"refs": ["<用到的技能、檔案>"]
}
ask放原話。整理過的版本會混進 agent 自己的理解,事後回頭看,原話才能回答「當時到底要什麼」。agent寫工具和主機。出問題時,直接查得到是誰、在哪台機器做的。refs寫用了哪篇技能。哪篇常被用、哪篇常出錯,統計一下就知道該先改哪篇。
紀錄寫了之後要能被讀回來:agent 開工時先查和這次工作相關的紀錄,這筆紀錄才會在下一次自動出現。
七、代價
- 兩份檔要同步:
./CLAUDE.md和./AGENTS.md。漏改一份,Claude Code 和其他三家就會照不同的規則做事。 - 正本只有一份,寫錯就一起錯。所以每條守則都要加日期,紀錄也要寫明用了哪篇技能,出錯時才找得到源頭。
- 共用技能庫連不到時要有退路。在全域檔寫好備援,例如改讀本機的 Git 副本。
- 整理要花時間。沒有索引和篇幅限制,共用技能庫最後也會變成另一個塞滿東西的全域資料夾。
八、導入步驟
- 把全域技能逐一問一次:換一類工作還用得到嗎?用不到的,搬進對應的專案資料夾。
- 每類工作一個資料夾,寫一份短守則,分成守則、位置、近況三段。
- 同一個資料夾放
CLAUDE.md和AGENTS.md,內容相同。 - 把共用的做法集中成一個有索引的技能庫,全域檔只寫「先讀這裡的入口」。
- 規定每次做完都寫一筆紀錄:原話、做了什麼、結果、用了哪篇。
前兩步一個下午就能做完。第五步要持續一個月左右才看得出效果。