如何跨儲存庫共享 Agent 技能並避免版本分歧
複製貼上 Agent 技能會導致各儲存庫版本悄然分歧。本文介紹如何將技能視為相依性管理,透過單一儲存庫與版本鎖定機制,確保各專案使用一致的技能版本,並建立完整的審核流程。
如何在多個儲存庫共用 agent skill
若要在多個儲存庫共用 agent skill,請停止複製檔案,改為依賴該檔案。維護一個 skills 儲存庫,為其建立標籤,讓各專案固定使用特定標籤。接著為每個 skill 新增 smoke test,並按照檢視相依性升級的方式檢視每次版本更新。
這包含四個部分:共用的單一真實來源、每個儲存庫固定使用的版本、每個 skill 的 smoke test,以及版本更新的檢視流程。以下內容會說明各部分存在的原因、2026 年提供的工具如何處理這些需求,以及如何在自架的 git remote 上建置完整流程,不涉及外部 git 主機或 package registry。smoke test 是唯一的例外。它們會執行 Claude Code,而 Claude Code 會將每個請求傳送至 model API,因此這個步驟仍會離開你的伺服器。
agent skill 是一個包含 SKILL.md 檔案的資料夾,以及該 skill 所需的指令碼和參考檔案。若你不熟悉這個單位,請先閱讀 什麼是 agent skill,以及 SKILL.md 如何運作。本頁說明的是這個單位周邊的供應鏈。
技能的存放位置,以及共用為何困難
Claude Code 會從以下位置等處載入技能,而 技能文件 會列出各個路徑。
.claude/skills/<skill-name>/SKILL.md位於受管理的設定目錄中,是企業層級的位置。組織部署此目錄的機器上,所有使用者都會載入其中的技能。~/.claude/skills/<skill-name>/SKILL.md是個人層級的位置。你所有的專案都會載入其中的技能,但其他人的專案不會。.claude/skills/<skill-name>/SKILL.md是專案層級的位置。簽出該儲存庫的人都會載入其中的技能。<plugin>/skills/<skill-name>/SKILL.md內含於 plugin 中。啟用該 plugin 的位置都會載入其中的技能。
Claude Code 也會從巢狀專案目錄、透過 --add-dir 指定的目錄,以及為你的 claude.ai 帳戶啟用的技能載入技能。
對團隊而言,專案層級的位置最實用,因為它會提交到版本控制,所有 clone 該 repo 的人都能取得。問題也從這裡開始。位於 .claude/skills/ 的技能隸屬於單一儲存庫。你有八個儲存庫,因此必須將技能複製八份。
frontmatter 也無法提供協助。Agent Skills spec 允許六個鍵;當你使用其他鍵時,負責套用該規範的發行工具會列出允許的鍵:
Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name請注意缺少的項目:其中沒有 version 鍵。你可以在 metadata 下記錄版本,但 spec 沒有定義相依性固定版本或更新機制。這是合理的,因為技能是文件,而不是 package。但這也表示版本控制必須由檔案周圍的層級負責,而該層級就是你的工作。
問題一:八份副本悄然分歧
複製貼上在第一天運作正常。到了第六十天就會失效。有人修正了 payments 儲存庫中的錯誤指令,卻未更動其他七份副本。另一個人則在 orders 中新增了關於分頁的規則。現在,同一個技能名稱會根據代理程式啟動所在的目錄,產生兩種不同的審查結果,而開發人員對此一無所知。
這種失敗是靜默的,因為不存在錯誤狀態。技能本質上是散文。過時的指令會產生自信但錯誤的答案,這類錯誤代價高昂。代理程式中沒有任何機制會比對你的副本與其他人的差異,因此唯一的訊號就是有人發現兩個儲存庫的內容不一致。
問題二:版本未鎖定
即使團隊將技能集中在同一處,常見的共享方式仍是複製步驟:安裝腳本、說明文件中的 curl 指令,或是同步資料夾的 shell alias。這些方法都會安裝當前分支最新版本的內容。
這意味著兩位開發者即使在同一個應用程式的相同 commit 上,也可能因為在不同日期執行同步,而運行不同的指令。這也導致在發生錯誤的代理執行後,無法回答關鍵問題:究竟是哪個版本的技能產生了此結果?若無記錄修訂版本,執行結果便無法重現,導致錯誤報告無法處理。
問題三:技能失效卻無人察覺
技能沒有編譯器。它是一組針對模型的指令,因此即使檔案內容完全未變,技能仍可能失效。模型升級會改變模型對長指令的遵循程度;技能所呼叫的命令列工具可能會變更旗標名稱;參考檔案中的 URL 可能會回傳 404 錯誤,導致代理程式誤將錯誤頁面內容當作回應來源。
在上述情況中,系統都不會發出明顯的失敗警示。代理程式依然會給出回應,只是回應品質較上個月下降。這種細微的品質衰退,在每次僅進行單一 Pull Request 的開發流程中極難察覺。
2026 年工具所解決的問題
目前已有數種解決方案推出,但它們對版本應存放的位置看法不同。
鎖定檔。 Vercel Labs 的 skills 命令列工具(vercel-labs/skills,採用 MIT 授權,截至 9 October 2026 的版本為 v1.7.2)會從 git repository 將 skills 安裝到 agent 預期的目錄,並了解超過 seventy 個 agent 的目錄結構。npx skills add <repo> 用於安裝,npx skills update 用於升級,npx skills list 用於顯示目前已有的項目。它會維護兩個鎖定檔。全域鎖定檔 ~/.agents/.skill-lock.json 會記錄單一使用者已安裝的項目。自 v1.4.1(20 February 2026)起,安裝到 project scope 也會在專案根目錄寫入 skills-lock.json,而該工具的原始碼表示,此檔案預期應提交至版本控制。npx skills experimental_install 會依此檔案還原專案的 skills。Issue 283 要求新增 skills install 命令,以便在另一台機器上還原全域鎖定檔;該 issue 已於 5 November 2026 以不予規劃結案,維護者指出這與 issue 549 是同一項請求。這兩項資訊都應視為狀態報告。每個專案的鎖定檔確實存在。在已發布的 v1.8.1 中,說明文字仍將還原命令標示為實驗性功能,但不指定來源執行 npx skills install 也會還原專案鎖定檔。
規格與測試。 SkillSpec 採取另一種方向。它將 SKILL.md 視為應進行檢查的契約,而不是可以直接信任的文字;其目標是讓 skills「可遵循、可測試且可驗證」。skillspec doctor <path> 會回報 agent 可能中斷執行脈絡的位置。skillspec boundary map <path> 會顯示 skill 的內容,skillspec boundary assess <path> 則會依風險排序,回報它能存取的項目。它是 Rust crate,採 MIT 或 Apache 2.0 雙重授權。版本 0.2.2 於 29 July 2026 發布,截至 10 October 2026 仍是 crates.io 上的最新版本。請安裝指定版本,不要安裝最新版本:
cargo install skillspec --version 0.2.2 --locked
skillspec --version自 12 November 2026 發布的 Cargo 1.100 起,cargo install 預設會使用隨套件提供的鎖定檔,而 --locked 不會執行任何動作。skillspec --version 應輸出 0.2.2。若顯示其他數字,表示你的 PATH 中較早出現的舊版 binary 正在生效。
供應商實務。 Google 在一篇介紹 如何建置、測試及擴展 agent skills 的文章中,說明其如何建置 google/skills 中的 skills。撇除規模因素後,這套機制就是一般的持續整合(CI)。每個 skill 在合併前,都必須通過 frontmatter metadata、行數、目錄結構與命名規則的 linter 檢查。只要任何 URL 回傳 404,連結檢查工具就會使建置失敗,藉此捕捉 agent 虛構出的看似合理連結。作者必須在 skill 之外提供 evaluation prompt suite 與評分準則。排程的 evaluation job 會每週針對整個程式庫執行,以發現回歸問題;每個 skill 也都有指定負責人,品質下降時應由該負責人修正。
三種解答背後的模式
您不必從中擇一。這些解答的底層是一個單一架構,而標準的 git 即可提供完整功能。
- 單一事實來源。該技能僅有一個歸屬地,每個儲存庫皆參照該歸屬地,而非儲存副本。
- 每個儲存庫鎖定特定版本。每個專案都會記錄其使用的確切修訂版本,因此升級動作即為該專案中包含作者與日期的一次 commit。
- 每個技能執行冒煙測試。透過一個可執行的檢查,證明該技能仍能產生預期的結果。
- 審查路徑。對共享技能的變更必須經過審查,且每個使用者在採用前都能看到差異比對(diff)。
這就是依賴關係的架構。技能成為共享產物的速度快於圍繞其發展的工具,因此,您現有且信任的工具即為最安全的選擇。
適用於小型團隊的自架 Git 遠端儲存庫配置
單一儲存庫存放所有技術文件。該儲存庫不包含其他內容,因此其提交歷史即為一份指令變更日誌。
agent-skills/
skills/
api-review/
SKILL.md
release-notes/
SKILL.md
tests/
api-review.sh
release-notes.sh
CHANGELOG.md軟體發布以標籤(tags)管理。請使用附註標籤(annotated tags),因為它們包含訊息與日期。請在訊息中說明使用者需要升級的原因:
git tag -a v1.4.0 -m "api-review: require pagination on list endpoints"
git push origin v1.4.0無論您的遠端伺服器是 Gitea、Forgejo、GitLab,或是透過 SSH 連線至 VPS 上的裸儲存庫(bare repository),以下內容皆適用。此處的所有操作僅涉及 git 與符號連結(symlink)。
使用 git submodule 進行鎖定
submodule 會在您的儲存庫中記錄另一個儲存庫的特定 commit。該記錄即為鎖定(pin)。在每個使用該模組的專案中:
git submodule add https://git.example.com/team/agent-skills.git vendor/agent-skills
git -C vendor/agent-skills fetch --tags
git -C vendor/agent-skills checkout v1.4.0
mkdir -p .claude/skills
ln -s ../../vendor/agent-skills/skills/api-review .claude/skills/api-review
git add .gitmodules vendor/agent-skills .claude/skills/api-review
git commit -m "Pin shared agent skills to v1.4.0"符號連結(symlink)是實現此功能的關鍵。專案層級的 skill 項目可以是指向磁碟其他位置目錄的符號連結,Claude Code 會追蹤該連結並讀取目標位置的 SKILL.md。因此,該 skill 會以一般專案 skill 的形式載入,而實際的位元組則儲存在您所選定 commit 的 submodule 中。
檢查鎖定狀態:
git submodule status正常的輸出列開頭為一個空格,接著是 commit、路徑,最後是最近的標籤(tag):
4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602 vendor/agent-skills (v1.4.0)開頭若為 -,表示該 submodule 未經初始化,因此 .claude/skills/api-review 指向空值,且該 skill 會在無提示的情況下無法載入。請執行 git submodule update --init 來修正此問題。開頭若為 +,表示目前簽出的 commit 與記錄的版本不符,這代表該開發者正在執行其他人未曾見過的指令。新複製的儲存庫需要執行 git clone --recurse-submodules,且此指令應寫入 README 中,因為一般的 clone 指令會使 vendor/agent-skills 保持為空且不會顯示任何錯誤訊息。
升級是經過審慎考量的行為,這正是此機制的重點所在:
git -C vendor/agent-skills fetch --tags
git -C vendor/agent-skills diff v1.4.0 v1.5.0 -- skills/
git -C vendor/agent-skills checkout v1.5.0
git add vendor/agent-skills
git commit -m "Bump shared agent skills to v1.5.0"diff 這一行是審查路徑。它顯示了其他所有使用該儲存庫的專案將會看到的相同變更,且適合放入 pull request 中。
改用外掛市集進行固定版本
如果不希望要求每位開發者學習 submodule,Claude Code 外掛系統會替你處理散布,而且可搭配自架的遠端儲存庫使用。請在 skills 儲存庫的 .claude-plugin/marketplace.json 放置目錄:
{
"name": "acme-agents",
"owner": { "name": "Platform team", "email": "platform@example.com" },
"plugins": [
{
"name": "team-skills",
"description": "Shared review and release skills",
"version": "1.4.0",
"source": {
"source": "url",
"url": "https://git.example.com/team/agent-skills.git",
"ref": "v1.4.0",
"sha": "4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602"
}
}
]
}這裡涉及兩個不同的來源,混淆兩者是最常見的錯誤。市集來源是指擷取目錄本身的位置,可接受以 ref 指定分支或標籤;在 Claude Code v2.1.324 或更新版本中,也可接受完整的小寫 commit SHA。它不接受獨立的 sha 欄位。目錄內的外掛來源則同時接受兩者;兩者都設定時,sha 是實際生效的固定版本。透過市集來源的 ref 固定目錄版本,並透過目錄項目的 sha 固定外掛版本。類型名稱也不同。在目錄內,url 表示要複製的 git 儲存庫。在市集來源中,url 表示直接連結至 marketplace.json 檔案,而 git 儲存庫則是 git。
每個使用中的儲存庫接著會在已提交的 .claude/settings.json 中宣告該市集:
{
"extraKnownMarketplaces": {
"acme-agents": {
"source": {
"source": "git",
"url": "https://git.example.com/team/agent-skills.git",
"ref": "v1.4.0"
}
}
},
"enabledPlugins": {
"team-skills@acme-agents": true
}
}團隊成員接受專案資料夾的 workspace trust 對話框後,Claude Code 就會為其註冊該市集,不必另外建立 wiki 頁面指示他們操作。目錄項目指向 git URL,而不是相對路徑,因此外掛不會僅依據儲存庫的設定安裝。每位團隊成員只需執行一次 claude plugin install team-skills@acme-agents --scope project;在此之前,Claude Code 會顯示外掛已在專案設定中啟用,但尚未安裝。之後,這些 skills 會以 /team-skills:api-review 回應,因為外掛 skills 會以外掛名稱加入命名空間,不會與同名的專案 skill 衝突。推送新標籤並更新目錄及使用中儲存庫的固定版本後,使用者執行 /plugin marketplace update acme-agents 重新整理;如果安裝摘要要求執行,接著再執行 /reload-plugins。
撰寫單一 skill 的 smoke test
Smoke test 是針對含有已知故障的 fixture 執行一次指令式 agent run,並進行一項 assertion。Claude Code 可搭配 -p 以非互動方式執行,使用者觸發的 skill 也能在其中運作:將 /skill-name 放入 prompt 字串,執行開始前就會展開。
#!/usr/bin/env bash
set -euo pipefail
claude -p "/api-review Read fixtures/orders-api.md and list the rule ids it breaks." \
--allowedTools "Read" \
--output-format json \
--json-schema '{"type":"object","properties":{"rule_ids":{"type":"array","items":{"type":"string"}}},"required":["rule_ids"]}' \
| jq -e '.structured_output.rule_ids | index("pagination-required")' > /dev/nullfixtures/orders-api.md 是含有一項刻意故障的簡短檔案。Assertion 是確認 skill 指出該故障。當篩選器產生 null 時,jq -e 會以非零狀態結束,因此停止捕捉這項預設故障的 skill 會使指令碼失敗。執行失敗時,claude 本身會以非零狀態結束,而 set -euo pipefail 會將任一失敗轉換為 failed test。
模型在不同執行之間可能改寫回答,因此不要對完整句子進行 assertion。請對 skill 應輸出的識別碼,或要求輸出的 schema 欄位進行 assertion,並縮小 fixture,以降低每次執行的成本。
在 CI 中加入 --bare。如果未加入,claude -p 會載入互動工作階段會使用的相同 context,包括 hooks、plugins,以及執行主機上的 CLAUDE.md,因此團隊成員的個人設定可能改變結果。Bare mode 會略過自動探索,但明確透過 --add-dir 指定的目錄下 .claude/skills/ 中的 skills 除外;它會略過此處要測試的 project skill,因此請明確載入該 skill。Bare mode 也不會讀取 subscription login,因此請先在環境中設定 ANTHROPIC_API_KEY:
claude --bare -p "/team-skills:api-review Read fixtures/orders-api.md and list the rule ids it breaks." \
--plugin-dir vendor/agent-skills \
--allowedTools "Read" \
--output-format json使用 --plugin-dir 載入的 plugin 會從 .claude-plugin/plugin.json 取得名稱;如果沒有該 manifest,則會以其目錄名稱命名。請將包含 "name": "team-skills" 的 plugin.json 放在 skills repository 中、catalog 旁邊,否則上方的指令必須改為呼叫 /agent-skills:api-review。
搭配 --output-format stream-json 時,system/init event 會回報已載入的 plugins,並在 plugin_errors array 中列出未載入的 plugins。除非 startup events 先發生,否則它會開啟該串流。當 plugin_errors 非空時,請讓 CI job 失敗。這可捕捉指向已不存在 revision 的 pin;否則 agent 只會安靜地忽略你的團隊規範。
可執行的指令
有兩項功能會讓這個說法成為字面上的事實,而當檔案來自其他團隊時,兩者都很重要。
首先,SKILL.md 可在模型讀取任何內容前執行 shell 命令。內文中的下列行會觸發預處理:
- Current branch: !`git rev-parse --abbrev-ref HEAD`命令會在載入該 skill 的機器上執行,其輸出會取代模型收到文字中的預留位置。以三個反引號開頭、後接 ! 的圍籬區塊,也會以相同方式執行多個命令。這些操作在執行期間都不會提示使用者。Claude Code 會依據權限規則檢查每個命令。在非自動模式下,權限規則不允許的命令會使 skill 中止,除非 skill 透過下方的第二項功能預先核准該命令。Deny 與 ask 規則仍會覆寫這項預先核准。讀取共用 skill 就等於讀取其中的命令替換內容。
其次,frontmatter 可以預先核准工具。allowed-tools 會在呼叫 skill 的該次操作中,核准清單中的工具而不顯示權限提示。Workspace trust 不會限制這項核准:即使在使用者未信任的資料夾中執行 -p,Claude Code 仍會套用專案 skill 的 allowed-tools。Claude Code 文件清楚說明其後果:skill 可以授予自身廣泛的工具存取權,因此在該儲存庫中執行 Claude Code 前,請檢查儲存庫內 skill 的 allowed-tools。組織可以在受管理設定中設定 allowManagedPermissionRulesOnly,禁止專案 skill 與個人 skill 使用此欄位;這需要 Claude Code v2.1.282 或更新版本。
因此,請以處理相依性升級的方式處理 skill 升級。在機制允許的情況下,請以確切的 commit 鎖定版本,因為 tag 可能被重新指向,而 branch 本來就會持續移動。在鎖定權限的機器上,設定中的 "disableSkillShellExecution": true 會將每個命令替換為字面文字 [shell command execution disabled by policy],而不實際執行命令;若透過受管理設定套用,使用者無法覆寫此設定。Bundled 與 managed skill 不受此設定限制。
同樣的注意事項也適用於 skill 讀取的內容。執行 env 或開啟設定檔的 skill,會將找到的內容載入模型的 context;這正是 讓機密資訊離開所執行的 agent 所涵蓋的問題。擷取頁面或執行查詢的 skill,則會將相同的暴露風險延伸到外部,因為擷取的文字會進入 context,看起來完全像是你撰寫的指令;在 讓 agent 使用你自己的 SearXNG instance 進行網頁搜尋 前,值得先了解這項邊界。
版本更新時的檢查重點
- 檢查每個
SKILL.md主體的差異(diff),因為該內容即為您的代理程式將遵循的指令。 - 檢查所有指令替換(command substitution),因為這些指令會在技能載入時於您的機器上執行。
- 檢查對
allowed-tools的任何變更,因為該行設定會直接授予工具存取權限而無需提示。 - 檢查標籤(tag)背後的測試執行結果。若共享儲存庫在 CI 中執行自有的冒煙測試(smoke tests),您所鎖定的標籤應具備綠色的測試通過紀錄。
若審閱者無法在 10 分鐘內讀完所有差異,代表該技能已過於龐大。請將其拆分。同樣的原則也適用於代理程式讀取的儲存庫文件:請將持久性規則保留在 AGENTS.md 與 HUMAN.md 拆分 中描述的檔案內,並將架構邏輯記錄在 專為代理程式編寫的 DESIGN.md 中,讓技能維持在狹窄且具體的程序。
當模型或工具變更導致技能失效
即使未經編輯,技能底層的環境仍可能發生變動。模型升級會改變其遵循長指令的可靠性,導致原本能執行到第九步驟的技能可能中斷。命令列工具若重新命名旗標,代理程式會執行舊旗標、讀取錯誤訊息並嘗試即興修正。若參考的 URL 回傳 404 錯誤,也會導致失敗。代理程式的調度機制若改變了技能選擇邏輯,原本能勝出的 description 可能不再被選中。當程序開始提前終止時,單純的版本更新無法解決問題,指令本身需要具備強制執行最後步驟的結構,這正是 unlazy skill 與其 Depth Tree 方法 背後的設計思路。
這就是為什麼在此架構中,冒煙測試(smoke test)至關重要。請排程執行每項技能的測試,並在每次推送程式碼時同步觸發。Google 基於此原因,每週針對整個函式庫執行評估作業;對於擁有十項技能的團隊而言,在小型 VPS 上設定每週一次的 cron job 即已足夠。這是開發者察覺損壞前,唯一能獲取通知的管道。
可攜性也有所幫助。Agent Skills 規範將前言(frontmatter)限制為六個鍵值,因此符合該規範的技能可載入至您編寫時所用的工具以外的環境;反之,您新增的每個特定於調度工具的鍵值,都是對單一供應商的押注。編寫能適應模型更換的技能是一門專業,相關內容請參閱 讓技能在任何模型上運作。
FAQ
如何在多個儲存庫共用同一項代理程式技能?
將技能放在專用的 git 儲存庫中,為其版本建立標籤,並讓各個使用專案參照標籤,而不是複製檔案。有兩種方式可行。git submodule 會記錄確切的 commit,從 .claude/skills/<name> 建立指向該 submodule 的符號連結後,技能就會以一般專案技能的形式載入。Plugin marketplace 則透過 /plugin 執行相同工作,並在使用端儲存庫的 .claude/settings.json 中宣告固定版本。這兩種方式都會將版本納入 git 歷史,因此可以追溯產生特定代理程式執行結果的指示。
可以將代理程式技能固定到特定版本嗎?
不能在 SKILL.md 內完成,因為該 frontmatter 沒有 version 鍵。版本固定必須由檔案外層的機制處理。git submodule 原本就會固定確切的 commit。在 Claude Code plugin marketplace 中,plugin source 可使用 ref 指定 branch 或 tag,並使用 sha 指定確切的 commit;兩者同時存在時,以 sha 為準。marketplace source 本身可使用 ref 指定 branch、tag,或在 Claude Code v2.1.324 及更新版本中指定完整的小寫 commit SHA。建議固定 commit,因為 tag 在審查後仍可能被重新指向其他內容。
技能的 smoke test 應驗證哪些內容?
應驗證穩定的內容。以非互動方式對包含已知錯誤的 fixture 執行技能,然後確認輸出中出現特定識別碼,例如技能應回報的規則 id。使用 --output-format json 和 --json-schema 要求結構化輸出,可讓檢查結果精確;jq -e 會在缺少該值時使指令碼失敗。不要驗證完整句子,因為模型在不同執行期間可能會改寫回答。
從其他團隊的儲存庫安裝共用技能是否安全?
應將其視為程式碼相依性,因為它是可執行的指示。SKILL.md 可在載入時透過 ! command substitution 形式執行 shell commands,而 frontmatter 的 allowed-tools 欄位可在不提示的情況下預先核准工具。每次更新版本時都應檢視 diff,固定到確切的 commit 而不是 branch,並優先使用由自有團隊控制的來源。在受管理的機器上,設定中的 "disableSkillShellExecution": true 會阻止 user、project、plugin 及 additional-directory skills 執行 command substitutions;bundled 和 managed skills 不受此限制。
共用技能能在 Claude Code 以外的代理程式中運作嗎?
這取決於使用哪些 frontmatter。Agent Skills 規格定義 6 個鍵:name、description、license、compatibility、metadata 和 allowed-tools。若技能只使用這些鍵,就能在實作該規格的工具之間載入,也能在 Claude Code 中直接載入,不需修改。規格以外的特定 harness 鍵與內文功能,會在其他工具中被忽略或拒絕;因此,預計廣泛共用的技能應避免使用這些內容。