Sona Orbitwork diary

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

· Sona Orbit

English version →

幾個資料夾各自連到中央的共用技能庫,右下角是工作紀錄卡

為什麼要這樣設計

只用一個 agent、只做一類工作時,把規則寫進全域設定檔就夠了。工作類型和 agent 一多,這個做法就會出問題:

  • 一份全域檔要同時管 App 送審、影片製作、後端部署,agent 每次開工都要讀完一整份,裡面大部分和這次的工作無關。
  • Claude Code 讀得到的技能,Codex 讀不到;同一份規則複製到好幾處,其中一份很快就會過時。
  • 上一個 agent 做到哪裡,下一個 agent 不知道,只能重新問一遍。

所以這套設計要達成三個目標:agent 只拿到這次工作需要的規則、不同家的 agent 讀到同一份規則、做完的工作接得上。對應的做法是:用資料夾區分工作類型、把通用技能集中在一處按需讀取、做完寫紀錄。全域設定檔只剩下指標。

具體分成三層:

  1. 全域只放指標。每個 agent 的全域設定檔保持很短,只寫去哪裡找規則、做完要寫紀錄,以及所有工作都要守的幾條底線。
  2. 工作類型用專案資料夾區分。每類工作的守則和專屬技能放在它自己的資料夾。agent 進到哪個資料夾,就拿到那類工作的規則。
  3. 通用技能集中放在共用技能庫,用到時才讀。各家 agent 讀的都是同一份。

此外還有一條貫穿三層的規則:做完一定寫紀錄,下一次或下一個 agent 才接得上。

一、為什麼不全部放在全域

把所有技能放進全域,看起來最省事,實際用下來會遇到四個問題:

  • 規則混在一起。送審規則、影片製作流程、後端的技術限制全寫在同一份檔案裡,改字幕時 agent 也得讀一遍送審規則。
  • 容易誤觸發。技能靠描述觸發。全域技能一多,描述就會互相重疊,「整理一下」可能叫出做報表的技能。
  • 佔 context。全域的內容每段對話一開始都會載入。和這次工作無關的內容越多,留給程式碼和文件的空間就越少。
  • 不同 agent 讀不到同一份。Claude Code、Codex、Antigravity、DeepSeek harness 各讀各的位置。要大家都讀到,就得複製好幾份,其中一份很快就會過時。

二、三層結構

三層結構:各 agent 讀哪個檔 Claude Code Codex Antigravity DeepSeek harness 全域只放指標 ~/.claude/CLAUDE.md ~/.codex/AGENTS.md ~/.gemini/GEMINI.md $DSH_HOME/AGENTS.md 專案資料夾這類工作的守則 ./CLAUDE.md ./AGENTS.md ./AGENTS.md ./AGENTS.md 內容相同 同一個檔 專屬技能只在這裡觸發 ./.agents/skills/ 四家共用一份,放在專案資料夾裡 按需讀取 做完寫入 共用技能庫 HTTP 或 Git,每個 agent 都拿得到 索引 → 入口 → 子規格,只讀需要的那篇 工作紀錄 原話・做了什麼 結果・用了哪篇
橫向是各家 agent,縱向是三層。全域各家位置不同;專案資料夾裡,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 讀的檔名不同,可以用三個做法對齊:

  1. 同一個資料夾放兩份內容相同的檔案。Claude Code 讀 CLAUDE.md;Codex、Antigravity、DeepSeek harness 都讀 AGENTS.md。兩份逐字相同,四家就讀到同一套規則。改規則時兩份一起改,改完用 diff 檢查。
  2. 全域檔只寫指標。每個 agent 的全域檔寫的是同幾件事,內容都是「去讀哪一篇」,規則本身不寫在全域檔。規則會一直更新,正本只有一份,就不會出現兩個版本。
  3. 共用技能庫用 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 開工時先查和這次工作相關的紀錄,這筆紀錄才會在下一次自動出現。

一次完整的工作循環 1進資料夾 CLAUDE.md AGENTS.md 拿到守則與近況 2載入專屬技能 .agents/skills/ 四家共用一份 只在這類工作觸發 3取通用技能 查索引 → 讀入口 只讀需要的那篇 不需要就不讀 4做完寫紀錄 原話・做了什麼 結果・用了哪篇 資料夾近況補一行 下一次、下一個 agent 開工時,先讀相關紀錄
第 1、2 步由資料夾決定,第 3 步依需要才讀,第 4 步寫下的紀錄會在下一次開工時讀回來。

七、代價

  • 兩份檔要同步:./CLAUDE.md 和 ./AGENTS.md。漏改一份,Claude Code 和其他三家就會照不同的規則做事。
  • 正本只有一份,寫錯就一起錯。所以每條守則都要加日期,紀錄也要寫明用了哪篇技能,出錯時才找得到源頭。
  • 共用技能庫連不到時要有退路。在全域檔寫好備援,例如改讀本機的 Git 副本。
  • 整理要花時間。沒有索引和篇幅限制,共用技能庫最後也會變成另一個塞滿東西的全域資料夾。

八、導入步驟

  1. 把全域技能逐一問一次:換一類工作還用得到嗎?用不到的,搬進對應的專案資料夾。
  2. 每類工作一個資料夾,寫一份短守則,分成守則、位置、近況三段。
  3. 同一個資料夾放 CLAUDE.md 和 AGENTS.md,內容相同。
  4. 把共用的做法集中成一個有索引的技能庫,全域檔只寫「先讀這裡的入口」。
  5. 規定每次做完都寫一筆紀錄:原話、做了什麼、結果、用了哪篇。

前兩步一個下午就能做完。第五步要持續一個月左右才看得出效果。