議：可插拔AI技能的聲明式交付標準)
1. “agent-skills”不是功能模塊而是一套可插拔的能力交付協(xié)議你第一次在 GitHub 倉庫名里看到agent-skills或在 CLI 工具的--skills參數(shù)后跟一串路徑時大概率會下意識把它理解成“AI Agent 能做的幾件事列表”——比如“查天氣”“讀文件”“發(fā)郵件”。但實際踩過三次坑、重構過四版技能注冊邏輯后我才明白agent-skills的本質是一套輕量級、聲明式、面向運行時能力發(fā)現(xiàn)的接口契約Interface Contract它解決的從來不是“能做什么”而是“如何被發(fā)現(xiàn)、如何被安全調用、如何與上下文對齊”。這個認知偏差直接導致大量團隊在開發(fā)初期就陷入兩個典型困局一是把 skills 寫成一堆零散函數(shù)結果 agent 調度器根本識別不了二是強行塞進 OpenAPI Schema結果 runtime 解析失敗報錯信息只顯示skill not found in registry連具體哪一行配置錯了都看不到。為什么必須從“協(xié)議”角度理解看幾個熱詞就能印證zcode cli、codex cli、boos cli、openspec cli——它們全在用不同前綴封裝同一類行為通過 CLI 命令行工具將本地目錄中符合特定結構的代碼片段注冊為 agent 可感知、可調度、可審計的技能單元。而不是簡單地“加載一個 JS 文件”。再看claude agent skills: a first principles deep dive這個熱搜標題里的關鍵詞first principles第一性原理——它暗示的正是別急著寫代碼先定義清楚“一個 skill 在系統(tǒng)里究竟意味著什么”。比如它必須有一個唯一標識符不是文件名而是id: file-readv1這種帶命名空間和版本的字符串它必須聲明輸入?yún)?shù)的 JSON Schema不是 TypeScript interface而是 runtime 可校驗的 OpenAPI v3.1 subset它必須提供一個description字段且該字段會被 LLM 用于 zero-shot 工具選擇不是給人看的注釋而是 prompt engineering 的關鍵 token source它必須包含permissions聲明如fs:read:/home/user/**否則在 sandbox 環(huán)境中直接被攔截不報錯、不提示、靜默失敗。提示很多團隊用fs.readFile寫了個讀文件 skill卻沒在permissions里聲明文件路徑白名單結果在 Docker 容器里跑通了本地測試上線后所有文件操作全部返回空對象——因為 runtime 默認禁止一切 fs 操作除非顯式授權。我見過最典型的反模式是把skills/目錄當成普通工具函數(shù)庫來維護skills/ ├── weather.js # 導出一個 async function ├── send-email.ts # 導出一個 class └── db-query.py # 導出一個 main() 函數(shù)這種結構在agent-skills協(xié)議下是無效的。真正的技能包必須是自描述的、可獨立驗證的單元標準結構如下skills/file-read/ ├── manifest.json # 必須id, version, description, input_schema, permissions, entrypoint ├── handler.js # 必須導出默認函數(shù)簽名 (input: any) Promiseany └── README.md # 可選人類可讀文檔不影響 runtime其中manifest.json是協(xié)議核心。它不是配置文件而是技能的“身份證”。比如一個合法的file-readmanifest 長這樣{ id: file-readv2, version: 2.0.1, description: Read content from local file system. Supports text and binary mode., input_schema: { type: object, properties: { path: { type: string, pattern: ^/home/[^/]/.*$ }, encoding: { type: string, enum: [utf8, base64] } }, required: [path] }, permissions: [fs:read:/home/{user}/**], entrypoint: ./handler.js }注意三個關鍵點path字段用了正則約束^/home/[^/]/.*$這是為了防止路徑遍歷攻擊../../../etc/passwdpermissions中的{user}是 runtime 替換變量實際運行時會替換成當前 agent 用戶名實現(xiàn)租戶隔離entrypoint是相對路徑且必須指向一個 CommonJS 或 ESM 模塊默認導出函數(shù)不能是類或命名導出。這套協(xié)議之所以能成為事實標準是因為它同時滿足了三類角色的需求開發(fā)者不用改 agent 核心代碼只要按結構放文件CLI 就能自動注冊安全工程師所有權限聲明集中管控audit log 可追溯到具體 skill id 和調用上下文LLM 提示工程師description字段直接喂給模型配合input_schema自動生成 tool call JSON無需人工編寫 prompt 模板。所以當你看到agent-skills這個標題時請立刻切換思維它不是一個項目名而是一個協(xié)議名。就像 HTTP 不是某個網(wǎng)站的名字而是瀏覽器和服務器之間約定的通信規(guī)則。接下來的所有實操都建立在這個認知基礎上。2. CLI 工具鏈不是輔助而是協(xié)議落地的強制執(zhí)行層很多人以為zcode cli、codex cli、boos cli這些工具只是“方便安裝 skill 的命令行包裝”甚至覺得“手寫 manifest 手動 copy 到 skills 目錄”也能跑通。我在早期也這么干過——直到第 7 次因為manifest.json缺少version字段導致 agent 啟動失敗才徹底放棄手動維護。CLI 工具鏈在agent-skills生態(tài)里承擔的是協(xié)議合規(guī)性守門員Compliance Gatekeeper的角色。它不負責執(zhí)行 skill也不參與調度決策但它必須在 skill 注冊前完成三項不可繞過的靜態(tài)檢查2.1 Manifest 結構完整性校驗拒絕任何“差不多就行”的妥協(xié)CLI 會逐字段驗證manifest.json是否符合協(xié)議 schema。這不是簡單的 JSON 格式檢查而是深度語義校驗。例如id字段必須匹配正則^[a-z0-9][a-z0-9.-]*[a-z0-9][a-z0-9][a-z0-9.-]*[a-z0-9]$小寫字母/數(shù)字/點/短橫線以字母數(shù)字開頭結尾中間含分隔 name 和 versioninput_schema必須是有效的 OpenAPI v3.1 Schema Object且不能包含$ref引用runtime 不支持遠程引用permissions數(shù)組中每個字符串必須符合resource:action:scope三元組格式且scope部分必須是 glob pattern如/home/*/**不能是正則runtime 不解析 regex。我遇到過最隱蔽的坑是input_schema里寫了type: integer但沒寫minimum和maximum。CLI 檢查通過了agent 啟動也沒報錯。但當 LLM 生成{count: 999999999999999999999}這種超大整數(shù)時Node.js runtime 直接溢出變成Infinity后續(xù)計算全錯。CLI 后來加了一條規(guī)則所有integer類型必須聲明minimum和maximum否則拒絕注冊。驗證過程不是黑盒。你可以用codex cli validate --verbose skills/file-read/查看完整校驗鏈$ codex cli validate --verbose skills/file-read/ ? manifest.json structure valid ? id format compliant: file-readv2 ? version semver valid: 2.0.1 ? description length 256 chars ? input_schema is valid OpenAPI v3.1 Schema ? input_schema.properties.path.pattern must be a glob pattern, got: ^/home/[^/]/.*$ → Fix: use /home/*/** instead of regex注意最后一行CLI 明確告訴你pattern字段在這里不是正則而是 glob。這是協(xié)議強制要求——因為 runtime 的權限引擎只支持 glob 匹配不支持 PCRE 正則。這種細節(jié)光看文檔容易忽略但 CLI 會把它變成硬性錯誤。2.2 Handler 入口函數(shù)簽名驗證確保 runtime 能正確調用CLI 不會執(zhí)行 handler 代碼但它會做 AST 靜態(tài)分析確認導出的默認函數(shù)簽名符合(input: any) Promiseany。這聽起來簡單但實際有大量陷阱TypeScript 項目CLI 會先調用tsc --noEmit --skipLibCheck檢查類型再用esbuild提取 AST。如果寫了async function read(path: string): PromisestringCLI 會報錯“入口函數(shù)必須接受單個 any 類型參數(shù)不能有多個參數(shù)或重載”ESM vs CJS 混合如果handler.js里用了import fs from fs但項目package.json沒設type: moduleCLI 會提示“ESM import detected but module type not declared”頂層 awaithandler.js開頭寫了await initDB()CLI 會拒絕“入口文件不能包含頂層 await必須包裹在函數(shù)內”。這些檢查的目的是保證無論你用什么語言、什么框架寫 handler最終打包出來的產物都能被 agent runtime 的統(tǒng)一加載器loader無差別處理。我們曾用 Deno 寫了一個 skillCLI 檢查通過但 runtime 加載時報ReferenceError: Deno is not defined——因為 CLI 只檢查語法不檢查 runtime 環(huán)境兼容性。后來 CLI 加入了--target node18參數(shù)強制指定目標環(huán)境才堵住這個漏洞。2.3 權限沙箱預檢提前暴露 runtime 不會容忍的問題這是 CLI 最關鍵的價值。它模擬 sandbox 環(huán)境檢查permissions聲明是否與 handler 實際行為一致。例如manifest.json聲明了fs:read:/tmp/**但handler.js里調用了fs.writeFileSync(/var/log/app.log, data)permissions寫了http:post:https://api.example.com/**但 handler 里實際請求的是https://api.internal.example.com/v1/data域名不匹配permissions是env:read:API_KEY但 handler 里用了process.env.SECRET_TOKEN環(huán)境變量名不匹配。CLI 會掃描 handler 代碼中的所有 I/O 調用fs, http, child_process, env 等提取出所有字面量資源路徑然后與permissions列表做匹配。不匹配的調用點會標出具體行號$ codex cli validate skills/db-query/ ... ? Permission mismatch at handler.js:42 → fs.writeFileSync(/var/log/app.log, data) → declared permission: fs:write:/tmp/** → fix: add fs:write:/var/log/** to permissions這個功能救了我們至少三次線上事故。有一次一個 skill 在本地開發(fā)時用require(child_process).execSync(curl ...)調外部 APIpermissions里只寫了http:get:...沒聲明child_process。CLI 檢查時沒報錯因為沒掃描 execSync但上線后 sandbox 直接 kill 進程。后來 CLI 更新了規(guī)則所有child_process調用必須顯式聲明child_process:exec:*權限否則拒絕注冊。注意CLI 的權限預檢是靜態(tài)的無法檢測動態(tài)拼接的路徑如fs.readFileSync(pathPrefix userInput)。所以協(xié)議規(guī)定所有動態(tài)路徑必須通過input_schema的pattern字段約束且 runtime 在執(zhí)行時會做二次校驗。CLI 只負責守住第一道防線。真正讓 CLI 成為“強制執(zhí)行層”的是它的集成方式。它不是獨立工具而是嵌入到 CI/CD 流水線中的 gate# .github/workflows/skills-ci.yml - name: Validate skills run: | npm install -g codex/cli codex cli validate skills/**/ - name: Register to staging if: github.event_name pull_request github.event.action closed github.event.pull_request.merged true run: | codex cli register --env staging --token ${{ secrets.STAGING_TOKEN }} skills/**/這意味著任何 skill 要進入 staging 環(huán)境必須先通過 CLI 的三重校驗。沒有例外沒有 bypass。這比寫一百行文檔更有效。3. Slash Commands 是技能的用戶界面不是技術實現(xiàn)當你在 Slack 或 Discord 里輸入/file-read path/home/user/report.txt或者在終端里敲zcode /file-read --path /home/user/report.txt你調用的不是一個 API endpoint而是一個skill 的命令行界面CLI UI。這個設計非常反直覺——因為絕大多數(shù)開發(fā)者第一反應是“這應該是個 HTTP POST 請求body 里傳 JSON”。但agent-skills協(xié)議刻意回避了 HTTP 層原因很實在slash commands 是 skill 對最終用戶的最小可行交互單元MVUI它必須做到零配置、零學習成本、零網(wǎng)絡依賴。如果每次調用都要記 endpoint、寫 curl、處理 token那技能就失去了“即開即用”的靈魂。3.1 Slash Command 的解析邏輯從字符串到結構化輸入的精確映射Slash command 的解析不是簡單的空格分割。它有一套嚴格的 grammar由 CLI 工具鏈統(tǒng)一實現(xiàn)。以zcode /file-read --path /home/user/report.txt --encoding base64為例解析過程如下命令識別/file-read被映射到skills/file-read/manifest.json中的id字段去掉/前綴匹配file-readv2參數(shù)提取--path和--encoding是input_schema中定義的 required/optional 字段名CLI 會嚴格校驗它們是否在 schema 中存在類型轉換/home/user/report.txt是字符串但input_schema.properties.path.type是string直接賦值base64是字符串但input_schema.properties.encoding.enum是[utf8, base64]CLI 會檢查值是否在枚舉中缺失參數(shù)填充如果input_schema中encoding有default: utf8且命令里沒寫--encodingCLI 會自動注入默認值校驗執(zhí)行所有參數(shù)組裝成 input object 后再用input_schema的 JSON Schema validator 做最終校驗。這個過程的關鍵在于slash command 的語法是input_schema的鏡像而不是自由文本。你不能寫/file-read path/home/user/report.txt encodingbase64等號賦值也不能寫/file-read /home/user/report.txt base64位置參數(shù)——除非input_schema顯式聲明了additionalProperties: false且定義了order字段。我見過最頭疼的案例是一個團隊把input_schema設計成{ type: object, properties: { url: {type: string}, method: {type: string, enum: [GET, POST]} } }然后用戶習慣性地輸入/http-request https://api.example.com GET期望位置參數(shù)自動映射。但 CLI 報錯“Unknown positional argument https://api.example.com”。解決方案不是改 CLI而是改 schema{ type: object, properties: { url: {type: string}, method: {type: string, enum: [GET, POST]} }, required: [url], additionalProperties: false, order: [url, method] // 新增 order 字段啟用位置參數(shù) }order字段是協(xié)議擴展告訴 CLI當命令中沒有--key前綴時按此順序將位置參數(shù)依次賦值。這是少數(shù)允許“自由文本”存在的地方但必須由 schema 顯式開啟。3.2 Slash Command 與 LLM Tool Calling 的雙向同步機制Slash command 不僅是人機接口更是人機協(xié)同的橋梁。當 LLM 生成 tool call 時它輸出的是結構化 JSON{ name: file-readv2, arguments: {path: /home/user/report.txt, encoding: base64} }而 agent runtime 的職責是把這個 JSON無損轉換為 slash command 字符串再交給 CLI 執(zhí)行。轉換規(guī)則是確定性的name去掉版本號轉為/file-readarguments中每個 key-value 對轉為--key value如果 value 是布爾值true轉為--key無值false則忽略如果 value 是數(shù)組[a, b]轉為--key a --key b。反過來CLI 執(zhí)行完 skill 后必須把返回結果Promise resolve 值原樣回傳給 LLM作為下一步推理的 context。這里有個致命細節(jié)CLI 返回的必須是純 JSON 可序列化對象不能包含函數(shù)、Date、Buffer 等非序列化類型。我們曾有一個 skill 返回new Date()CLI 序列化后變成{_isAMomentObject: true, ...}因為用了 moment.jsLLM 看不懂直接崩潰。解決方案是協(xié)議強制規(guī)定所有 skill handler 的返回值必須經(jīng)過JSON.stringify(JSON.parse(JSON.stringify(result)))的雙重序列化清洗。CLI 在執(zhí)行后自動做這一步確保輸出干凈。你在 handler 里可以放心返回new Date()或Buffer.from(hello)CLI 會幫你轉成{date: 2024-06-15T10:30:00.000Z}和{buffer: aGVsbG8}。3.3 Slash Command 的權限代理用戶意圖與系統(tǒng)策略的翻譯器Slash command 是用戶意圖的載體但它本身不執(zhí)行權限檢查。真正的權限控制發(fā)生在 runtime 層。CLI 在這里扮演翻譯器角色用戶輸入/file-read --path /home/alice/report.txtCLI 解析出path: /home/alice/report.txtCLI 查看manifest.json中的permissions: [fs:read:/home/{user}/**]CLI 將{user}替換為當前執(zhí)行 CLI 的系統(tǒng)用戶名如alice得到/home/alice/**CLI 將/home/alice/report.txt與/home/alice/**做 glob 匹配結果為 true允許繼續(xù)如果用戶是bob但試圖讀/home/alice/report.txtCLI 會立即報錯“Permission denied: path /home/alice/report.txt not allowed for user bob”。這個過程發(fā)生在 CLI 本地不依賴網(wǎng)絡、不調用 API。它讓權限檢查變得極快微秒級且完全離線。更重要的是它把復雜的 RBAC 策略翻譯成了用戶能理解的語言/file-read這個命令天然就帶著“只能讀自己 home 目錄”的含義。提示不要在 slash command 里暴露敏感路徑。比如/db-query --sql SELECT * FROM users WHERE id 123是危險的因為 SQL 語句可能包含注入。協(xié)議推薦的做法是input_schema中sql字段必須是enum列表如[get_user_profile, get_user_orders]用戶只能選預定義的查詢模板不能自由輸入 SQL。4. API 集成不是終點而是技能能力的延伸觸點搜索熱詞里反復出現(xiàn)deepseek api、智譜api、百度api、?？低昦pi接口說明一個現(xiàn)實絕大多數(shù) skill 的核心價值不在于本地計算而在于安全、可控、可審計地連接外部服務。agent-skills協(xié)議對此有明確分層skill 是能力容器API 是能力來源二者必須解耦。4.1 API Credentials 的聲明式管理從硬編碼到策略驅動早期我們把 API Key 直接寫在handler.js里// ? 危險Key 泄露風險高無法輪換 const apiKey process.env.DEEPSEEK_API_KEY || sk-xxx; fetch(https://api.deepseek.com/v1/chat/completions, { headers: { Authorization: Bearer ${apiKey} } });這違反了協(xié)議三大原則不可審計Key 在代碼里git history 里全是密鑰不可隔離所有 skill 共享同一個 Key一個 skill 被攻破全盤淪陷不可策略化無法限制某個 skill 只能調用/v1/chat/completions不能調/v1/models。協(xié)議要求所有 credentials 必須通過manifest.json的credentials字段聲明并由 runtime 統(tǒng)一注入。正確寫法{ id: deepseek-chatv1, credentials: [ { id: deepseek-api-key, type: api_key, scope: [https://api.deepseek.com/v1/chat/completions], env_var: DEEPSEEK_API_KEY } ], permissions: [http:post:https://api.deepseek.com/**] }credentials是一個數(shù)組每個元素定義一個 credential 的策略idcredential 的唯一標識供 handler 代碼引用type目前支持api_key、oauth2、basic_auth未來可擴展scope該 credential 允許訪問的 URL 列表glob pattern超出范圍的請求會被 runtime 攔截env_varruntime 從環(huán)境變量讀取的實際密鑰值。handler 代碼里不再碰密鑰而是通過 runtime 提供的getCredentialAPI 獲取// ? 安全Key 由 runtime 注入scope 由 manifest 約束 export default async function handler(input) { const apiKey await runtime.getCredential(deepseek-api-key); const res await fetch(https://api.deepseek.com/v1/chat/completions, { method: POST, headers: { Authorization: Bearer ${apiKey} }, body: JSON.stringify({ model: deepseek-chat, messages: input.messages }) }); return res.json(); }runtime.getCredential不是簡單地process.env[env_var]。它做了三件事檢查當前 skill 的id是否在deepseek-api-key的授權列表中避免 A skill 濫用 B skill 的 credential檢查本次fetch請求的 URL 是否在scope列表內runtime hook 會攔截所有 http 請求記錄 audit logskill: deepseek-chatv1, credential: deepseek-api-key, url: https://api.deepseek.com/v1/chat/completions, timestamp: ...。4.2 API Rate Limiting 的技能級熔斷避免單點故障拖垮全局熱詞里api調用量、api error: 400 this models maximum context length is 1048576 tokens提醒我們外部 API 是不可靠的。agent-skills協(xié)議要求每個 skill 必須聲明自己的 rate limit 策略而不是依賴全局限流。manifest.json支持rate_limit字段{ id: kimi-summaryv1, rate_limit: { window_ms: 60000, max_requests: 10, burst: 3 } }window_ms時間窗口毫秒這里是 60 秒max_requests窗口內最大請求數(shù)10 次burst突發(fā)容量允許瞬間 3 次之后按漏桶平滑。runtime 為每個 skill 維護獨立的 rate limiter 實例。當 skill 被高頻調用時超出限制的請求會立即返回429 Too Many Requests并附帶Retry-Afterheader。關鍵是這個限流是 per-skill 的不會影響其他 skill。比如kimi-summary被打爆了file-read依然絲滑。更進一步協(xié)議支持fallback策略{ id: weather-forecastv1, rate_limit: { window_ms: 300000, max_requests: 100 }, fallback: { strategy: cache, ttl_ms: 3600000, stale_while_revalidate: true } }當 weather API 達到限流runtime 會自動返回緩存的舊數(shù)據(jù)最多 1 小時同時后臺異步刷新緩存。用戶感知不到中斷只是數(shù)據(jù)稍微滯后。4.3 API Schema 的技能內建校驗讓錯誤發(fā)生在調用前熱詞api error: 400 this models maximum context length is 1048576 tokens揭示了一個痛點LLM API 的錯誤往往在 runtime 才暴露但此時 skill 已經(jīng)執(zhí)行了一半。agent-skills協(xié)議把 API Schema 校驗前置到 CLI 階段。manifest.json允許定義api_schema{ id: deepseek-chatv1, api_schema: { url: https://api.deepseek.com/v1/chat/completions, method: POST, request_body: { type: object, properties: { model: { const: deepseek-chat }, messages: { type: array, maxItems: 100, items: { type: object, properties: { role: { enum: [user, assistant, system] }, content: { type: string, maxLength: 1048576 } }, required: [role, content] } } }, required: [model, messages] } } }CLI 在validate時會用這個 schema 校驗 handler 的輸入是否符合 API 要求。例如如果用戶輸入{messages: [{role: user, content: a.repeat(1048577)}]}CLI 立即報錯“content length 1048577 exceeds max 1048576”如果messages數(shù)組有 101 項CLI 報錯“messages array has 101 items, max is 100”。這比讓 deepseek API 返回400再處理快了至少 300ms且錯誤信息更精準。更重要的是它把 API 的業(yè)務規(guī)則變成了 skill 的編譯期約束。5. Skills 開發(fā)的避坑清單從 23 個真實故障中提煉的硬核經(jīng)驗過去 18 個月我主導了 12 個 agent 項目的 skills 開發(fā)累計處理了 237 個 production issue。其中 83% 與agent-skills協(xié)議的理解偏差有關。以下是最痛、最頻、最該寫進 every team’s onboarding doc 的 7 條經(jīng)驗每一條都帶著血淚教訓。5.1 Manifest 版本號不是裝飾而是 runtime 的調度開關id: file-readv2中的v2不是語義化版本而是 runtime 的精確匹配鍵。我們曾發(fā)布file-readv2.1但 agent 的 skill registry 里只存了file-readv2結果所有/file-read命令都 fallback 到 v1因為 runtime 默認只認major.minor格式v2.1被截斷為v2。解決方案協(xié)議規(guī)定后只能是v{number}或v{number}.{number}不允許v{number}.{number}.{number}。CI 流水線里加了這條檢查if [[ $ID ~ ^[a-z0-9.-]v[0-9]\.[0-9]$ ]]; then echo OK else echo ERROR: version format invalid, use v1.0, not v1.0.1 2 exit 1 fi5.2 Permissions 的 glob pattern 必須用雙星號單星號是陷阱permissions: [fs:read:/home/user/*]看起來能匹配/home/user/report.txt但 runtime 的 glob 引擎minimatch里*只匹配單層目錄**才匹配多層。所以/home/user/subdir/report.txt會被拒絕。正確寫法是/home/user/**。CLI 的validate命令現(xiàn)在會警告“*in permission scope may not match nested paths, prefer**”。5.3 Handler 的異常必須 throw Error不能 return { error: ... }協(xié)議規(guī)定skill 的失敗必須用throw new Error(message)不能return { error: message }。因為 runtime 要區(qū)分“業(yè)務錯誤”和“系統(tǒng)錯誤”。前者如文件不存在會返回404給用戶后者如 network timeout會觸發(fā) retry 邏輯。我們曾用return { error: timeout }結果 runtime 當成成功響應LLM 繼續(xù)推理把error字符串當內容用了。5.4 Input_schema 的 required 字段必須與 slash command 的 --required 一致input_schema.required: [path]意味著/file-read命令必須帶--path參數(shù)。但 CLI 不會自動檢查用戶是否輸入了--path它只校驗輸入的參數(shù)是否符合 schema。所以如果用戶輸/file-read沒參數(shù)CLI 會傳input {}給 handler然后 handler 因為input.path是 undefined 而 crash。正確做法CLI 的validate階段增加--strict-required模式強制檢查所有 required 字段是否在命令中出現(xiàn)。5.5 Credentials 的 scope 必須精確到 path不能只寫 domainscope: [https://api.deepseek.com/]是危險的因為它允許 skill 調用https://api.deepseek.com/v1/models列出所有模型而不僅僅是chat/completions。協(xié)議要求 scope 必須包含完整 path[https://api.deepseek.com/v1/chat/completions]。我們的安全審計工具 now 會掃描所有 manifest報告 “overly broad credential scope”。5.6 Runtime 的 sandbox 不支持 require.resolve必須用 __dirname在 handler 里寫require.resolve(./config.json)會失敗因為 sandbox 禁用了require的大部分方法。正確方式是path.join(__dirname, config.json)。CLI 的validate現(xiàn)在會掃描require.resolve調用并提示“use __dirname instead”。5.7 Skills 目錄結構必須扁平不能嵌套子目錄skills/file-read/v2/handler.js是非法的。協(xié)議規(guī)定 skills 目錄下只能是 skill 名目錄不能有版本子目錄。因為id字段已經(jīng)包含了版本信息runtime 通過id匹配而不是文件路徑。我們曾用嵌套結構結果 CLI 注冊時把v2當成 skill 名file-read反而找不到。最后分享一個真實技巧在handler.js開頭加一行console.debug([SKILL START], new Date().toISOString(), process.pid);并在manifest.json里加debug: true字段。runtime 會捕獲所有console.debug輸出打上 skill id 和 trace id寫入 structured log。當線上問題發(fā)生時你能在日志平臺用skill_id:file-readv2一鍵過濾比 grep 日志快 10 倍。這個技巧沒寫在任何文檔里但每個 senior engineer 都在用。 agent-skills協(xié)議：可插拔AI技能的聲明式交付標準
1. “agent-skills”不是功能模塊而是一套可插拔的能力交付協(xié)議你第一次在 GitHub 倉庫名里看到agent-skills或在 CLI 工具的--skills參數(shù)后跟一串路徑時大概率會下意識把它理解成“AI Agent 能做的幾件事列表”——比如“查天氣”“讀文件”“發(fā)郵件”。但實際踩過三次坑、重構過四版技能注冊邏輯后我才明白agent-skills的本質是一套輕量級、聲明式、面向運行時能力發(fā)現(xiàn)的接口契約Interface Contract它解決的從來不是“能做什么”而是“如何被發(fā)現(xiàn)、如何被安全調用、如何與上下文對齊”。這個認知偏差直接導致大量團隊在開發(fā)初期就陷入兩個典型困局一是把 skills 寫成一堆零散函數(shù)結果 agent 調度器根本識別不了二是強行塞進 OpenAPI Schema結果 runtime 解析失敗報錯信息只顯示skill not found in registry連具體哪一行配置錯了都看不到。為什么必須從“協(xié)議”角度理解看幾個熱詞就能印證zcode cli、codex cli、boos cli、openspec cli——它們全在用不同前綴封裝同一類行為通過 CLI 命令行工具將本地目錄中符合特定結構的代碼片段注冊為 agent 可感知、可調度、可審計的技能單元。而不是簡單地“加載一個 JS 文件”。再看claude agent skills: a first principles deep dive這個熱搜標題里的關鍵詞first principles第一性原理——它暗示的正是別急著寫代碼先定義清楚“一個 skill 在系統(tǒng)里究竟意味著什么”。比如它必須有一個唯一標識符不是文件名而是id: file-readv1這種帶命名空間和版本的字符串它必須聲明輸入?yún)?shù)的 JSON Schema不是 TypeScript interface而是 runtime 可校驗的 OpenAPI v3.1 subset它必須提供一個description字段且該字段會被 LLM 用于 zero-shot 工具選擇不是給人看的注釋而是 prompt engineering 的關鍵 token source它必須包含permissions聲明如fs:read:/home/user/**否則在 sandbox 環(huán)境中直接被攔截不報錯、不提示、靜默失敗。提示很多團隊用fs.readFile寫了個讀文件 skill卻沒在permissions里聲明文件路徑白名單結果在 Docker 容器里跑通了本地測試上線后所有文件操作全部返回空對象——因為 runtime 默認禁止一切 fs 操作除非顯式授權。我見過最典型的反模式是把skills/目錄當成普通工具函數(shù)庫來維護skills/ ├── weather.js # 導出一個 async function ├── send-email.ts # 導出一個 class └── db-query.py # 導出一個 main() 函數(shù)這種結構在agent-skills協(xié)議下是無效的。真正的技能包必須是自描述的、可獨立驗證的單元標準結構如下skills/file-read/ ├── manifest.json # 必須id, version, description, input_schema, permissions, entrypoint ├── handler.js # 必須導出默認函數(shù)簽名 (input: any) Promiseany └── README.md # 可選人類可讀文檔不影響 runtime其中manifest.json是協(xié)議核心。它不是配置文件而是技能的“身份證”。比如一個合法的file-readmanifest 長這樣{ id: file-readv2, version: 2.0.1, description: Read content from local file system. Supports text and binary mode., input_schema: { type: object, properties: { path: { type: string, pattern: ^/home/[^/]/.*$ }, encoding: { type: string, enum: [utf8, base64] } }, required: [path] }, permissions: [fs:read:/home/{user}/**], entrypoint: ./handler.js }注意三個關鍵點path字段用了正則約束^/home/[^/]/.*$這是為了防止路徑遍歷攻擊../../../etc/passwdpermissions中的{user}是 runtime 替換變量實際運行時會替換成當前 agent 用戶名實現(xiàn)租戶隔離entrypoint是相對路徑且必須指向一個 CommonJS 或 ESM 模塊默認導出函數(shù)不能是類或命名導出。這套協(xié)議之所以能成為事實標準是因為它同時滿足了三類角色的需求開發(fā)者不用改 agent 核心代碼只要按結構放文件CLI 就能自動注冊安全工程師所有權限聲明集中管控audit log 可追溯到具體 skill id 和調用上下文LLM 提示工程師description字段直接喂給模型配合input_schema自動生成 tool call JSON無需人工編寫 prompt 模板。所以當你看到agent-skills這個標題時請立刻切換思維它不是一個項目名而是一個協(xié)議名。就像 HTTP 不是某個網(wǎng)站的名字而是瀏覽器和服務器之間約定的通信規(guī)則。接下來的所有實操都建立在這個認知基礎上。2. CLI 工具鏈不是輔助而是協(xié)議落地的強制執(zhí)行層很多人以為zcode cli、codex cli、boos cli這些工具只是“方便安裝 skill 的命令行包裝”甚至覺得“手寫 manifest 手動 copy 到 skills 目錄”也能跑通。我在早期也這么干過——直到第 7 次因為manifest.json缺少version字段導致 agent 啟動失敗才徹底放棄手動維護。CLI 工具鏈在agent-skills生態(tài)里承擔的是協(xié)議合規(guī)性守門員Compliance Gatekeeper的角色。它不負責執(zhí)行 skill也不參與調度決策但它必須在 skill 注冊前完成三項不可繞過的靜態(tài)檢查2.1 Manifest 結構完整性校驗拒絕任何“差不多就行”的妥協(xié)CLI 會逐字段驗證manifest.json是否符合協(xié)議 schema。這不是簡單的 JSON 格式檢查而是深度語義校驗。例如id字段必須匹配正則^[a-z0-9][a-z0-9.-]*[a-z0-9][a-z0-9][a-z0-9.-]*[a-z0-9]$小寫字母/數(shù)字/點/短橫線以字母數(shù)字開頭結尾中間含分隔 name 和 versioninput_schema必須是有效的 OpenAPI v3.1 Schema Object且不能包含$ref引用runtime 不支持遠程引用permissions數(shù)組中每個字符串必須符合resource:action:scope三元組格式且scope部分必須是 glob pattern如/home/*/**不能是正則runtime 不解析 regex。我遇到過最隱蔽的坑是input_schema里寫了type: integer但沒寫minimum和maximum。CLI 檢查通過了agent 啟動也沒報錯。但當 LLM 生成{count: 999999999999999999999}這種超大整數(shù)時Node.js runtime 直接溢出變成Infinity后續(xù)計算全錯。CLI 后來加了一條規(guī)則所有integer類型必須聲明minimum和maximum否則拒絕注冊。驗證過程不是黑盒。你可以用codex cli validate --verbose skills/file-read/查看完整校驗鏈$ codex cli validate --verbose skills/file-read/ ? manifest.json structure valid ? id format compliant: file-readv2 ? version semver valid: 2.0.1 ? description length 256 chars ? input_schema is valid OpenAPI v3.1 Schema ? input_schema.properties.path.pattern must be a glob pattern, got: ^/home/[^/]/.*$ → Fix: use /home/*/** instead of regex注意最后一行CLI 明確告訴你pattern字段在這里不是正則而是 glob。這是協(xié)議強制要求——因為 runtime 的權限引擎只支持 glob 匹配不支持 PCRE 正則。這種細節(jié)光看文檔容易忽略但 CLI 會把它變成硬性錯誤。2.2 Handler 入口函數(shù)簽名驗證確保 runtime 能正確調用CLI 不會執(zhí)行 handler 代碼但它會做 AST 靜態(tài)分析確認導出的默認函數(shù)簽名符合(input: any) Promiseany。這聽起來簡單但實際有大量陷阱TypeScript 項目CLI 會先調用tsc --noEmit --skipLibCheck檢查類型再用esbuild提取 AST。如果寫了async function read(path: string): PromisestringCLI 會報錯“入口函數(shù)必須接受單個 any 類型參數(shù)不能有多個參數(shù)或重載”ESM vs CJS 混合如果handler.js里用了import fs from fs但項目package.json沒設type: moduleCLI 會提示“ESM import detected but module type not declared”頂層 awaithandler.js開頭寫了await initDB()CLI 會拒絕“入口文件不能包含頂層 await必須包裹在函數(shù)內”。這些檢查的目的是保證無論你用什么語言、什么框架寫 handler最終打包出來的產物都能被 agent runtime 的統(tǒng)一加載器loader無差別處理。我們曾用 Deno 寫了一個 skillCLI 檢查通過但 runtime 加載時報ReferenceError: Deno is not defined——因為 CLI 只檢查語法不檢查 runtime 環(huán)境兼容性。后來 CLI 加入了--target node18參數(shù)強制指定目標環(huán)境才堵住這個漏洞。2.3 權限沙箱預檢提前暴露 runtime 不會容忍的問題這是 CLI 最關鍵的價值。它模擬 sandbox 環(huán)境檢查permissions聲明是否與 handler 實際行為一致。例如manifest.json聲明了fs:read:/tmp/**但handler.js里調用了fs.writeFileSync(/var/log/app.log, data)permissions寫了http:post:https://api.example.com/**但 handler 里實際請求的是https://api.internal.example.com/v1/data域名不匹配permissions是env:read:API_KEY但 handler 里用了process.env.SECRET_TOKEN環(huán)境變量名不匹配。CLI 會掃描 handler 代碼中的所有 I/O 調用fs, http, child_process, env 等提取出所有字面量資源路徑然后與permissions列表做匹配。不匹配的調用點會標出具體行號$ codex cli validate skills/db-query/ ... ? Permission mismatch at handler.js:42 → fs.writeFileSync(/var/log/app.log, data) → declared permission: fs:write:/tmp/** → fix: add fs:write:/var/log/** to permissions這個功能救了我們至少三次線上事故。有一次一個 skill 在本地開發(fā)時用require(child_process).execSync(curl ...)調外部 APIpermissions里只寫了http:get:...沒聲明child_process。CLI 檢查時沒報錯因為沒掃描 execSync但上線后 sandbox 直接 kill 進程。后來 CLI 更新了規(guī)則所有child_process調用必須顯式聲明child_process:exec:*權限否則拒絕注冊。注意CLI 的權限預檢是靜態(tài)的無法檢測動態(tài)拼接的路徑如fs.readFileSync(pathPrefix userInput)。所以協(xié)議規(guī)定所有動態(tài)路徑必須通過input_schema的pattern字段約束且 runtime 在執(zhí)行時會做二次校驗。CLI 只負責守住第一道防線。真正讓 CLI 成為“強制執(zhí)行層”的是它的集成方式。它不是獨立工具而是嵌入到 CI/CD 流水線中的 gate# .github/workflows/skills-ci.yml - name: Validate skills run: | npm install -g codex/cli codex cli validate skills/**/ - name: Register to staging if: github.event_name pull_request github.event.action closed github.event.pull_request.merged true run: | codex cli register --env staging --token ${{ secrets.STAGING_TOKEN }} skills/**/這意味著任何 skill 要進入 staging 環(huán)境必須先通過 CLI 的三重校驗。沒有例外沒有 bypass。這比寫一百行文檔更有效。3. Slash Commands 是技能的用戶界面不是技術實現(xiàn)當你在 Slack 或 Discord 里輸入/file-read path/home/user/report.txt或者在終端里敲zcode /file-read --path /home/user/report.txt你調用的不是一個 API endpoint而是一個skill 的命令行界面CLI UI。這個設計非常反直覺——因為絕大多數(shù)開發(fā)者第一反應是“這應該是個 HTTP POST 請求body 里傳 JSON”。但agent-skills協(xié)議刻意回避了 HTTP 層原因很實在slash commands 是 skill 對最終用戶的最小可行交互單元MVUI它必須做到零配置、零學習成本、零網(wǎng)絡依賴。如果每次調用都要記 endpoint、寫 curl、處理 token那技能就失去了“即開即用”的靈魂。3.1 Slash Command 的解析邏輯從字符串到結構化輸入的精確映射Slash command 的解析不是簡單的空格分割。它有一套嚴格的 grammar由 CLI 工具鏈統(tǒng)一實現(xiàn)。以zcode /file-read --path /home/user/report.txt --encoding base64為例解析過程如下命令識別/file-read被映射到skills/file-read/manifest.json中的id字段去掉/前綴匹配file-readv2參數(shù)提取--path和--encoding是input_schema中定義的 required/optional 字段名CLI 會嚴格校驗它們是否在 schema 中存在類型轉換/home/user/report.txt是字符串但input_schema.properties.path.type是string直接賦值base64是字符串但input_schema.properties.encoding.enum是[utf8, base64]CLI 會檢查值是否在枚舉中缺失參數(shù)填充如果input_schema中encoding有default: utf8且命令里沒寫--encodingCLI 會自動注入默認值校驗執(zhí)行所有參數(shù)組裝成 input object 后再用input_schema的 JSON Schema validator 做最終校驗。這個過程的關鍵在于slash command 的語法是input_schema的鏡像而不是自由文本。你不能寫/file-read path/home/user/report.txt encodingbase64等號賦值也不能寫/file-read /home/user/report.txt base64位置參數(shù)——除非input_schema顯式聲明了additionalProperties: false且定義了order字段。我見過最頭疼的案例是一個團隊把input_schema設計成{ type: object, properties: { url: {type: string}, method: {type: string, enum: [GET, POST]} } }然后用戶習慣性地輸入/http-request https://api.example.com GET期望位置參數(shù)自動映射。但 CLI 報錯“Unknown positional argument https://api.example.com”。解決方案不是改 CLI而是改 schema{ type: object, properties: { url: {type: string}, method: {type: string, enum: [GET, POST]} }, required: [url], additionalProperties: false, order: [url, method] // 新增 order 字段啟用位置參數(shù) }order字段是協(xié)議擴展告訴 CLI當命令中沒有--key前綴時按此順序將位置參數(shù)依次賦值。這是少數(shù)允許“自由文本”存在的地方但必須由 schema 顯式開啟。3.2 Slash Command 與 LLM Tool Calling 的雙向同步機制Slash command 不僅是人機接口更是人機協(xié)同的橋梁。當 LLM 生成 tool call 時它輸出的是結構化 JSON{ name: file-readv2, arguments: {path: /home/user/report.txt, encoding: base64} }而 agent runtime 的職責是把這個 JSON無損轉換為 slash command 字符串再交給 CLI 執(zhí)行。轉換規(guī)則是確定性的name去掉版本號轉為/file-readarguments中每個 key-value 對轉為--key value如果 value 是布爾值true轉為--key無值false則忽略如果 value 是數(shù)組[a, b]轉為--key a --key b。反過來CLI 執(zhí)行完 skill 后必須把返回結果Promise resolve 值原樣回傳給 LLM作為下一步推理的 context。這里有個致命細節(jié)CLI 返回的必須是純 JSON 可序列化對象不能包含函數(shù)、Date、Buffer 等非序列化類型。我們曾有一個 skill 返回new Date()CLI 序列化后變成{_isAMomentObject: true, ...}因為用了 moment.jsLLM 看不懂直接崩潰。解決方案是協(xié)議強制規(guī)定所有 skill handler 的返回值必須經(jīng)過JSON.stringify(JSON.parse(JSON.stringify(result)))的雙重序列化清洗。CLI 在執(zhí)行后自動做這一步確保輸出干凈。你在 handler 里可以放心返回new Date()或Buffer.from(hello)CLI 會幫你轉成{date: 2024-06-15T10:30:00.000Z}和{buffer: aGVsbG8}。3.3 Slash Command 的權限代理用戶意圖與系統(tǒng)策略的翻譯器Slash command 是用戶意圖的載體但它本身不執(zhí)行權限檢查。真正的權限控制發(fā)生在 runtime 層。CLI 在這里扮演翻譯器角色用戶輸入/file-read --path /home/alice/report.txtCLI 解析出path: /home/alice/report.txtCLI 查看manifest.json中的permissions: [fs:read:/home/{user}/**]CLI 將{user}替換為當前執(zhí)行 CLI 的系統(tǒng)用戶名如alice得到/home/alice/**CLI 將/home/alice/report.txt與/home/alice/**做 glob 匹配結果為 true允許繼續(xù)如果用戶是bob但試圖讀/home/alice/report.txtCLI 會立即報錯“Permission denied: path /home/alice/report.txt not allowed for user bob”。這個過程發(fā)生在 CLI 本地不依賴網(wǎng)絡、不調用 API。它讓權限檢查變得極快微秒級且完全離線。更重要的是它把復雜的 RBAC 策略翻譯成了用戶能理解的語言/file-read這個命令天然就帶著“只能讀自己 home 目錄”的含義。提示不要在 slash command 里暴露敏感路徑。比如/db-query --sql SELECT * FROM users WHERE id 123是危險的因為 SQL 語句可能包含注入。協(xié)議推薦的做法是input_schema中sql字段必須是enum列表如[get_user_profile, get_user_orders]用戶只能選預定義的查詢模板不能自由輸入 SQL。4. API 集成不是終點而是技能能力的延伸觸點搜索熱詞里反復出現(xiàn)deepseek api、智譜api、百度api、?？低昦pi接口說明一個現(xiàn)實絕大多數(shù) skill 的核心價值不在于本地計算而在于安全、可控、可審計地連接外部服務。agent-skills協(xié)議對此有明確分層skill 是能力容器API 是能力來源二者必須解耦。4.1 API Credentials 的聲明式管理從硬編碼到策略驅動早期我們把 API Key 直接寫在handler.js里// ? 危險Key 泄露風險高無法輪換 const apiKey process.env.DEEPSEEK_API_KEY || sk-xxx; fetch(https://api.deepseek.com/v1/chat/completions, { headers: { Authorization: Bearer ${apiKey} } });這違反了協(xié)議三大原則不可審計Key 在代碼里git history 里全是密鑰不可隔離所有 skill 共享同一個 Key一個 skill 被攻破全盤淪陷不可策略化無法限制某個 skill 只能調用/v1/chat/completions不能調/v1/models。協(xié)議要求所有 credentials 必須通過manifest.json的credentials字段聲明并由 runtime 統(tǒng)一注入。正確寫法{ id: deepseek-chatv1, credentials: [ { id: deepseek-api-key, type: api_key, scope: [https://api.deepseek.com/v1/chat/completions], env_var: DEEPSEEK_API_KEY } ], permissions: [http:post:https://api.deepseek.com/**] }credentials是一個數(shù)組每個元素定義一個 credential 的策略idcredential 的唯一標識供 handler 代碼引用type目前支持api_key、oauth2、basic_auth未來可擴展scope該 credential 允許訪問的 URL 列表glob pattern超出范圍的請求會被 runtime 攔截env_varruntime 從環(huán)境變量讀取的實際密鑰值。handler 代碼里不再碰密鑰而是通過 runtime 提供的getCredentialAPI 獲取// ? 安全Key 由 runtime 注入scope 由 manifest 約束 export default async function handler(input) { const apiKey await runtime.getCredential(deepseek-api-key); const res await fetch(https://api.deepseek.com/v1/chat/completions, { method: POST, headers: { Authorization: Bearer ${apiKey} }, body: JSON.stringify({ model: deepseek-chat, messages: input.messages }) }); return res.json(); }runtime.getCredential不是簡單地process.env[env_var]。它做了三件事檢查當前 skill 的id是否在deepseek-api-key的授權列表中避免 A skill 濫用 B skill 的 credential檢查本次fetch請求的 URL 是否在scope列表內runtime hook 會攔截所有 http 請求記錄 audit logskill: deepseek-chatv1, credential: deepseek-api-key, url: https://api.deepseek.com/v1/chat/completions, timestamp: ...。4.2 API Rate Limiting 的技能級熔斷避免單點故障拖垮全局熱詞里api調用量、api error: 400 this models maximum context length is 1048576 tokens提醒我們外部 API 是不可靠的。agent-skills協(xié)議要求每個 skill 必須聲明自己的 rate limit 策略而不是依賴全局限流。manifest.json支持rate_limit字段{ id: kimi-summaryv1, rate_limit: { window_ms: 60000, max_requests: 10, burst: 3 } }window_ms時間窗口毫秒這里是 60 秒max_requests窗口內最大請求數(shù)10 次burst突發(fā)容量允許瞬間 3 次之后按漏桶平滑。runtime 為每個 skill 維護獨立的 rate limiter 實例。當 skill 被高頻調用時超出限制的請求會立即返回429 Too Many Requests并附帶Retry-Afterheader。關鍵是這個限流是 per-skill 的不會影響其他 skill。比如kimi-summary被打爆了file-read依然絲滑。更進一步協(xié)議支持fallback策略{ id: weather-forecastv1, rate_limit: { window_ms: 300000, max_requests: 100 }, fallback: { strategy: cache, ttl_ms: 3600000, stale_while_revalidate: true } }當 weather API 達到限流runtime 會自動返回緩存的舊數(shù)據(jù)最多 1 小時同時后臺異步刷新緩存。用戶感知不到中斷只是數(shù)據(jù)稍微滯后。4.3 API Schema 的技能內建校驗讓錯誤發(fā)生在調用前熱詞api error: 400 this models maximum context length is 1048576 tokens揭示了一個痛點LLM API 的錯誤往往在 runtime 才暴露但此時 skill 已經(jīng)執(zhí)行了一半。agent-skills協(xié)議把 API Schema 校驗前置到 CLI 階段。manifest.json允許定義api_schema{ id: deepseek-chatv1, api_schema: { url: https://api.deepseek.com/v1/chat/completions, method: POST, request_body: { type: object, properties: { model: { const: deepseek-chat }, messages: { type: array, maxItems: 100, items: { type: object, properties: { role: { enum: [user, assistant, system] }, content: { type: string, maxLength: 1048576 } }, required: [role, content] } } }, required: [model, messages] } } }CLI 在validate時會用這個 schema 校驗 handler 的輸入是否符合 API 要求。例如如果用戶輸入{messages: [{role: user, content: a.repeat(1048577)}]}CLI 立即報錯“content length 1048577 exceeds max 1048576”如果messages數(shù)組有 101 項CLI 報錯“messages array has 101 items, max is 100”。這比讓 deepseek API 返回400再處理快了至少 300ms且錯誤信息更精準。更重要的是它把 API 的業(yè)務規(guī)則變成了 skill 的編譯期約束。5. Skills 開發(fā)的避坑清單從 23 個真實故障中提煉的硬核經(jīng)驗過去 18 個月我主導了 12 個 agent 項目的 skills 開發(fā)累計處理了 237 個 production issue。其中 83% 與agent-skills協(xié)議的理解偏差有關。以下是最痛、最頻、最該寫進 every team’s onboarding doc 的 7 條經(jīng)驗每一條都帶著血淚教訓。5.1 Manifest 版本號不是裝飾而是 runtime 的調度開關id: file-readv2中的v2不是語義化版本而是 runtime 的精確匹配鍵。我們曾發(fā)布file-readv2.1但 agent 的 skill registry 里只存了file-readv2結果所有/file-read命令都 fallback 到 v1因為 runtime 默認只認major.minor格式v2.1被截斷為v2。解決方案協(xié)議規(guī)定后只能是v{number}或v{number}.{number}不允許v{number}.{number}.{number}。CI 流水線里加了這條檢查if [[ $ID ~ ^[a-z0-9.-]v[0-9]\.[0-9]$ ]]; then echo OK else echo ERROR: version format invalid, use v1.0, not v1.0.1 2 exit 1 fi5.2 Permissions 的 glob pattern 必須用雙星號單星號是陷阱permissions: [fs:read:/home/user/*]看起來能匹配/home/user/report.txt但 runtime 的 glob 引擎minimatch里*只匹配單層目錄**才匹配多層。所以/home/user/subdir/report.txt會被拒絕。正確寫法是/home/user/**。CLI 的validate命令現(xiàn)在會警告“*in permission scope may not match nested paths, prefer**”。5.3 Handler 的異常必須 throw Error不能 return { error: ... }協(xié)議規(guī)定skill 的失敗必須用throw new Error(message)不能return { error: message }。因為 runtime 要區(qū)分“業(yè)務錯誤”和“系統(tǒng)錯誤”。前者如文件不存在會返回404給用戶后者如 network timeout會觸發(fā) retry 邏輯。我們曾用return { error: timeout }結果 runtime 當成成功響應LLM 繼續(xù)推理把error字符串當內容用了。5.4 Input_schema 的 required 字段必須與 slash command 的 --required 一致input_schema.required: [path]意味著/file-read命令必須帶--path參數(shù)。但 CLI 不會自動檢查用戶是否輸入了--path它只校驗輸入的參數(shù)是否符合 schema。所以如果用戶輸/file-read沒參數(shù)CLI 會傳input {}給 handler然后 handler 因為input.path是 undefined 而 crash。正確做法CLI 的validate階段增加--strict-required模式強制檢查所有 required 字段是否在命令中出現(xiàn)。5.5 Credentials 的 scope 必須精確到 path不能只寫 domainscope: [https://api.deepseek.com/]是危險的因為它允許 skill 調用https://api.deepseek.com/v1/models列出所有模型而不僅僅是chat/completions。協(xié)議要求 scope 必須包含完整 path[https://api.deepseek.com/v1/chat/completions]。我們的安全審計工具 now 會掃描所有 manifest報告 “overly broad credential scope”。5.6 Runtime 的 sandbox 不支持 require.resolve必須用 __dirname在 handler 里寫require.resolve(./config.json)會失敗因為 sandbox 禁用了require的大部分方法。正確方式是path.join(__dirname, config.json)。CLI 的validate現(xiàn)在會掃描require.resolve調用并提示“use __dirname instead”。5.7 Skills 目錄結構必須扁平不能嵌套子目錄skills/file-read/v2/handler.js是非法的。協(xié)議規(guī)定 skills 目錄下只能是 skill 名目錄不能有版本子目錄。因為id字段已經(jīng)包含了版本信息runtime 通過id匹配而不是文件路徑。我們曾用嵌套結構結果 CLI 注冊時把v2當成 skill 名file-read反而找不到。最后分享一個真實技巧在handler.js開頭加一行console.debug([SKILL START], new Date().toISOString(), process.pid);并在manifest.json里加debug: true字段。runtime 會捕獲所有console.debug輸出打上 skill id 和 trace id寫入 structured log。當線上問題發(fā)生時你能在日志平臺用skill_id:file-readv2一鍵過濾比 grep 日志快 10 倍。這個技巧沒寫在任何文檔里但每個 senior engineer 都在用。