前言
嗨嗨大家好！想跟大家分享一個蠻實用的運用主題喔。
在 Claude Code 這類 AI 程式設計代理工具裡面，「Skills（技能）」已經成為日常運作的核心了。只要把提示詞、工作流程還有禁止事項整理寫進SKILL.md，代理工具就會在需要的時機自動讀取，並且切換自己的行為模式，真的是蠻聰明的一個機制。不過實際運用下來，有一個讓人頭痛的難題會浮現出來，那就是「Skills 在團隊內部到底要怎麼分享？」。越好用的 Skills 當然越想推薦給同事，但是硬把全部 Skills 推給所有人其實不是好辦法。畢竟有些 Skills 是依附在自己個人工作流程上面的，甚至有些會跟別人的環境八字不合。
這篇文章想以我自己在運用的 dotfiles 入門套件作為範例，來介紹一種不依賴中央集權的 Skills 分享設計。希望能給大家在思考 Skills 運用時一些參考喔。
「團隊共用 skills repository」會遇到的困擾
大家一開始最容易想到的方案應該是：「做一個團隊共用的 skills repository，大家都從那邊 pull 下來」。乍看之下蠻乾淨的，但實際跑起來會出現三個問題：
- 不需要的 Skills 也會被塞給所有人
- 維護負擔全部集中在中央
- 很難輕鬆地進行各種嘗試
我個人覺得，Skills 的養成方式本來就是因人而異的，反而先讓大家各自發揮會更好。這樣才會孕育出多元的 Skills，也能提升整個團隊的敏捷度。
各自攜帶、互相分享的 dotfiles 型分享方式
因此這次採用的設計，是讓每個人都把 Skills 放在自己的 dotfiles repository 裡面，需要的人再各自去 pull，類似 P2P 的結構。核心原則如下：
- 自己做的 Skills 放在自己的 dotfiles，並且以那邊作為 source of truth
- 想借用別人的 Skills 時，只要從對方的 dotfiles 去 install 就好
- 不強迫也不做中央管理，只創造「想用就能用」的狀態
為了讓這種運用方式容易執行，我做了一個以 chezmoi 為基礎的入門套件。
入門套件的結構
這個 repository 放在 github.com/kamo-shika/chezmoi-dotfiles-starter，內容其實很單純：
.
├── .chezmoiignore # chezmoi 會忽略的檔案
├── .gitignore
├── README.md
└── dot_claude/ # 會被佈署到 ~/.claude/
├── CLAUDE.md # 全域的使用者指示
├── settings.json # Claude Code 的設定
└── skills/ # 使用者 Skills 的存放處
├── example-skill/
│ └── SKILL.md
└── skill-management/
└── SKILL.md # Skills 管理的運用規則
依照 chezmoi 的命名規則，dot_foo 會被展開成 ~/.foo。也就是說，dot_claude/skills/ 會直接被佈署到 ~/.claude/skills/，Claude Code 就能順利讀取到囉。
使用方式也超級簡單，只要跑 chezmoi init 跟 chezmoi apply 就可以了。就算換到新的電腦，也只要幾個指令就能把 Skills 整套復原起來。
bash
brew install chezmoi
chezmoi init https://github.com/<your-username>/dotfiles.git
chezmoi apply
到這裡為止，都跟一般的 dotfiles 管理沒什麼差別。這個入門套件真正的重點是：把 Skills 分成三類、各自清楚地分開管理。
依照「出處」把 Skills 分成三類
在 Claude Code 環境中處理的 Skills，依照出處可以分成以下三種：
分類範例管理工具1. 自製 Skills自己寫的 skill-management 或獨創工作流程chezmoi2. 別人做的 Skills從 vercel-labs 的 skills.sh 拉下來的skills CLI3. 案件專屬 Skills特定專案的規範或工作流程專案 repo
這裡超級重要的原則就是：絕對不要混用出處。如果同一個 Skill 被 chezmoi 跟 skills CLI 雙邊管理，那麼 skills update 拉下來的最新版，很可能會被下次的 chezmoi apply 用舊內容蓋回去，就會釀成事故喔。
1. 自製 Skills 用 chezmoi 管理並公開
自己寫的 Skills 放在 ~/dotfiles/dot_claude/skills/<name>/SKILL.md。編輯時在這個 source 端進行，然後用 chezmoi apply 反映到 ~/.claude/skills/。
想要分享的話，只要把 dotfiles repository push 上去，想用的成員就能直接 pull 取得。push 到公司內部的 GHE 就能做公司內部限定分享；放到 public 的 GitHub 也可以分享給公司外部的朋友。
2. 別人的 Skills 就交給 skills CLI
使用 Vercel Labs 公開的 skills CLI（透過 skills.sh），可以一個指令就 install 別人公開的 Skills：
bash
skills add <owner>/<repo> -g # 全域 install
skills update -g # 全部更新
skills find <query> # 在 skills.sh 搜尋
install 之後的實體會放在 ~/.claude/skills/<name>/，但請千萬不要把這些檔案納入 chezmoi 的管理範圍。理由就是前面提到的，當 skills update 和 chezmoi apply 都對同一個檔案下手時，就會發生事故。
3. 案件 Skills 直接放進專案裡
只在特定案件才會用到的 Skills（例如那個案件的部署流程、或是案件特有的工單運作方式），就直接 commit 到專案 repo 的 .claude/skills/。Claude Code 會把 .claude/skills/ 當作 project scope 來讀取，所以其他成員只要 clone repo 就能自動使用了。
如果把案件 Skills 放進個人 dotfiles 或 skills CLI 裡面，離開那個案件之後，不需要的 Skills 會一直留在 global 空間，反而會變成雜訊。所以原則就是：案件專屬的東西，就放在會跟著案件一起消失的位置。
把運用規則本身也做成 Skills 來分享
這個入門套件裡面，附了一個把運用規則本身進行 codify 的 Skills，名字叫做 skill-management。
skill-management/SKILL.md 的 description 裡面，為了在所有跟 Skills 相關的話題都能確實觸發，放了超多的觸發詞。給大家節錄一小段感受一下氣氛：
提供 Claude Code Skills 的建立、新增、更新、刪除、佈署等運用規則。當使用者提到「做 Skill」、「新增 Skill」、「skills add」、「用 chezmoi 管理 Skill」等語句，或是出現
~/.claude/skills/、~/.agents/.skill-lock.json、dot_claude/skills/等路徑時，必定觸發。
換句話說，當使用者說出「我想新增 Skill」的當下，Claude Code 就會讀進這個 Skills，依照三分類判定流程確認「這是自製的？別人的？還是案件專屬的？」，然後再用正確的工具進行作業。重點在於：把運用規則寫成代理工具能直接讀取的形式，而不是寫在 Wiki 上讓人類自己去翻。
這樣的設計也會帶來一些附帶的好處：
- 新進成員就算不知道規則，也能自動加入同一套運作方式
- 規則有變動時，只要重新 push dotfiles，所有 pull 的成員就能一起跟著更新
在公司內部 GHE 使用時的眉角
在公司內部使用時，會把 dotfiles 放在公司的 GitHub Enterprise（之後簡稱 GHE），其他成員再從那邊 install。這邊有一個 skills CLI 的小陷阱想跟大家分享。
skills add 會依照 host name 進行分支處理，非 github.com 的來源（包括 GHE）會被註冊為 sourceType: "git"。在這種情況下，folder hash 會保持空值，之後執行 skills update -g 會悄悄地 skip 掉，連錯誤訊息也不會丟出來。原因是 CLI 內部將 api.github.com 寫死了，沒有辦法去對 GHE 的 API endpoint 發出查詢。
解法其實蠻簡單的，用同樣的 URL 再執行一次 skills add，就會以覆蓋方式 install。這是目前 GHE install 唯一的更新手段：
bash
# 其他成員的 GHE Skills 更新步驟
export GH_TOKEN=$(gh auth token -h <your-ghe-host>)
skills add https://<your-ghe-host>/<your-ghe-user>/<your-ghe-user>-dotfiles -s <name> -g -y
推薦大家用 GH_TOKEN 環境變數明確傳入喔。我自己觀察過，在 skills CLI 這邊，gh auth token 的 host 指定有時候會失效。
這個 know-how 也已經寫進 skill-management 這個 Skills 的本文裡面了，所以使用中的成員只要說「想要在 GHE 更新 Skills」，Claude Code 就能自然地回覆正確的步驟。
總結
把 Skills 分享做成中央集權型的話，要同時兼顧彈性跟維護性其實意外地困難。相對地，只要採用以下三個分類：
- 自製 Skills 用 chezmoi 管理放進自己的 dotfiles
- 別人的 Skills 交給 skills CLI 處理
- 案件 Skills 直接放在專案 repo
各自分開管理之後，就能在避開中央集權的同時，創造出整個團隊可以互相利用的狀態。
再把運用規則本身也做成 Skills 交給代理工具讀取，就算團隊規模擴大，也能繼續維持紀律。讀 Wiki 的成本降為零，人類需要記住的事情也大幅減少了。
這套運用方式其實才剛開始跑而已，未來會怎麼發展老實說我也還不太確定。之後如果有新的進展或發現，會再寫一篇文章跟大家分享喔。
