前言¶
在 Cursor、Claude Code、Gemini CLI 等環境裏給 Agent 加「專項能力」，常見做法是寫一長段系統提示或項目規則。提示會越堆越長，換工具就要重寫，也很難用版本管理做評審。Agent Skills 把能力收成可移植的文件夾：元數據加說明文檔，必要時附帶腳本與參考資料。問題是規範裏有不少硬性約定——目錄怎麼命名、SKILL.md 要寫哪些節、代碼示例該放哪裏、發佈前如何校驗。meta-skill-creator 是一套面向「寫 Skill 的人」的 Meta Skill：它按 Agent Skills 開放標準 梳理完整流程，適合作爲理解 Skill 生態的入門材料。
這是什麼¶
meta-skill-creator 由 oakoss 維護，倉庫路徑爲 oakoss/agent-skills/skills/meta-skill-creator，許可爲 MIT，Skill 元數據版本爲 1.0，規範來源標註爲 agentskills.io。
它的定位是：在 Claude Code、Cursor、Gemini CLI 及其他兼容 Agent 上，指導你完成新 Skill 的創建、結構設計與驗證。覆蓋 Skill 結構、SKILL.md 撰寫、frontmatter 配置、漸進式披露、reference 文件、校驗與分發等環節。Skill 自身設置了 disable-model-invocation: true，表示由人在合適場景下啓用，而不是默認讓模型隨意調用。
根據 Agent Skills 概覽，Skill 本質是包含 SKILL.md 的文件夾，可附帶 scripts/、references/、assets/ 等；Agent 通過漸進式披露按需加載，從而在保留大量 Skill 的同時控制上下文佔用。
核心功能¶
下面介紹 meta-skill-creator 在資料中明確列出的能力要點。
目錄與必需文件¶
標準結構以 skill-name/SKILL.md 爲核心，可選目錄包括 references/、scripts/、assets/。唯一必需文件是 SKILL.md。
Frontmatter 與命名¶
必填 YAML 字段爲 name 與 description：name 必須與父目錄名完全一致，最長 64 字符；命名僅允許小寫字母、數字與連字符，不得出現 --，不得以 - 開頭或結尾，最少 4 個字符。可選字段包括 license、compatibility、metadata、allowed-tools 等，由開放標準定義，便於跨 Agent 移植。部分 Agent 專有擴展（如 model、context、hooks）在資料中標註爲不可移植。
description 應包含 “Use when…” 或 “Use for…” 等觸發短語，用第三人稱、關鍵詞豐富的寫法，便於 Agent 發現何時啓用該 Skill。
SKILL.md 結構與篇幅¶
SKILL.md 須包含五個固定章節：Overview、Quick Reference、Common Mistakes、Delegation、References。目標篇幅約 100–150 行，上限 500 行；不在 SKILL.md 內放代碼示例，示例應拆到 references/。
漸進式披露分三層：元數據 → 指令正文 → 資源文件；SKILL.md 全文在激活時加載，reference 按需讀取。
Reference 與腳本¶
references/[topic].md 每個文件建議自包含、從 SKILL.md 僅一層鏈接，單文件上限 500 行，且需帶 frontmatter：title、description、tags。scripts/ 下放可執行代碼；Agent 執行腳本而非通讀源碼。
分發時排除的文件名包括 README.md、metadata.json 以及以 _ 開頭的文件。
校驗與協作分工¶
發佈前應運行項目自帶校驗器或 skills-ref validate。規範細節可查 Agent Skills specification；需要對照現有 Skill 結構時，資料建議用 Explore 類 Agent 做模式發現。
安裝與啓用¶
Skill 可按作用域放在不同路徑（資料中的示例如下，具體產品是否完全一致以各客戶端文檔爲準）：
| 作用域 | 路徑 | 說明 |
|---|---|---|
| 個人 | ~/.claude/skills/ |
當前用戶、所有項目 |
| 項目 | .claude/skills/ |
倉庫內共享 |
| 分發 | 通過 skills CLI |
插件或包用戶 |
將 meta-skill-creator 作爲文件夾安裝到上述兼容目錄後，在 Cursor 等客戶端中按產品說明啓用 Skills 即可。資料未給出單獨的 git clone 或一鍵安裝命令，獲取源碼以官方倉庫爲準。
典型用法：創建新 Skill 的工作流¶
官方在 Skill 內歸納的五步流程可直接復現：
- 在合適位置新建目錄，並創建
SKILL.md。 - 編寫 frontmatter：
name與目錄名一致，description寫清觸發場景。 - 寫完五個必需章節（Overview、Quick Reference、Common Mistakes、Delegation、References）。
- 把代碼示例抽到
references/，保持SKILL.md無代碼塊示例。 - 用
skills-ref validate或項目校驗器驗證後再分發。
frontmatter 示例（字段含義見上文，此處僅示意結構）：
---
name: my-skill-name
description: >
Short summary of what the skill does.
Use when ...
Use for ...
license: MIT
metadata:
author: your-name
version: '1.0'
---
校驗示例：
skills-ref validate
meta-skill-creator 還通過 references/ 鏈接更細的說明，例如 skill-anatomy、frontmatter、validation 等主題，寫 Skill 時可按需讓 Agent 加載對應 reference。
適用場景與注意¶
適合誰： 要在多 Agent 環境複用同一套工作流說明的開發者；團隊希望把流程、檢查清單、腳本打包成可版本管理的 Skill；需要系統瞭解 agentskills.io 規範而非憑感覺寫 Markdown 的人。
常見錯誤（資料中的對照表）： 缺少 “Use when/for” 觸發語；在 SKILL.md 裏寫代碼；reference 互相深層嵌套；name 與目錄不一致；frontmatter 第一行前有空行；reference 缺少 title/description/tags；未在 SKILL.md 中顯式鏈接支撐文件。
限制： 開放標準字段與 Claude Code 等擴展字段需區分，避免不可移植配置。SKILL.md 行數與 reference 深度、自包含性都有硬性建議，忽視後可能導致校驗失敗或 Agent 加載不全。資料稱兼容 27+ Agent 客戶端，具體支持列表以 agentskills.io 的 Client Showcase 爲準。
結尾¶
meta-skill-creator 的價值在於把「教 Agent 做事」收斂成可檢驗的文件夾規範：結構、觸發描述、漸進披露和校驗步驟都寫死在流程裏，減少各工具各寫一套說明的重複勞動。若要上手或對照規範，可從官方倉庫閱讀完整 SKILL.md 與 reference：https://github.com/oakoss/agent-skills/tree/main/skills/meta-skill-creator。
