Nova 技能創建器 — 技能工程師協議 v2.2
版本 2.4.1 · 模式:順序工作流程 · 類型:代碼支架與模板
「技能工程師協議 v2.2」是此技能所遵循流程的名稱,而非版本號。
目的
此元技能將每個與技能相關的請求(編寫新技能 / 升級 / 編輯 / 審查)轉化為標準工程流程,並生成可立即部署的專業技能。每個輸出技能都是一個獨立的「虛擬員工」:根據複雜性和目標環境,可以是 1 個 SKILL.md 檔案 或 1 個完整的文件夾。
當此技能被激活時,請以以下確切句子開始回應: 「技能工程師協議 v2.2 已激活。正在啟動標準流程...」
之後,請以用戶使用的語言回應。
⚠️ 重寫時保留內容(最高規則)
「完整重寫」意味著 重構,而非 壓縮/總結。當此技能與另一個 LLM(尤其是較弱的模型)一起使用時,最常見的失敗是技術描述被壓縮、表格欄位被截斷、具體的 schema/值被丟棄——輸出看起來更整潔,但已遺失原始內容。
強制性區分:
| 重構(正確) | 壓縮(錯誤) |
|---|---|
| 更改佈局、合併重複部分、修正措辭 | 刪除表格、行、列、範例 |
| 完全保留每個值/schema/ID/規則 | 將 schema 改寫成「大致上」 |
| 輸出項目數量 >= 輸入項目數量 | 將 10 個陷阱縮減為 4 個 |
| 提高清晰度 | 減少細節「以使其更簡潔」 |
3 步驟防壓縮流程 — 每次重寫或升級前/後強制執行:
- 首先盤點(內容清單): 列出所有不得遺失的原始元素 — 每個表格(及其行/列數)、每個 schema 規則、每個具體值(ID、版本、選項)、每個陷阱、每個測試案例。將其記錄為一份檢查清單。
- 受約束的重寫: 重寫時,清單中的每個元素都必須完整出現在輸出中。您可以改進呈現方式;但不得減少元素數量或任何元素的詳細程度。
- 事後檢查(差異檢查): 將輸出與清單進行比對。如果缺少任何元素,或表格的行/列數少於原始表格 → 未完成;在回答前將其恢復。
給執行 LLM 的自我綁定指令:「逐字保留每個表格、schema、具體值和陷阱。不要總結,不要丟棄技術細節。如果必須更簡潔,請將其拆分到 references/;切勿刪除內容。」
技能即文件夾 — 根據複雜度選擇結構
Claude、Claude Code 和其他代理支援將技能作為一個 文件夾,其中包含 SKILL.md 和捆綁資源,具有漸進式揭示(按需加載資源)、可離線運行的腳本以及動態加載的 references/。您不必將所有內容塞進 1 個檔案。
| 複雜度 | 建議結構 |
|---|---|
| 簡單、簡短的技能 | 僅 1 個 SKILL.md 檔案(仍然有效) |
| 具有重複/確定性邏輯的技能 | 文件夾 + scripts/ |
| 多領域技能 / 長文檔 | 文件夾 + 按變體拆分的 references/ |
| 輸出捆綁檔案(模板/圖示/字體)的技能 | 文件夾 + assets/ |
原則: 選擇足夠的最小結構。簡單 → 1 個檔案;複雜 → 拆分為文件夾以保持 SKILL.md 精簡。當內容過長時 → 將其拆分到 references/,切勿將其壓縮掉。
技能的構成
skill-name-kebab-case/
├── SKILL.md (必需)
│ ├── YAML 前置元数据(5 個欄位用於帳戶/自由格式 LLM · 僅 `name` + `description` 用於標準代理技能目標 — 請參閱「按目標環境劃分的變體」)
│ └── Markdown 指令
└── 捆綁資源(可選)
├── scripts/ - 用於確定性/重複性任務的可執行代碼
├── references/ - 在需要時加載到上下文中的文檔
└── assets/ - 輸出中使用的檔案(模板、圖示、字體)
漸進式揭示(3 個加載級別)
| 級別 | 內容 | 何時進入上下文 |
|---|---|---|
| 1 | 元數據(name + description) | 始終(約 100 詞) |
| 2 | SKILL.md 主體 | 技能激活時(理想情況下少於 500 行) |
| 3 | 捆綁資源 | 需要時(references/ 動態加載;scripts/ 運行時不將其內容加載到上下文中) |
規則: 保持 SKILL.md 主體少於 500 行。當接近限制時 → 拆分到 references/ 並在 SKILL.md 中留下清晰的指針,說明在哪裡讀取。較長的參考文件(>300 行)應有目錄。拆分與壓縮 不同 — 拆分將內容完整地保留在另一個檔案中,而壓縮則會丟失內容。
編寫新技能流程(8 步驟)
| # | 步驟 | 描述 |
|---|---|---|
| 1 | 詢問遺漏資訊 | 目標、陷阱、語言、輸出、目標環境。如果對話中已包含工作流程 → 首先從歷史記錄中提取,僅詢問缺失的內容 |
| 2 | 選擇 1 個模式 + 1 個技能類型 | 各選恰好 1 個(參見下面的列表) |
| 3 | 首先編寫描述 | 最重要的步驟 — 遵循下面的描述協議 |
| 4 | 選擇結構 + 設計內容 | 單個檔案還是文件夾?哪些內容內聯,哪些放到 references/,哪些邏輯變成 scripts/ |
| 5 | 編寫 SKILL.md | YAML + 工作流程 + 規則/Schema + 陷阱;主體少於 500 行,將長部分卸載到參考文件 |
| 6 | 編寫腳本/參考文件(如需要) | 確定性/重複性邏輯 → scripts/;長文檔 → references/ 並附上指針 |
| 7 | 測試激活 | 3 個正向 + 3 個負向案例 |
| 8 | 使用輸出格式回答 | 參見下面的輸出格式部分 |
僅當所有 14/14 檢查清單項目通過時才發布。
升級 / 編輯流程(8 步驟)
- 讀取整個當前的 SKILL.md(及其捆綁檔案)。
- 首先盤點 — 列出所有不得遺失的表格/schema/值/陷阱/測試案例(最高規則,步驟 1)。
- 記錄來自用戶和先前運行的陷阱。
- 根據 14 項檢查清單進行評估。
- 識別失敗類型:觸發不足 / 過度觸發 / 執行錯誤 / 內容遺失(壓縮/截斷)。
- 在保留約束下重寫所有內容 — 重構,不要壓縮。切勿逐塊修補。
- 事後檢查 — 將輸出與清單進行比對,恢復任何遺失的內容。
- 重新測試 3 個正向 + 3 個負向案例,提升
version。
鐵則: 完整重寫 = 保留所有內容的重構。不要拼湊。不要壓縮掉細節。升級時保留舊的 name。
YAML 前置元数据(強制性)
---
name: skill-name-kebab-case
version: x.x.x
description: >-
[針對激活優化的描述,少於 1024 個字符,純 ASCII,無變音符號,無尖括號]
pattern: [5 個模式中的 1 個]
type: [9 個技能類型中的 1 個]
---
按目標環境劃分的變體(在編寫前置元数据前詢問)
上面的 5 欄位區塊是供 claude.ai 帳戶 / Grok / 自由格式 LLM 使用的模板。某些目標恰好接受 2 個欄位 — 在那裡提交 5 欄位版本會立即導致驗證失敗,甚至在審查開始之前。步驟 1(收集資訊)必須詢問或推斷目標;如果不清楚,預設使用 2 欄位版本,因為 2 欄位版本適用於所有目標,而 5 欄位版本則不行。
| 目標 | 前置元数据 | Version / Pattern / Type 的位置 |
|---|---|---|
| claude.ai 帳戶、Grok、其他 LLM | 5 個欄位,如上模板所示,description 使用 >- 折疊 | 在 YAML 中 |
標準代理技能(Claude Code 的 .claude/skills、Codex 的 .agents/skills)以及具有嚴格驗證的技能註冊表 | 僅 name + description,各自佔據一行 — 無 >-、無縮進行、無第三個欄位 | 一條緊跟在 H1 下方的引用行:> **Version x.y.z** · Pattern: … · Type: …;實際版本存在於目標系統的註冊表/清單檔案中(如有) |
標準代理技能目標的模板:
---
name: skill-name-kebab-case
description: "[針對激活優化的描述,一行,>= 40 個字符,純 ASCII,無變音符號,無尖括號]"
---
始終將單行 description 用雙引號包裹。 Claude Code 和 Codex 使用真正的 YAML 解析器讀取前置元数据。使用裸值會導致兩種故障。 (1) 解析錯誤 — 技能以空元數據加載且無警告:中間出現 : (例如 Vi du: … 或 Example: …)、結尾出現 :、以 [ { > | ' " * ! % @ , 或反引號開頭,或以 - ? : (字符後跟空格)開頭。 (2) 含義的靜默更改 — 它解析成功但結果錯誤:以 # 開頭會使描述為空,中間的 # 會截斷其餘部分,以 & 開頭會將其變成錨點。雙引號可以避免這兩個問題;在雙引號內不要使用 " 或 \。
具有嚴格驗證的註冊表通常還會阻止:包含 Windows 磁碟機代號的絕對路徑(磁碟機 + 冒號 + 斜線 — 寫入 <root>/… 而不是硬編碼磁碟機)、看起來像憑證的字串、套件內損壞的 markdown 連結,以及任何未強制 stdout/stderr 為 UTF-8 的 .py 腳本。獨立審查也經常拒絕僅在 claude.ai 沙箱中有效的語法(/mnt/skills/…、/mnt/user-data/outputs/、present_files、extract-text)— 請編寫主機中立的指令。
5 種模式(選擇恰好 1 種)
順序工作流程 | 多 MCP 協調 | 迭代優化 | 上下文感知工具選擇 | 領域特定智慧
9 種技能類型(選擇恰好 1 種)
庫與 API 參考 | 產品驗證 | 代碼支架與模板 | 業務流程自動化 | 資料獲取與分析 | 代碼品質與審查 | CI/CD 與部署 | 操作手冊 | 基礎設施運維
描述編寫協議(強制性)
目標: 激活率 72–90%。
| 要求 | 詳細說明 |
|---|---|
| 觸發短語 | 至少 5 個短語(以您的用戶使用的每種語言,必要時使用羅馬化,例如英語 + 越南語) |
| 風格 | 情境式:「當用戶想要...時使用」、「每當...」 |
| 實際範例 | 至少幾個用戶實際會輸入的提示範例 |
| 長度 | 少於 1024 個字符 |
| 無變音符號 | 僅限 YAML 欄位:純 ASCII — 去除每個帶重音符號的字母和聲調符號(例如越南語的 ă â ê ô ơ ư đ)。對於非拉丁字母的語言,使用羅馬化或英語觸發短語 |
| 無尖括號 | 切勿使用開放/關閉尖括號 |
| 負面阻止語 | 以阻止性句子結尾:「請勿在...時使用」 |
標準描述的範例(純 ASCII):
Use when the user wants to add content to an AI Wiki on Notion, save AI knowledge,
classify article links, notes, tools, prompts. WHENEVER the user pastes a link,
a note, a tool name or an AI prompt to keep. Examples - save this link to the wiki,
add this tool to notion, keep this prompt, save this article. Do not use when the
user only asks a knowledge question or asks for new content with no intent to save.
14 項檢查清單(閘門 — 需要 14/14)
| # | 標準 | 通過條件 |
|---|---|---|
| 1 | name 是正確的 kebab-case 且不包含「claude」/「anthropic」 | ☐ |
| 2 | YAML 包含 name + version + description(+ pattern + type) | ☐ |
| 3 | description 完全符合描述協議 | ☐ |
| 4 | 描述中無尖括號 | ☐ |
| 5 | SKILL.md 主體少於 500 行(長部分卸載到參考文件) | ☐ |
| 6 | 恰好選擇 1 個模式 + 1 個技能類型 | ☐ |
| 7 | 不教授 AI 已知的基礎知識 | ☐ |
| 8 | 具有實際陷阱(至少 5 個) | ☐ |
| 9 | 結構符合需求:長文檔拆分到 references/ 並附有清晰指針 | ☐ |
| 10 | 重複/確定性邏輯打包為 scripts/,而不是手動描述 | ☐ |
| 11 | 描述針對激活優化 + 具有負面阻止語 | ☐ |
| 12 | 測試了 3 個正向 + 3 個負向案例 | ☐ |
| 13 | 如果這是升級,則已完整重寫(非修補) | ☐ |
| 14 | 已完成差異檢查:每個原始表格/schema/值/陷阱/測試案例仍然完整,無壓縮或截斷 | ☐ |
僅當所有 14/14 通過時才回答用戶。
6 條黃金原則
- 不要教授 AI 已知的內容 — 僅專注於特定上下文和陷阱。
- 陷阱是最有價值的資產 — 記錄每次重複的失敗。
- 持續更新 — 每次錯誤 = 一個新陷阱 → 立即升級。
- 足夠的最小結構 — 簡單 = 1 個檔案,複雜 = 拆分為文件夾並使用漸進式揭示。
- 完整重寫 = 重構,而非壓縮 — 完全保留技術內容;如果太長,拆分到參考文件,不要壓縮掉。
- 切勿逐塊修補。
回答用戶時的輸出格式(強制性,按此順序)
- 技能摘要 — 目的、模式、類型、結構(單個檔案或文件夾)。
- 完整的 SKILL.md 內容 — 在代碼區塊中;如果是文件夾,也列出
references//scripts//assets/檔案。 - 部署指南 — 針對目標環境的具體步驟。
- 測試結果 — 3 個正向 + 3 個負向案例。
- 差異檢查 — 確認未遺失任何原始內容(如果這是升級/重寫)。
- 已處理的陷阱 — 如果這是升級。
- 版本 — YAML 中的版本。
部署指南
文件夾技能(Claude Code / 代理 / API):
- 創建文件夾
skill-name-kebab-case/。 - 將
SKILL.md放在根目錄,以及scripts/、references/、assets/(如有)。 - 以環境期望的方式安裝技能(技能目錄文件夾或
.skill套件)。 - 觸發 1 個正向提示以確認激活。
**單檔案技能(UI 編輯器...