1. 120 技能到底哪一步先崩先說清楚我講的“Agent Skill”指什么不是幾十行的提示詞片段而是包含SKILL.md描述、入口腳本、示例參數(shù)和配套資產(chǎn)的一整套能力目錄。早期我只有十幾個技能放在一個文件夾里完全沒有壓力隨手就能定位。后來數(shù)量爬過五十個我開始試圖分類爬過一百個尤其是超過 120 個之后我發(fā)現(xiàn)自己每次新增技能之前都要做一輪心理建設這個技能會不會和舊的重復舊的現(xiàn)在還能不能跑如果我改了某個入口哪些調用鏈會跟著斷真正把我逼到動手造“包管理器”的不是那次隨手數(shù)數(shù)而是連續(xù)踩中的三個實坑。1.1 先出問題的不是文件亂是“同名不同行為”開始互相打架第一個坑是命名沖突。聽起來很小兒科實際相當惡心。我的技能庫里出現(xiàn)過兩個都叫web_extract的技能一個是從普通網(wǎng)頁抽正文另一個是給特定結構化接口做爬蟲封裝。它們在運行時被注冊成同一個名字調用結果完全不可預期。當你只有十幾個技能時靠人腦記這種差異還不算離譜當你有上百個技能時靠記憶維護“同名但語義不同”的映射就是在給自己埋雷。名字問題背后其實是身份問題。技能不只是“一堆代碼”它應該擁有一個不可變身份知道它是什么版本、從哪里來、被誰維護。沒有身份技能和流浪代碼沒有分別短期能跑長期就是定時炸彈。1.2 手動分類和“前綴潔癖”撐不過三個月我也嘗試過不少土辦法結果各有各的尷尬。按業(yè)務功能建目錄pdf/、web/、email/、data/……聽起來合理但技能往往橫跨多個領域一個“導出網(wǎng)頁正文為 PDF”的技能你放哪個目錄都會覺得不對勁。用命名前綴做約束category__name__vX這種格式一開始挺清爽但版本一多就退化它只是把版本號塞進了名字里并沒有真正暴露版本關系。寫內部文檔登記天真的做法。文檔更新的速度永遠趕不上代碼變更的速度一周之后就沒人再看了。這三個方案共同的缺陷是它們只解決了“物理擺放”和“目視管理”沒有解決“源”和“同步”。目錄再整齊如果不知道技能的正式版本在哪、如何更新、如何回溯那它依然是一堆躺在磁盤里的未知文件。說句難聽的它們只是在給混亂做裝飾沒有真正引入秩序。1.3 真正致命的三個代價上下文、信任和技能發(fā)現(xiàn)到了 120 這個量級比目錄亂更嚴重的是三個系統(tǒng)性問題。上下文失控。我當時的架構會把技能的“描述頭”作為上下文注入模型。當技能數(shù)量超過一百個哪怕每個只占 300 token總開銷也有幾萬 token這還不算為了選出合適技能而進行的額外推理成本。結果就是模型被淹沒在大量“可能有用但當前用不上”的描述里真正該突出的意圖理解反而被削弱。信任崩塌。技能多了之后我沒法保證“這個技能是最近一次驗證過的版本”。有幾次我明明修好了一個 bug換到另一個項目環(huán)境卻發(fā)現(xiàn)舊行為又出現(xiàn)了因為那一份技能副本還是老的。這種“看似能跑但不敢依賴”的狀態(tài)比技能本身壞掉更消耗精力。技能發(fā)現(xiàn)困難。技能庫大到一定程度想找一件“我記得我做過”的能力非常耗時。明明是自己的資產(chǎn)卻像在舊倉庫里翻箱子而且大多數(shù)箱子沒有標簽。搜索、定位、判斷是否適合自己的需求這些動作的耗時已經(jīng)超過寫一個新技能的成本于是你會本能地選擇重寫然后制造出第 121 個重復輪子。到這個階段我意識到我需要的不再是“再整理一次文件夾”而是一個類似操作系統(tǒng)包管理器的東西能回答四個基本問題技能從哪里來、裝到哪去、怎么升級、怎么刪除。答案拆開就是標題里那兩句話——倉庫是源鏈接是安裝。2. 從 Linux 包管理器和 Maven 生態(tài)里偷師的三件事包管理器不是什么新鮮概念。Linux 下的 apt/yum、Java 生態(tài)的 Maven、Python 的 pip、前端世界的 npm都是已經(jīng)運行了十幾二十年的成熟模式。動手之前我專門把它們的共同點拆出來看了一眼發(fā)現(xiàn)真正核心的其實只有三條。2.1 倉庫是“唯一事實源”包管理器的第一性原理是讓所有客戶端面對同一個事實源。apt 的源倉庫、Maven 中央倉庫、npm registry、Docker Hub本質都是同一個角色定義“什么東西存在、什么版本可用、什么內容被正式認可”。Skill 生態(tài)缺的正是這一層。大多數(shù)人的技能散落在個人目錄、GitHub 倉庫、公司共享盤里每個人拿到的都是某個時間點的副本。副本之間沒有同步機制也就談不上“正式版”。當我決定把“倉庫”作為基礎設施時我給自己定了一條規(guī)則任何技能只要沒有被提交到倉庫就不算存在。所有安裝、更新行為都以倉庫里的內容為準。這條規(guī)則聽起來簡單但它把“我這臺機器上有什么”和“系統(tǒng)里應該存在什么”明確分開了。前者是本地狀態(tài)后者是倉庫權威。很多所謂的版本混亂本質上就是這兩個集合長期不一致造成的。2.2 鏈接是“安裝的最小可尋址單元”我喜歡 Maven 的一個細節(jié)依賴坐標是groupId:artifactId:version一個三元組就能唯一定位一個制品。它把“從哪來”和“怎么裝”解耦了。鏈接作為安裝手柄是同樣輕量的思路。所謂“鏈接是安裝”實際含義是安裝動作的參數(shù)是一個 URL而不是一個復制命令。這個 URL 指向倉庫里某個技能的唯一入口。安裝程序通過解析 URL獲得技能的清單、文件清單、版本信息和來源信息然后把技能落地到本地并在本地索引里記錄“這個技能從哪個 URL 安裝”。相比“手工把技能目錄拷貝到某個位置”鏈接的價值有三點可追溯URL 本身就是溯源記錄隨時能翻回去看安裝時拿的是什么內容?？筛庐攤}庫里更新了同一 URL 下的內容可以顯式升級?？沈炞C有效鏈接證明資源仍然存在于權威源中拷貝出來的目錄則沒有任何證明。2.3 我刻意沒有做的事傳遞依賴解析Maven 的依賴樹解析確實強大但對 Agent Skill 來說一上來就做傳遞依賴管理我認為是錯的。原因一技能的“依賴”在 Agent 上下文里更多是“推薦配套使用某個工具”而不是編譯期的 class 依賴。一個 PDF 提取技能可能希望 Agent 同時具備 OCR 能力但這不應該是強制安裝的。如果把它做成運行時強依賴安裝鏈會變得非常脆弱。原因二依賴解析會引入大量重復檢查和版本沖突問題早期版本如果卡在這一步整個項目根本走不到“能用”的階段。我采用的折中方案是在SKILL.md元數(shù)據(jù)里聲明recommended_skills和environment安裝器只展示提示不自動解析安裝。從實際效果看這已經(jīng)覆蓋了絕大多數(shù)場景。提示先做最小可用版本把“包管理器”跑起來比設計一個完美的依賴解析器重要得多。依賴問題等真遇到了再補不要提前自嗨。3. 一個周末跑通最小可用版?zhèn)}庫、清單文件和安裝器這個項目的實施時間比預想短很多核心原因是我沒有把“包管理器”做成一枚火箭而是用了最樸素的“Git 倉庫 JSON 索引 一個 CLI”組合。3.1 SKILL.md 清單規(guī)范7 個字段就夠每個技能在倉庫里占一個目錄目錄內至少有一個SKILL.md作為描述文件。字段我規(guī)定為字段必填用途name是技能唯一 IDversion是semver 版本號description是給 Agent/模型看的調用說明entry是入口文件與主函數(shù)定位author否維護者方便追溯license否使用時的約束recommended_skills否建議搭配的能力列表不自動安裝我最想提醒后來人的一點description是寫給你電腦里的模型看的不是寫給人看的。它是模型判斷“這個技能適不適合當前任務”的關鍵依據(jù)。描述里應當說明“它做什么、什么時候不應該用、需要哪些輸入”。不少技能被我拒絕進倉庫就是因為描述寫得太抽象比如“對文本進行深度處理”——這句話對模型毫無幫助。一個合格的描述大概長這樣Extract main text content from an HTML page and convert it to clean Markdown. Useful for article reading, content archiving, or building datasets. Do NOT use for image-based PDF files; those need the ocr-pdf skill. Input: a URL or local HTML file path.后半段“什么時候不該用”特別重要它能讓 Agent 在調用前做出更好的篩選。3.2 倉庫結構一個 Git 倉庫加一個索引文件倉庫目錄結構長這樣skillhub/ ├── index.json ├── skills/ │ ├── web/ │ │ ├── pdf-extractor/ │ │ │ ├── SKILL.md │ │ │ ├── main.py │ │ │ └── assets/ │ │ └── page-reader/ │ └── email/ │ └── summary/ │ ├── SKILL.md │ └── summary.py └── releases/ └── skillhub-v1.0.0.jsonindex.json是給搜索用的快速索引內容是一個簡單數(shù)組[ { name: pdf-extractor, version: 1.2.0, path: skills/web/pdf-extractor, tags: [pdf, extract, text] } ]為什么要有index.json而不是直接讓 CLI 去遍歷倉庫因為遍歷一個完整 Git 歷史很慢尤其在倉庫變大之后。一個輕量索引可以把“搜索”這個高頻操作降到毫秒級而索引生成完全可以交給 pre-push 鉤子或 CI 腳本。3.3 安裝協(xié)議一個 URL 從解析到落地的完整鏈路這是“鏈接是安裝”最直接的體現(xiàn)。安裝命令的調用長這樣skillhub install https://gitee.com/myorg/skillhub/raw/main/skills/web/pdf-extractor/SKILL.mdCLI 拿到 URL 之后執(zhí)行五步操作下載清單獲取SKILL.md原文。字段校驗檢查name、version、entry三個必備字段是否存在且格式正確。本地落盤把技能目錄完整放到本地技能區(qū)local_skills_dir/category/name/保留元數(shù)據(jù)。寫入溯源記錄在本地索引中記錄{name, version, source_url, installed_at}。輸出加載信息打印技能入口路徑和推薦描述方便接入 Agent 時直接引用。我建議安裝協(xié)議適配 Git raw 地址 release 標簽而不是把 URL 指向分支。分支是可變的今天裝的是這個版本明天可能就變。release 標簽才具有不可變性。這也是我后來控制“鏈接漂移”的關鍵設計。3.4 CLI 提供五個動詞足夠了CLI 最終只暴露了五個命令基本對標 npm 和 apt 的用戶直覺skillhub search keyword搜索公共倉庫里的技能。skillhub info name查看技能描述和版本。skillhub install urlURL 安裝。skillhub remove name移除本地技能并同步索引。skillhub verify檢查本地索引和實際文件目錄是否一致。實現(xiàn)上也不復雜我用 Node.js 寫了大概兩百行的 CLI用原生fetch下載列表和文件用本地 JSON 文件維護索引整個過程沒有引入任何重量級依賴。如果你想在團隊里復刻用 Python 也一樣核心邏輯是相通的。4. 把 120 個散裝技能遷移進“倉庫”的完整過程方案在技術上不難真正的難點是遷移。下面我把遷移過程完整復盤一遍盡量保留細節(jié)。4.1 先盤點不要急著建倉庫我第一天沒有建任何倉庫而是先寫了一個掃描腳本把現(xiàn)有技能內容、入口、依賴、大小全部扒了出來。這一步的價值遠超預期。掃描完全量目錄后我拿到了第一組準確數(shù)據(jù)。原本我預期有 120 個技能實際共 137 個目錄。其中約 40 個明顯是重復或廢棄副本。最后真正有維護價值、需要保留的大約占一半。沒有第一步盤點后面所有“整理”都是盲目的。盤點時的關鍵動作掃描全量技能對每個技能目錄生成 SHA-256。后面用來比對重復版本。按名稱聚類找出功能雷同的候選。列出“最近半年沒有調用記錄”的技能作為僵尸技能候選。4.2 清洗與補元數(shù)據(jù)合并重復補寫描述盤點完成后進入清洗階段前后花了三天。我總結了三個原則重復內容合并。最典型的是網(wǎng)頁提取不同時期寫了好幾個變體。最終合并成一個穩(wěn)定版本廢棄其他。無描述技能一律補寫。凡是描述少于 20 個字的技能必須補上“做什么、什么時候不用”才允許入庫。入口無法驗證的技能標記為待定。不確定能否跑通的在清單里標成status: pending。它不會進入正式索引但會保留在檔案區(qū)。這比直接刪除更容易讓人接受。最后確認 15 個僵尸技能徹底廢棄其余確認保留。4.3 入庫與索引生成分類只是主域標簽承載跨域清洗完之后才是“建倉”。我按業(yè)務域做了分類web/、pdf/、email/、data/、prompt/、misc/。分類過程被“技能橫跨多個領域”這個現(xiàn)實打臉了好幾次。解決辦法是允許一個技能歸屬多個標簽但目錄只選擇主域。一份tags字段承擔跨域標記比如 PDF 提取技能放在web/但 tags 同時帶上pdf、extract、ocr。在每個技能目錄里SKILL.md的格式和現(xiàn)有 Agent 工具生態(tài)保持一致。這意味著遷移后Agent 側加載模塊不需要做額外適配老調用方式依然工作。4.4 首次安裝演練一次性發(fā)現(xiàn)兩個實際問題倉庫搭建完成后我在一個干凈臨時目錄里從頭執(zhí)行了一次安裝流程第一次就暴露了兩個問題。案例 A只復制主腳本忘了配套資源。有些技能入口調用了同目錄下的輔助文件但遷移時我只拷貝了主腳本沒有拷貝assets/目錄。安裝產(chǎn)物在資源加載時直接缺失。修正很快但它讓我意識到入庫校驗必須檢查入口引用的本地文件是否都在目錄里。后來我加了一段靜態(tài)分析腳本掃描入口源文件中的所有相對引用。案例 B鏈接失效。一個技能清單里記錄的原始 URL 是舊位置遷移后這個 URL 已經(jīng) 404。這提醒我安裝 URL 是硬約束每次更新倉庫中的技能都要同步更新source_url并把技能文件放到倉庫的 release 附件中。后來我還加了一條 CI 任務定期檢查所有鏈接的有效性發(fā)現(xiàn)死鏈直接告警。5. 四個最容易翻車的環(huán)節(jié)以及我踩過的坑遷移上線只是開始后續(xù)維護才真正考驗設計。下面按四個月的實際使用把最容易翻車的環(huán)節(jié)講清楚。5.1 鏈接漂移把 URL 指向分支是最隱蔽的坑如果你把安裝 URL 指向 Git 分支比如raw/main/skills/...在某個時間點它是有效的。但分支內容是可變的。當我修改技能并推送到 main 之后所有之前“裝過這個版本”的機器表面沒有變化但再重裝拿到的是另一個內容。想要診斷到底裝的哪個版本全靠source_url溯源記錄。解決辦法為每個技能發(fā)布版本時打tag安裝 URL 統(tǒng)一指向 release 標簽對應的 raw 路徑。這樣安裝動作就是可重復的分支只承擔開發(fā)流不承擔安裝流。5.2 安裝天然帶代碼執(zhí)行風險“鏈接是安裝”聽起來方便但外部鏈接拉下來直接執(zhí)行等同于把一個陌生人請進家。我對此做了四件事建議所有的接入方都照做默認安裝器不執(zhí)行技能里的任何安裝腳本只負責把文件復制到本地。manifest 只允許白名單入口類型比如python: main.py或node: index.js對 shell 等高危入口直接拒絕。公共倉庫里的技能必須經(jīng)過審閱沒有 review 不允許合入。安裝時完整記錄source_url出事以后第一時間回溯源頭。提示凡是來自公開鏈接的技能默認按“不可信代碼”處理。先審閱再使用不要嫌麻煩。5.3 團隊協(xié)作時提交紀律比工具本身更決定成敗如果你只是一個人在倉庫里操作你只需要解決自己那部分問題。團隊協(xié)作時剩下 40% 的成敗取決于 merge 紀律。我見過最典型的反面案例有人直接 push 一個技能進倉庫沒有描述沒有入口驗證結果別人安裝完根本跑不起來。后來我在倉庫里加了 PR 模板要求必須包含變更說明一條可執(zhí)行的示例對應SKILL.md的前端描述同步。同時在 CI 里加了 schema 校驗字段不齊或版本號不合法直接阻止合并請求。這一步看起來死板但實際把“入庫即可用”這條標準落到了機器層面。5.4 離線環(huán)境和內網(wǎng)部署依然可以跑起來這套模型不要求必須連公共網(wǎng)絡。因為“倉庫是源”你只要把 Git 倉庫同步到內網(wǎng)機器用 Nginx 或任何靜態(tài)服務器托管 skills 目錄安裝 URL 改成內網(wǎng)地址即可?？蛻舳藗鹊谋镜厮饕耆蛔?。用到私有化交付時甚至可以做一個skillhub bundle命令把倉庫和索引導出成一個 tar 包拿到離線環(huán)境里直接安裝。這比每次到客戶現(xiàn)場都要重新配一套網(wǎng)關舒服得多。6. 四個月后我重新理解了 Agent Skill 治理6.1 實際感受到的差異這套體系跑通之后變化最明顯的有三點。第一是維護成本。以前調整一個技能要擔心有沒有同步到每個環(huán)境現(xiàn)在統(tǒng)一提交到倉庫更新策略非常清晰。第二是技能發(fā)現(xiàn)效率。我直接通過 CLI 搜索從整個庫存里篩出某個域內的可用技能不靠印象也不靠翻 Notion。第三是上下文控制。技能打上標簽后Agent 加載技能以需求為維度而不是把全部技能塞進上下文。我自己的記錄里新增一個技能從“半天也沒定下來”縮短到十幾分鐘技能召回的準確率也明顯提升。這種改善不是因為某個功能特別炫而是因為“先搜索、再安裝、再加載”的鏈路把心智負擔從人腦轉移到了工具上。6.2 什么時候不需要自己造這套東西如果你手頭只有十個以內的技能且只給自己一個人用建議不要造。包管理器是治理型工具只有當維護成本顯著高于工具本身的建設成本時才值得動手。市面上也已經(jīng)有一些現(xiàn)成的 skill marketplace 和 MCP 生態(tài)能覆蓋一部分場景。但如果你和我當時的情況很像——幾十甚至上百個技能需要在多個環(huán)境同步、需要多人協(xié)作、需要不斷做版本迭代——那么一個最小可用的包管理器成本完全值得。6.3 下一步要補的能力指紋校驗、自動更新與分級權限現(xiàn)有版本還剩幾個想補的功能。第一個是簽名校驗在 manifest 里引入 sha256 指紋安裝時對比下載文件哈希防止內容被篡改。第二個是自動更新類似apt upgrade把倉庫的 index 與本地索引做 diff列出可升級項由用戶決定是否升級。第三個是分級權限把“可匿名安裝”和“需要審核安裝”分開尤其在團隊內給敏感技能的入口加一道審批。最后說一點個人體會。這次折騰讓我明白很多看似“管理混亂”的問題本質不是人的問題而是缺了一個抽象層。把技能當作包把倉庫當作源把鏈接當作安裝句柄——這個簡單的映射比任何“再整理一次文件夾”的努力都要穩(wěn)妥。工具不必一開始就完美先把“倉庫是源鏈接是安裝”這兩條原則落地后面的問題會自然消解一大片。