框架技能創作 (Framework Skill Authoring)
這是一個元技能 (meta-skill):一種用來建構技能的技能。只要指向任何你擁有原始碼的程式框架或函式庫,它就能產生一個自包含的 Agent Skills 家族,讓其他代理稍後僅需已安裝的套件(例如 wheel、jar 或同等形式)即可使用,無需原始碼、無需儲存庫、無需文件網站。
你是作者代理 (author agent)。你擁有原始碼。你的工作是捕捉未來消費者代理 (consumer agent) 會需要的所有資訊,並將其融入技能中,因為消費者代理將無法讀取程式碼。
何時使用此技能
- "為
<framework>建立 Agent Skills。" - "讓
<library>能被僅安裝了該函式庫的 AI 助理使用。" - "將此程式碼庫逆向工程為一個技能家族。"
- "為我們的框架建立一個入口路由器技能和多個能力技能。"
- "為
<framework>撰寫文件,讓筆記本內 / IDE 內的助理能夠驅動它。"
如果使用者只想要一個針對狹義任務的簡單技能,請改用一般的技能創作方法——此元技能是為了產生一個完整的家族來展現框架。
雙代理模型 (為什麼自包含至關重要)
flowchart LR
subgraph authorSide [作者端:擁有原始碼]
src[框架原始碼、測試、文件]
author[作者代理 + 此元技能]
end
subgraph out [產出成品]
fam[技能家族:<br/>入口路由器 + 能力技能<br/>+ 工作區指令]
end
subgraph consumerSide [執行時期:無原始碼]
consumer[消費者代理]
pkg[僅有已安裝的套件]
end
src --> author
author -->|分析、映射、產生、驗證| fam
fam --> consumer
pkg --> consumer
消費者代理通常在套件已安裝但儲存庫未安裝的環境中執行:例如資料平台的筆記本助理、IDE 助理,或是從 Agent Skills 標準目錄讀取技能的 CLI 代理。它可以執行程式碼並呼叫套件的公開 API,但無法開啟你的原始碼檔案。
黃金法則:為無法存取原始碼的消費者撰寫
消費者需要的所有東西都必須存在於生成的技能內部。
- 參考資料中不得包含原始碼檔案路徑(例如
src/...、tests/...、內部模組檔案)。這些路徑對消費者而言不存在。 - 所有程式碼範例都必須是完整且可複製貼上的,絕對不能寫 "詳見檔案 X"。
- 跨技能引用時,請使用技能名稱,而不是檔案路徑。
- 如果框架提供了執行時期文件/探索 API(一個能在執行時期回傳元件或欄位文件的函式),請將其整合到技能中,作為消費者處理你未內嵌之細節時的逃脫機制。
- 優先使用框架自己的公開原始元素,而非手刻程式碼;技能的存在是為了讓消費者使用框架,而不是繞過它。
完整規則:authoring-rules.md
開始之前
- 閱讀整份檔案。此檔案刻意保持簡短。
- 確認你確實擁有框架原始碼(儲存庫,或已解壓縮且程式碼可讀的套件)。如果你只有已安裝的套件,你就是消費者,而非作者——你無法從一個黑盒子進行創作。
- 將 assets/templates/authoring-plan.md 複製到你的工作計畫中並遵循它。在完成盤點清單之前,不要撰寫任何技能。
- 快速瀏覽參考資料庫(底下的表格),以便知道哪份指南能回答哪個問題。
作者代理的工作議程
請先產出這份計畫(範本:authoring-plan.md),並依序執行:
- 盤點框架——公開 API、設定/配置物件、領域模型、CLI 入口點、執行時期文件 API、範例/測試。填寫 capability-inventory.md。
- 映射盤點結果至能力分類,並決定要產出哪些技能。跳過框架缺少的領域。
- 萃取概念詞彙(層級、載入語意、模式、嚴重性等級、環境層級、技術欄位等)。
- 草擬從框架真實決策點衍生而來的入口路由器決策樹。
- 創作 workspace-instructions 檔案和入口路由器。
- 創作每個適用領域對應的一個能力技能。
- 自包含檢查——移除原始碼路徑、內嵌範例、串接執行時期文件 API、依名稱交叉連結同層級技能。
- 驗證——結構性檢查 + 針對每個關鍵使用者旅程 (CUJ) 進行無原始碼的消費者模擬。
- 根據差距反覆修正;將僅限貢獻者的領域標記為超出消費者範圍。
四個階段
階段 1 — 分析(你擁有原始碼)
盤點框架能做什麼以及使用者如何驅動它。要讀取的訊號以及如何讀取,請參考 analyze-framework.md。產出:一份已填寫的 capability-inventory.md。
階段 2 — 映射至通用分類法
針對每個能力領域,決定:框架是否具備此能力?如果有,則從能力範本產出一個技能;如果沒有,則跳過。去品牌化的領域檢查清單和映射規則請參考 universal-taxonomy.md。在映射的同時,也請使用 conceptual-taxonomies.md 記錄框架的概念詞彙——這些是無法存取原始碼的代理永遠無法猜到的列舉(載入類型、模式、嚴重性等級等)。
階段 3 — 生成家族
按此順序產出,使用範本和技能結構:
- workspace-instructions 檔案(範本)。
- 入口路由器技能(範本)——決策樹、心智模型、快速參考、技能索引、設定/路徑規則。根據 decision-tree-patterns.md 建立其決策樹。
- 每個適用領域對應的一個能力技能(範本)。
階段 4 — 驗證
進行結構檢查,然後模擬一個無法存取原始碼的消費者僅使用技能 + 已安裝套件來執行每個 CUJ。修正差距並重複。程序:validate-skills.md。
你產出的內容(輸出佈局)
為框架選擇一個短小、小寫的前綴 <fw>(例如套件的匯入名稱)。產出:
<deploy-root>/
├── workspace-instructions 檔案 # 總是注入的:「先閱讀 <fw>」+ 復原
└── skills/
├── <fw>/ # 入口路由器(決策樹 + 索引)
│ ├── SKILL.md
│ ├── references/ # 設定/路徑、遷移、深入參考資料
│ └── assets/templates/ # 消費者複製入門配置
├── <fw>-<capability-a>/
│ └── SKILL.md
├── <fw>-<capability-b>/
│ ├── SKILL.md
│ └── <sub-guide>.md # 內容較大時逐步揭露
└── ...
確切的部署根目錄和 workspace-instructions 機制取決於消費者平台——請確保兩者皆可設定,且絕不要硬編碼特定的供應商路徑。詳見 authoring-rules.md。
命名慣例
- 入口路由器技能名稱 =
<fw>(僅框架前綴)。 - 能力技能名稱 =
<fw>-<能力>,全小寫並使用連字號,例如<fw>-onboarding、<fw>-data-quality、<fw>-orchestration。 - frontmatter 中的
name:必須等於技能目錄的名稱。 - 名稱應具描述性,永遠不要使用
helper/utils/tools。
參考資料庫
| 指南 | 何時閱讀 |
|---|---|
| analyze-framework.md | 階段 1:從原始碼萃取能力訊號 |
| universal-taxonomy.md | 階段 2:決定要產出哪些能力技能 |
| conceptual-taxonomies.md | 階段 2:需要逐字捕捉的領域詞彙 |
| decision-tree-patterns.md | 階段 3:為路由器 + 技能建立決策樹 |
| skill-anatomy.md | 階段 3:每個 SKILL.md 的章節結構 |
| authoring-rules.md | 全過程:自包含 + 良好的描述 |
| validate-skills.md | 階段 4:檢查 + 無原始碼消費者模擬 |
範本
| 範本 | 用途 |
|---|---|
| authoring-plan.md | 你複製到自己的計畫中的議程 |
| capability-inventory.md | 階段 1 你要填寫的分析成品 |
| workspace-instructions.md | 總是注入的指令檔案 |
| entry-router.SKILL.md | 框架的頂層路由器技能 |
| capability.SKILL.md | 一個細粒度的能力技能 |