make-skill — 以經過驗證的方式建立、改裝與發佈技能
從一個運作中的儲存庫（通常是 ~/DATA/<name>）複製：ssheleg/super-ux（多重技能套件，Cursor 規則）或 ssheleg/task-pipeline（單一技能編排器，發佈自動化）。make-skill 本身即依此規範建置。
參考文件 — 按需載入
| 請閱讀 | 時機 |
|---|---|
references/agent-skills-spec.md | 撰寫或稽核任何 SKILL.md 時 — 來自兩方權威的硬性限制、選填欄位、預算、誰會拒絕什麼 |
references/authoring.md | 撰寫或調整主體/說明時 — 命名規則、第三人稱、自由度、腳本規則、評估循環 |
references/surfaces.md | 發佈到 Claude Code 以外的任何地方時 — Skills API 上傳/版本/每次 8 個請求、claude.ai zip、無網路限制 |
references/enterprise.md | 安裝他人的技能，或管理技能群時 — 風險等級、審查檢查清單、核准關卡、生命週期 |
references/retrofit.md | 稽核現有技能/儲存庫時 — 14 項檢查清單、證據規則、個人技能簡化版 |
references/host-capabilities.md | 發佈鉤子、子代理、命令、腳本或 MCP 依賴時 — 各項的優缺點、鉤子事件與退出碼、降級條款 |
references/claude-code-plugin.md | 任何以 Claude Code 外掛/市場形式發佈的專案 — 清單結構、元件佈局、路徑變數、validate 失敗 |
references/distribution.md | 儲存庫佈局、發佈版本與所有五種管道 — 外掛、skills CLI、npx、Cursor、父層家族儲存庫 |
references/mcp.md、references/mcp-ship.md | 技能 vs MCP 伺服器，包裝其中一個 — 然後發佈：掛載、其 404、server.json、註冊中心 |
references/a2a.md | 技能橫跨兩個自主代理 (A2A)：代理卡片、任務生命週期、委派 |
此副本遺漏了？原始備援：
raw.githubusercontent.com/ssheleg/make-skill/main/plugins/make-skill/skills/make-skill/references/<file>
選擇工作流程
從請求以及 $ARGUMENTS 中的任何路徑進行偵測；宣布所做的選擇。
| 情況 | 工作流程 |
|---|---|
| 新技能，僅供此使用者的代理使用 | 建立（個人） |
| 新技能，可讓其他使用者/代理安裝 | 建立（可發佈） |
| 現有技能或儲存庫低於此標準，且詢問「是否符合規範？」 | 改裝 |
| 個人技能應變成可安裝 | 升級 |
沒有引數時，偵測而非詢問：目前目錄中有 SKILL.md、.claude-plugin/ 或 plugins/*/skills/*/ → 執行改裝稽核並報告差距表及一個下一步行動。無任何可偵測項目 → 用一行文字詢問要建立什麼。
可發佈的工作是一個真正的專案：先有規格（docs/superpowers/specs/），後有程式碼，且規格會先鎖定目標專案的檔案合約 — 技能是針對該合約撰寫的，絕非臨時湊合。
撰寫規則（每個工作流程都適用）
規格基礎優先 — 開放標準和 Anthropic 的平台規則都是不可協商的；此規範僅在其之上增加項目。 欄位表、其差異及檢查清單：references/agent-skills-spec.md。
name：字元規則請見references/agent-skills-spec.md；需等於目錄名稱。陷阱：絕不能包含anthropic或claude— 這些是保留子字串，Claude Code 會愉快地載入，但 Skills API 會在上傳時拒絕，因此失敗會發生在別人的機器上。description：≤1024 個字元（此限制僅針對此欄位，而非整個 front-matter 區塊），不得有尖括號，使用第三人稱 — 它會被注入到系統提示中，在那裡「我可以幫你…」會降低被選中的機率。說明它做什麼以及何時使用。- 可攜帶的選填欄位集為
license、compatibility、metadata和allowed-tools— 限制與型別請見references/agent-skills-spec.md。 license是選填的 — 無論如何都宣告它，在 front matter 和marketplace.json的外掛條目中都要：根目錄的LICENSE檔案既不會到達外掛列表，也不會到達已安裝的技能，而且不會報錯，因此這個缺口會一直存在（此處的所有六個儲存庫，截至 2026-07-30）。- 主機擴充功能是合法的，但絕不能是關鍵依賴。 Claude Code 會讀取另一組僅屬於主機的設定（
references/claude-code-plugin.md）；其他代理會忽略它，因此依賴於它的技能在其他地方會壞掉。規範 ∪ 主機之外的內容 = 拼寫錯誤。 - 主體 < 500 行且 < 5000 tokens，並保留 5% 的餘裕 — 一個預算使用率達 99% 的主體會讓下一次修正變成與驗證器的戰鬥。較重的材料應放入技能目錄內部的
references/、scripts/、assets/，深一層，每個都需從主體連結並說明載入觸發條件（「當 Y 時閱讀 X」）— 絕不能只是「請見 references/」。超過 100 行的參考檔案應以## 目錄列表開頭：代理通常只會進行部分head讀取。 - 注意事項留在
SKILL.md中：代理無法知道去開啟一個它不知道存在的陷阱檔案。 - 為你所聲稱的最弱表面撰寫（
references/surfaces.md）：Claude API 容器沒有網路和沒有套件安裝，claude.ai 情況各異，只有 Claude Code 兩者都有。一個執行pip install或 curl 的腳本是 Claude Code 專用的技能 — 請在compatibility中說明或刪除它。各表面之間沒有同步；git 才是事實的來源。
在規範之上的自訂補充：
- 散文使用英文；字面值則保持其原本輸入的語言。 西里爾字母僅在四種情況下保留，即該字串本身即為重點：觸發詞組、拒絕詞組（操作者輸入這兩者 — 如果翻譯了，它們就不再與實際說出的內容相符）、專有名詞、語言範例（
«вы»/«ты»）。預算規則優先於風格規則：俄語以每個 token 1.9–2.3 個字元編碼，而英語為 5.0（cl100k），將八個 ssheleg 路由器改寫為英文後，其 token 數從 3408 減少到 1885，且無損意義。 description以「Use when …」開頭，並列出具體的觸發詞組 — 英文和俄文（使用者在兩種語言中工作）。一個無人觸發的技能是死重量。在此處也保留 5% 的餘裕（≤970 of 1024）：一個接近邊界的相鄰項目會迫使加入「NOT for …」子句，而一個使用率達 98% 上限的說明會沒有空間容納它。- 統一的命名模式，最好是動名詞形式 (
processing-pdfs)；永遠不要使用helper、utils、tools、data— 模糊的名稱會失去所有被選中的機會。 - 一個技能 = 一個工作。多個關注點 → 多個技能 + 一個共享的合約檔案。將合約放在技能目錄內部（
references/…）：skills CLI 只會發送技能自身的目錄，因此一個同層級的skills/references/在作為 Claude Code 外掛時可以運作，但在其他所有代理上到達時都是壞的。跨技能共享 → 在每個技能目錄中複製，並由驗證器檢查是否相同。 - 主體：命令式、程序式、檢查清單優先於散文；將不可協商的項目明確陳述。根據脆弱程度調整規定程度 — 對於破壞性或依賴順序的工作使用精確命令，對於由上下文決定的情況僅提供方向（
references/authoring.md）。 - 評估先於散文： 在沒有技能的情況下執行目標任務，記錄失敗，針對這些失敗撰寫 ≥3 個評估，然後撰寫能夠通過的最低限度內容；一個沒有基準線建立的技能所記錄的是想像中的問題。加入現有家族 → 根據已安裝的集合衡量共存性，不要猜測：你提名的相鄰項目通常不是最近的那個。
- 提供單一指令的進入點：冪等 — 檢查狀態 → 修復缺失的部分 → 狀態報告 → 精確建議一個下一步行動。偵測模式，永遠不要詢問。技能本身就是那個指令；不同頻道的調用方式不同（從技能目錄調用為
/<skill>，作為外掛調用為/<plugin>:<skill>）— 在 README 中同時寫明這兩者，而不是僅承諾一種。 - 永遠不要覆寫使用者資料：僅在不存在時建立種子資料；僅在加上
--force時才能覆寫。
降級合約（每個會接觸主機功能的技能）
鉤子、子代理、/commands、外掛路徑變數和 MCP 伺服器僅存在於 Claude Code 內部 — 這是技能運行的少數環境。每個都是加速器，並附有書面備援方案；沒有它，技能仍然能完成工作，只是速度較慢。 將三種情況寫入主體，使用代理的語言，並在代理需要它們的時候出現（形式請見 references/host-capabilities.md）：
- 非 Claude Code（Cursor、Codex、skills CLI、API）：沒有鉤子、沒有子代理、沒有
/command。指明內聯程序；捆綁的scripts/仍然會傳送，因此請提供每個頻道的路徑。 - 推薦的外掛/技能缺失：說明一次哪些功能會降級，然後繼續走手動路徑。一個因為缺少選用夥伴而拒絕啟動的階段是壞掉的，而不是嚴格的。
- 工具、直譯器或 MCP 伺服器缺失：說明一次，回退到手動程序，永遠不要循環重試。互動式認證是人工步驟。
你知道但沒有寫下來的備援方案就不是備援方案。
此技能隨附的工作範例 — 複製這些，而不是你的記憶
scripts/audit_skill.py 可稽核任何技能目錄（標準庫；改裝流程的機械部分），包裝為 bin/make-skill-audit 供 Claude Code 使用。旁邊還有：hooks/（PostToolUse，除非寫入了 SKILL.md，否則保持靜默）、commands/skill-audit.md（故意不使用技能的名稱）、agents/skill-auditor.md，以及六個骨架：assets/SKILL.template.md、assets/plugin.template.json、assets/marketplace.template.json、assets/hooks.template.json、assets/agent.template.md、assets/command.template.md。
建立（個人）
根據撰寫規則在 ~/.claude/skills/<name>/SKILL.md 建立 — 完成。沒有儲存庫，沒有版本控制；下次啟動時載入。提及「升級」作為升級路徑。
需要鉤子、代理或 MCP 伺服器，但仍然沒有儲存庫？在同一個資料夾中加入 .claude-plugin/plugin.json — Claude Code 會在下次啟動時將其作為 <name>@skills-dir 載入。
建立（可發佈）
儲存庫樹結構、公開儲存庫基本要求、claude plugin validate … --strict 的兩次執行以及內部驗證器規範都在 references/distribution.md → 可發佈的儲存庫佈局 中。在建立第一個檔案之前先打開它。 始終適用的規則：
- 在儲存庫根目錄有
.claude-plugin/marketplace.json；外掛位於plugins/<name>/下，並有自己的.claude-plugin/plugin.json；技能位於plugins/<name>/skills/<skill>/下，其內部包含references/、scripts/、assets/。只有清單文件存放在.claude-plugin/中 — 埋藏在那裡的元件載入時會變為空無一物，而外掛看起來仍能正常運作。 - 版本同步（硬性規則）： marketplace.json、plugin.json、package.json 以及頂層的 CHANGELOG 條目必須攜帶相同的 semver 版本，並一起更新（如果
SKILL.md攜帶了metadata.version，則再加上第 5 個同步點）。 - 兩次
--strict執行都必須通過，在 CI 中，作為獨立作業 — 它們只讀取清單，因此 front-matter 規則應放在你自己的test/validate.py中，並且該測試需要一個負面自我測試：一個不能失敗的驗證器只是裝飾品。在plugin.json以及市場條目中提供$schema和displayName（市場根目錄不接受這兩者）。 - 一個公開儲存庫應為讀者提供英文優先的 README、包含驗證變更的離線命令的
CONTRIBUTING.md，以及指名私有通訊管道和安裝程式所觸及範圍的SECURITY.md。
首次發佈 — 端到端，同一次工作階段
一路完成，不能有半成品交接。只有首次發佈需要人工介入（npm 2FA）；讓 CI 能夠進行發佈是發佈流程的一部分，這樣第二次就不需要了。11 個步驟的序列在 references/distribution.md → 首次發佈 中。 完成 = 五個已驗證的事實：儲存庫 + CI 通過、npm 可透過 npx 解析、外掛已安裝、skills-CLI 發現功能正常運作、下一個標籤無需人工即可發佈。
改裝（將現有技能/儲存庫提升至標準）
先稽核，後修正，在同一工作階段內完成。每個項目的判定結果：通過 / 有差距 / 未執行，並附上證據 — 一個 file:line 或你實際執行的命令的輸出。「看起來沒問題」不是一個判定結果，基於推理而非執行的檢查得到「通過」也一樣；一個缺少工具的檢查項目是附帶原因的「未執行」，絕非「通過」。
先執行隨附的稽核器 — 它會確定性地完成機械部分，並且永遠不依賴於未設定的變數：
make-skill-audit <skill-dir> --house # Claude Code：外掛的 bin/ 在 PATH 中
在任何其他地方，從你剛才讀取此內容的 make-skill 目錄執行 scripts/audit_skill.py。然後處理 references/retrofit.md 中的 14 項檢查清單 — 規範基礎、外掛基礎、表面、單一任務、進入點、佈局與版本同步、驗證器與 CI、評估、README、發佈、儲存庫後設資料、注意事項、協定、主機功能。對於個人技能，僅適用其中三項；該檔案會說明是哪三項。
然後： 報告差距表，修正所有現在可以修正的問題，更新一個次要/修訂版本號，執行發佈檢查清單。
升級（個人 → 可發佈）
按照佈局建立儲存庫，將技能移至 plugins/<name>/skills/<skill>/，將合約提取到 references/，然後端到端執行首次發佈。僅在確認外掛安裝已驗證之後，才刪除舊的 ~/.claude/skills/<skill> 副本。
安裝他人的技能
技能是代理執行的指令加上代理在未閱讀情況下執行的程式碼 — 安裝技能就是安裝軟體。任何不是你寫的技能，首先都要經過 references/enterprise.md 中的審查檢查清單。風險最高的形式：一個從 URL 獲取其指令的技能 — 該內容在批准它的審查之後可能會變更。
協定連接的技能（MCP / A2A）
技能是指令；它無法授予能力。教導代理如何做是技能的工作。針對即時系統提供新能力的是 MCP 伺服器（先看 mcp.md，然後看 mcp-ship.md 以掛載和發佈）。將結果委派給另一個自主代理的是 A2A（a2a.md）。這兩個參考文件都包含了線路層級的規則 — 每個主機的工具名稱發現、代理卡片，以及將互動式認證視為人工步驟。