Communitygithub.com

grusin-db/framework-skill-authoring

元技能(Meta-skill):將任何框架的原始碼轉換為自包含的 Agent Skills 家族,之後可僅從已安裝的套件(例如在 Databricks Genie Code 或任何 AI 編碼代理中)使用。

framework-skill-authoring 是什麼?

這是一個「元技能」(meta-skill),專門用於從框架或函式庫的原始碼,自動生成一個**完整的 Agent Skills 家族**。它遵循「雙代理模型」(two-agent model):在「作者代理」階段,代理擁有原始碼,負責盤點 API、領域模型、設定等,並將這些知識完整地封裝進生成的技能中;在「消費者代理」階段,另一個沒有原始碼的代理(例如在 Databricks Genie Code、IDE 或 CLI 中運行的代理)僅依賴已安裝的套件(如 wheel 或 jar)就能透過這些技能來驅動該框架。此技能的核心原則是「自包含」(self-containment),所有產出的技能內都包含完整的、可複製貼上的程式碼範例,且絕不依賴原始碼路徑。它支援作者代理規劃、盤點、映射至通用分類法,並最後生成一個入口路由器 (entry router) 和多個能力技能 (capability skills)。最終輸出結構包含 workspace-instructions 檔案和一個以框架前綴命名的技能目錄,適合任何 AI 編碼代理平台使用。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add grusin-db/framework-skill-authoring

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

框架技能創作 (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

開始之前

  1. 閱讀整份檔案。此檔案刻意保持簡短。
  2. 確認你確實擁有框架原始碼(儲存庫,或已解壓縮且程式碼可讀的套件)。如果你只有已安裝的套件,你就是消費者,而非作者——你無法從一個黑盒子進行創作。
  3. 將 assets/templates/authoring-plan.md 複製到你的工作計畫中並遵循它。在完成盤點清單之前,不要撰寫任何技能。
  4. 快速瀏覽參考資料庫(底下的表格),以便知道哪份指南能回答哪個問題。

作者代理的工作議程

請先產出這份計畫(範本:authoring-plan.md),並依序執行:

  1. 盤點框架——公開 API、設定/配置物件、領域模型、CLI 入口點、執行時期文件 API、範例/測試。填寫 capability-inventory.md。
  2. 映射盤點結果至能力分類,並決定要產出哪些技能。跳過框架缺少的領域。
  3. 萃取概念詞彙(層級、載入語意、模式、嚴重性等級、環境層級、技術欄位等)。
  4. 草擬從框架真實決策點衍生而來的入口路由器決策樹。
  5. 創作 workspace-instructions 檔案和入口路由器。
  6. 創作每個適用領域對應的一個能力技能。
  7. 自包含檢查——移除原始碼路徑、內嵌範例、串接執行時期文件 API、依名稱交叉連結同層級技能。
  8. 驗證——結構性檢查 + 針對每個關鍵使用者旅程 (CUJ) 進行無原始碼的消費者模擬。
  9. 根據差距反覆修正;將僅限貢獻者的領域標記為超出消費者範圍。

四個階段

階段 1 — 分析(你擁有原始碼)

盤點框架能做什麼以及使用者如何驅動它。要讀取的訊號以及如何讀取,請參考 analyze-framework.md。產出:一份已填寫的 capability-inventory.md。

階段 2 — 映射至通用分類法

針對每個能力領域,決定:框架是否具備此能力?如果有,則從能力範本產出一個技能;如果沒有,則跳過。去品牌化的領域檢查清單和映射規則請參考 universal-taxonomy.md。在映射的同時,也請使用 conceptual-taxonomies.md 記錄框架的概念詞彙——這些是無法存取原始碼的代理永遠無法猜到的列舉(載入類型、模式、嚴重性等級等)。

階段 3 — 生成家族

按此順序產出,使用範本和技能結構:

  1. workspace-instructions 檔案(範本)。
  2. 入口路由器技能(範本)——決策樹、心智模型、快速參考、技能索引、設定/路徑規則。根據 decision-tree-patterns.md 建立其決策樹。
  3. 每個適用領域對應的一個能力技能(範本)。

階段 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一個細粒度的能力技能

相關技能