Skills管理最佳實踐，skills-lock.json
整理版優先睇
skills-lock.json 係鎖住 Agent skill 版本嘅鎖文件，確保重現性同完整性，作者分享咗佢喺 verysmallwoods 倉庫嘅實際使用經驗
呢篇文章出自作者喺 verysmallwoods 倉庫嘅實戰經驗。佢一開始裝咗二十幾個 Agent skill，最近清理到剩低五個常用嘅，趁機會分享 skills-lock.json 嘅用法。作者想解決嘅問題係：Agent skill 愈來愈多，點樣確保團隊同未來嘅自己可以裝到完全一樣嘅版本？點樣防止上游改咗內容而本地唔知？鎖文件就係為咗呢兩件事而設——用 SHA-256 哈希鎖死每個 skill 嘅版本，做到重現性同完整性。
鎖文件背後由 Vercel Labs 團隊維護，格式穩定，CLI 持續迭代。管理上好直接：用 npx skills 嘅 add、check、experimental_install 三個命令搞掂。作者嘅實踐包括：將鎖文件 commit 入 git、所有操作只用 CLI、唔好為對稱而硬拆鎖文件、升級前先 check 再 add、新機器只跑 experimental_install、source 可信度永遠第一、同埋用鎖文件就等於綁定咗成個 CLI 工具鏈。
整體結論係：skills-lock.json 係管理 Agent skill 版本嘅有效工具，只要跟實呢套做法，就可以解決環境不一致嘅問題，做到「環境對得上」由靠記憶變為靠文件。
- skills-lock.json 用 SHA-256 哈希鎖死每個 skill 版本，確保團隊同 CI 裝到同一份，解決重現性同完整性問題。
- 管理工具係 npx skills CLI，三個主要命令：add（新增）、check（對比更新）、experimental_install（精確還原）。
- 作者唔建議為對稱而硬拆鎖文件——子項目冇獨立 skill 集合就唔使另開鎖文件，全倉庫一份鎖就夠。
- 升級流程：先跑 npx skills check 睇下邊啲有更新，再決定用 npx skills add 重新裝，避免盲升。
- 鎖文件解決版本一致性，但唔代表 source 可信——你要自己判斷 add 嘅 GitHub repo 值唔值得信，hash 只防篡改唔防來源風險。
npx skills CLI
管理 skills-lock.json 嘅命令行工具，由 Vercel Labs 維護。支援 add、check、experimental_install 等命令。
Skills註冊表
瀏覽同發現 Agent skill 嘅官方目錄。
skills-lock.json 係咩？點解要用？
Agent skill 係俾 AI agent 用嘅可複用能力包，通常係一份 SKILL.md。用嘅時候兩大問題好快出現：重現性（團隊成員、CI、未來嘅你能唔能裝到同一份？）同完整性（上游改咗內容你本地知唔知？）。
skills-lock.json 就係為咗呢兩件事而生，用 SHA-256 哈希做兜底校驗，鎖死「我而家裝嘅係邊一份」。
佢嘅角色同 package-lock.json 之於 npm、composer.lock 之於 PHP 一樣——將安裝狀態寫死落文件，git 跟蹤住，人唔好手動改。
背後維護團隊同工具鏈
鎖文件格式同 npx skills CLI 都係由 Vercel Labs 團隊維護，同 package-lock.json 由 npm 團隊維護一個位。呢個意思係格式相對穩定，可以當長期方案用。
唔使擔心係某個個人項目，隨時可能冇人維護。
管理上直接簡單：CLI 寫入，git 跟蹤，人唔好手動改。改 skill 集合嘅命令（add、update、remove）先會寫入鎖文件；install 方向相反——佢讀鎖文件並還原版本，唔會反過嚟改鎖。
experimental_install 嘅行為同 npm ci 一樣，嚴格按鎖文件裝，唔接受不一致狀態。
鎖文件結構逐個睇
{
"version": 1,
"skills": {
"frontend-slides": {
"source": "sugarforever/frontend-slides",
"sourceType": "github",
"skillPath": "SKILL.md",
"computedHash": "bbf3664513fba5704c63a1b1425d0fc71c10ff48df7e419b193167299bed3931"
},
"personal-chinese-writing-style": {
"source": "sugarforever/01coder-agent-skills",
"ref": "main",
"sourceType": "github",
"skillPath": "skills/personal-chinese-writing-style/SKILL.md",
"computedHash": "19b40f9180c02ab9a9706e30c6e7a2aa9abcce70f942a89e8f5bf49769526521"
}
}
}每個字段都好直白：source 係 GitHub repo 路徑，sourceType 目前得 github，skillPath 係倉庫入面 SKILL.md 嘅位置，computedHash 係安裝時計嘅 SHA-256。ref 可選，預設係 HEAD，如果想釘到特定分支或 commit 就顯式寫出嚟。
鎖文件只記引用版本，唔存內容，實際文件喺 .agents/skills/<name>/ 下。
每日三個命令搞掂
- 1 新增 skill：npx skills add <owner>/<repo>，從 GitHub 拉落嚟並寫入鎖文件。
- 2 對比更新：npx skills check，比較本地哈希同上遊有冇唔同，決定係咪要升級。
- 3 精確還原：npx skills experimental_install，按鎖文件裝返曬所有 skill，團隊同步或 CI 必用。
experimental_install 個名容易誤解，其實佢係嚴格還原，唔會順手更新鎖文件。
作者嘅真實實踐（verysmallwoods 倉庫）
- 鎖文件一定要 commit 入 git，唔 commit 等於冇用。
- 所有變更只透過 CLI 產生，唔好手改鎖文件，否則下次 CLI 會同實際安裝對唔上。
- 唔好為咗對稱而硬拆鎖文件——作者最初 backend/ 子項目另外整咗份鎖，後來發現 backend 係 Cloudflare Worker 唔跑 Agent skill，即刻刪咗。判斷標準：子項目有冇自己唔重疊嘅 skill 集？冇就唔好拆。
- 升級流程：先 check 再 add，唔好盲升。
- 新機器拉代碼後，三步搞掂：git pull → 裝依賴 → npx skills experimental_install。
- source 可信度永遠第一，hash 只係兜底防篡改。你 add 嘅 repo 靠唔靠得住要自己判斷。
- 用鎖文件就等於綁定咗 npx skills CLI 工具鏈，繞過佢就冇重現性。
我用 skills-lock.json 管 verysmallwoods 倉庫入面嘅 Agent skill 有一段時間㗎喇 - 最高峯裝到二十幾個，最近做咗一輪清理，刪到 frontend-slides、open-design、prototype、yourwebs、personal-chinese-writing-style 五個常用嘅。藉住今次清理嘅機會傾下鎖文件 - 佢係咩、邊個喺背後維護、解決咗咩問題、我喺項目入面點樣用，同埋一啲自己摸索出來嘅實踐。希望對大家有幫助。
skills-lock.json 解決咩問題
先講下：Agent skill 係俾 AI agent 用嘅可複用能力包，通常係一份 SKILL.md（或者一組配套文件），話俾模型知「碰到 X 任務時就按呢套套路做」。Claude Code、Vercel 嘅 agent toolkit 等都係跟呢個範式運作。
Skill 多咗之後，兩個問題即刻出現：
重現性：我裝嘅版本，團隊成員、CI、未來嘅我，係咪裝到一模一樣嗰份？ 完整性：Skill 係公開倉庫入面嘅 markdown，今日 add 一次、聽日上游改一行，我本地呢份就同當初睇嘅唔係同一份喇。
skills-lock.json 就係為咗呢兩件事而生。佢係項目級嘅鎖文件，同 package-lock.json 之於 npm、composer.lock 之於 PHP 嘅位置一樣 - 將「我而家裝嘅到底係邊一份」寫死，並用 SHA-256 哈希做兜底校驗。
鎖文件背後
圍繞 skills-lock.json 呢套工具鏈嚟自 Vercel Labs - 鎖文件格式同 npx skills CLI 都係呢個團隊喺維護，同 package-lock.json 由 npm 團隊維護一個位置。呢個意味住格式相對穩定，CLI 亦持續迭代，可以當作長期方案用，唔使擔心係某個個人項目第日冇人維護。
管理上亦都好直接：CLI 寫入，git 追蹤，人唔使動手。改 skill 集合嘅命令（add、update、remove）先會寫呢份文件；experimental_install 方向相反 - 佢讀鎖文件，將裏面記嘅版本還原到 .agents/skills/ 下面，唔會反方向改鎖。我將鎖文件同代碼一齊 commit；手動改佢嘅後果同手動改 package-lock.json 一樣 - 下次 CLI 行會同實際安裝對唔上。
文件係點樣
直接俾我哋睇倉庫根目錄 skills-lock.json 入面嘅兩條：
{
"version": 1,
"skills": {
"frontend-slides": {
"source": "sugarforever/frontend-slides",
"sourceType": "github",
"skillPath": "SKILL.md",
"computedHash": "bbf3664513fba5704c63a1b1425d0fc71c10ff48df7e419b193167299bed3931"
},
"personal-chinese-writing-style": {
"source": "sugarforever/01coder-agent-skills",
"ref": "main",
"sourceType": "github",
"skillPath": "skills/personal-chinese-writing-style/SKILL.md",
"computedHash": "19b40f9180c02ab9a9706e30c6e7a2aa9abcce70f942a89e8f5bf49769526521"
}
}
}啲欄位意思都好直接：
source：Skill 喺邊度嚟。GitHub repo 路徑，owner/repo形式。sourceType：來源類型。目前係github。skillPath：倉庫入面SKILL.md嘅具體位置。同一個 repo 可以暴露多個 skill。computedHash：裝入時計算嘅 SHA-256。上游內容變咗，哈希會對唔上。ref（可選）：追蹤嘅 git ref。默認係倉庫 HEAD；如果想釘到具體分支、tag 或 commit 上，就顯式寫出來 - 上面嗰個personal-chinese-writing-style就釘在main分支。
鎖文件本身唔儲存 skill 內容；skill 嘅實際文件落喺 .agents/skills/<name>/ 下面。鎖文件只記一件事 - 我引用嘅係邊一份。
npx skills 三件套
日常基本就係呢三個動作：
# 新增 skill：從 GitHub 拉下來，把這次安裝寫進 skills-lock.json
npx skills add <owner>/<repo>
# 對比本地哈希和上游：看有沒有更新可用
npx skills check
# 按鎖文件精確還原所有 skill：團隊同步 / CI 必用
npx skills experimental_installexperimental_install 呢個名最容易令人誤解 - 聽落似 install 類操作，會順手更新鎖文件，但佢嘅行為其實同 npm ci 一回事，嚴格按鎖文件裝，唔接受鎖文件同實際安裝不一致嘅狀態。換部機、換條分支、CI 拉新代碼，行一次就知道環境係咪齊全。
我喺呢個倉庫入面嘅幾條實踐
下面係我喺 verysmallwoods 入面嘅真實做法。唔係放諸四海皆準，但每一條都係為咗解決具體問題。
將鎖文件提交入 git。skills-lock.json 同代碼一齊入版本控制係呢個機制用得成嘅前提 - 唔 commit，就等於冇用鎖文件。所有變更只透過 CLI 產生：add 寫入、check 比對、install 還原。
唔好為咗對稱夾硬拆鎖文件。 我一開始都喺 backend/ 子項目入面單獨建立咗一份 skills-lock.json，諗住等前後端各自管理，同兩份 package.json 對稱。後來發現 backend/ 係個獨立部署嘅 Cloudflare Worker，根本唔行 Agent skill，嗰份鎖就係個空殼，刪咗 - 而家成個倉庫一份鎖就夠。判斷標準好簡單 - 子項目有無佢自己、同主項目唔重疊嘅 skill 集合？冇就唔好拆。
升級流程：先 check 再 add。 想睇上游有無更新就跑 npx skills check，佢會列出本地哈希同上遊唔一致嘅條目。睇完輸出再決定係咪要升級；要升就用 npx skills add 重新裝，鎖文件會隨即同步更新。直接 add 都得，但係先行一次 check 可以避免「唔知改咗啲咩就升級」。
新機只做一件事：experimental_install。 拉代碼、裝依賴、npx skills experimental_install，三步搞掂 Agent skill 呢一層就齊全。呢個係鎖文件最大嘅意義 - 令「環境對得上」由靠記憶變成靠文件。
Source 嘅可信度永遠第一，hash 係兜底。 鎖文件解決嘅係「上游今日嘅樣同我當初安裝時係咪一致」，佢唔會幫你判斷「呢個 repo 一開始值唔值得信」。你 add 嘅係一個 GitHub repo 入面嘅 SKILL.md，嗰個 repo 本身嘅可信度你要自己睇。Hash 捉嘅係篡改，唔係來源風險。
用鎖文件就等於綁定咗一套 CLI。 引入 skills-lock.json 之後，成個項目嘅 skill 管理就同 npx skills 呢套工具綁埋一齊 - 團隊成員、CI、未來嘅我，都要用同一套 CLI 去 add / update / install。繞過佢（手動裝 skill、手動改鎖文件）嘅話，鎖文件會即刻同實際安裝對唔上，重現性就冇咗。呢個唔算壞事，但用之前要清楚：揀咗鎖文件，就揀咗配套嘅 CLI。
Vercel Labs skills CLI：github.com/vercel-labs/skills Skills 註冊表：skills.sh
我用 skills-lock.json 管 verysmallwoods 倉庫裏的 Agent skill 有一陣了 - 最高峯裝到二十來個，最近做了一輪清理，砍到 frontend-slides、open-design、prototype、yourwebs、personal-chinese-writing-style 五個常用的。借這次清理的機會聊一聊鎖文件 - 它是什麼、誰在背後維護、解決了什麼問題、我在項目裏怎麼用，以及一些自己摸出來的實踐。期望對大家有所幫助。
skills-lock.json 解決什麼問題
先交代一下：Agent skill 就是給 AI agent 用的可複用能力包，通常是一份 SKILL.md（或者一組配套文件），告訴模型「碰到 X 任務時按這套套路做」。Claude Code、Vercel 的 agent toolkit 等都在這個範式上跑。
skill 多了之後，兩個問題馬上冒出來：
重現性：我裝的版本，團隊成員、CI、未來的我，能不能裝到一模一樣的那一份？ 完整性：skill 是公開倉庫裏的 markdown，今天 add 一次、明天上游改一行，我本地這份就跟當初看的不是同一份了。
skills-lock.json 就是為這兩件事而生。它是項目級的鎖文件，跟 package-lock.json 之於 npm、composer.lock 之於 PHP 的位置一致 - 把「我現在裝的到底是哪一份」寫死，並用 SHA-256 哈希做兜底校驗。
鎖文件背後
圍繞 skills-lock.json 的這套工具鏈來自 Vercel Labs - 鎖文件格式和 npx skills CLI 都是這個團隊在維護，跟 package-lock.json 由 npm 團隊維護一個位置。這意味着格式相對穩定，CLI 也在持續迭代，可以當作長期方案用，不用擔心是某個個人項目某天沒人維護。
管理上也很直接：CLI 寫入，git 跟蹤，人不動手。改 skill 集合的命令（add、update、remove）才會寫這份文件；experimental_install 方向相反 - 它讀鎖文件，把裏面記的版本還原到 .agents/skills/ 下，不反向改鎖。我把鎖文件跟代碼一起 commit；手改它的後果跟手改 package-lock.json 一樣 - 下次 CLI 跑會跟實際安裝對不上。
文件長什麼樣
直接給我倉庫根目錄 skills-lock.json 裏的兩條：
{
"version": 1,
"skills": {
"frontend-slides": {
"source": "sugarforever/frontend-slides",
"sourceType": "github",
"skillPath": "SKILL.md",
"computedHash": "bbf3664513fba5704c63a1b1425d0fc71c10ff48df7e419b193167299bed3931"
},
"personal-chinese-writing-style": {
"source": "sugarforever/01coder-agent-skills",
"ref": "main",
"sourceType": "github",
"skillPath": "skills/personal-chinese-writing-style/SKILL.md",
"computedHash": "19b40f9180c02ab9a9706e30c6e7a2aa9abcce70f942a89e8f5bf49769526521"
}
}
}字段意思都直白：
source：skill 從哪兒來。GitHub repo 路徑，owner/repo形式。sourceType：來源類型。目前是github。skillPath：倉庫內SKILL.md的具體位置。同一個 repo 可以暴露多個 skill。computedHash：裝入時計算的 SHA-256。上游內容變了，哈希會對不上。ref（可選）：跟蹤的 git ref。默認是倉庫 HEAD；如果想釘到具體分支、tag 或 commit 上，就顯式寫出來 - 上面那個personal-chinese-writing-style就釘在main分支。
鎖文件本身不存 skill 內容；skill 的實際文件落在 .agents/skills/<name>/ 下。鎖文件只記一件事 - 我引用的是哪一份。
npx skills 三件套
日常基本就這三個動作：
# 新增 skill：從 GitHub 拉下來，把這次安裝寫進 skills-lock.json
npx skills add <owner>/<repo>
# 對比本地哈希和上游：看有沒有更新可用
npx skills check
# 按鎖文件精確還原所有 skill：團隊同步 / CI 必用
npx skills experimental_installexperimental_install 的名字最容易讓人誤讀 - 聽上去像 install 類操作，會順手更新鎖文件，但它的行為其實跟 npm ci 一回事，嚴格按鎖文件裝，不接受鎖文件和實際安裝不一致的狀態。換台機器、換條分支、CI 拉新代碼，跑一次就知道環境是不是齊的。
我在這個倉庫裏的幾條實踐
下面是我在 verysmallwoods 裏的真實做法。不是放之四海皆準，但每條都是為了解決具體問題。
把鎖文件提交進 git。skills-lock.json 跟代碼一起進版本控制是這個機制能用起來的前提 - 不 commit，等於沒用鎖文件。所有變更只通過 CLI 產生：add 寫入、check 比對、install 還原。
不要為了對稱硬拆鎖文件。 我一開始也在 backend/ 子項目裏單建了一份 skills-lock.json，想着讓前後端各管各的，跟兩份 package.json 對稱。後來發現 backend/ 是個獨立部署的 Cloudflare Worker，根本不跑 Agent skill，那份鎖就是個空架子，刪了 - 現在整個倉庫一份鎖就夠。判斷標準很簡單 - 子項目有沒有它自己、跟主項目不重疊的 skill 集合？沒有就別拆。
升級流程：先 check 再 add。 想看上游有沒有更新就跑 npx skills check，它會列出本地哈希和上游不一致的條目。看完輸出再決定要不要升級；要升就用 npx skills add 重新裝，鎖文件隨即同步更新。直接 add 也能用，但先跑一遍 check 能避免「不知道改了什麼就升上去」。
新機器只做一件事：experimental_install。 拉代碼、裝依賴、npx skills experimental_install，三步走完 Agent skill 這一層就齊了。這是鎖文件最大的意義 - 讓「環境對得上」從靠記憶變成靠文件。
source 的可信度永遠第一，hash 是兜底。 鎖文件解決的是「上游今天的樣子跟我當初安裝時是否一致」，它不替你判斷「這個 repo 一開始就值不值得信」。你 add 的是一個 GitHub repo 裏的 SKILL.md，那個 repo 本身的可信度你得自己看。Hash 抓的是篡改，不是來源風險。
用鎖文件就等於綁定一套 CLI。 引入 skills-lock.json 之後，整個項目的 skill 管理就跟 npx skills 這套工具綁在一起 - 團隊成員、CI、未來的我，都得用同一套 CLI 去 add / update / install。繞過它（手裝 skill、手改鎖文件）鎖文件馬上跟實際安裝對不上，重現性也就沒了。這不算壞事，但用之前要清楚：選了鎖文件，就選了配套的 CLI。
Vercel Labs skills CLI：github.com/vercel-labs/skills Skills 註冊表：skills.sh