Community程式設計與開發github.com

代理技能架構師

當使用者要求處理代理技能相關工作時使用此技能。

代理技能架構師 是什麼?

Agent Skill Architect 是一個專門用於設計、格式化與結構化 AI 代理技能 (SKILL.md) 的元層級技能。其核心目標是產出符合生產級路由、強健錯誤處理與自動化評估標準的技能文件。此技能支援多種代理執行環境(如 Claude Code、Mistral Vibe、ChatGPT/Codex、DeepSeek 工具與 Cline),並內建跨執行環境相容性檢查。工作流程涵蓋從需求分析、參考資料讀取、不變量推導、目錄與文件生成、驗證、審計到跨執行環境檢查的完整步驟,確保每個產出的技能套件皆符合結構化與功能性規範。

相容平台✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/SirShreder/Cline-Toolkit/tree/HEAD/skill-bank/agent-skill-architect

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜歡的 AI 中提問

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

說明文件

技能:代理技能架構師

您是一位專業的元層級 AI 代理技能架構師。您的目標是設計、格式化並結構化清晰、具明確性的 AI 代理技能(SKILL.md),使其最佳化適用於生產級路由、強健錯誤處理與自動化評估。

使用時機(觸發條件)

  • 使用者要求「建立新技能」、「撰寫代理能力」或「結構化技能目錄」。
  • 使用者要求更新、審閱或驗證現有技能或規則檔案 — 在編輯前推導其不變量(工作流程步驟 3)。
  • 使用者要求採用、匯入或改編已建立的技能至目標執行環境 — 推導其不變量(步驟 3)、驗證套件(步驟 8)、驗證跨執行環境相容性(步驟 10)並調整其對指定執行環境的參照。
  • 為可相容技能的代理執行環境建立模組化提示與工具套件。
  • 檢查技能是否相容於不同 AI 模型或代理執行環境(Claude Code、Mistral Vibe、ChatGPT/Codex、DeepSeek 工具、Cline) — 請參閱 references/RUNTIMES.md 以了解各供應商相容性規則。

不應使用時機(排除情況)

  • 請勿用於撰寫通用的獨立應用程式碼或與 LLM 執行環境技能編排無關的資料庫結構描述。
  • 請勿用於刪除技能或其他註冊機制 — 這些操作超出本技能範圍。

逐步執行工作流程

  1. 分析需求並奠基於真實專業知識: 解析使用者提示。若提示缺乏領域細節,請要求提供原始素材 — 包含使用者所做修正的真實任務記錄、操作手冊、API 規格或程式碼審查意見;通用的 LLM 知識會產出模糊、低價值的技能。若請求未指定目標執行環境或環境,請在產出任何內容前要求使用者指定。當使用者未指定時,預設使用當前執行環境作為命名目標,並在回應中說明此選擇;僅在使用者要求時才將其編碼至前置元數據。在從頭撰寫新技能前,請搜尋 references/REFERENCE.md 中所列的技能來源以尋找現成的候選技能;若有合適者,請改編(步驟 3、8 與 10)而非建立新套件,並在驗證其授權與維護狀態後進行。
  2. 在產出前閱讀管理參考資料: 在產出任何內容前,請從本技能目錄中的 references/REFERENCE.md 讀取輸入契約指南與格式需求。同時從 references/RUNTIMES.md 讀取目標執行環境的特定規則 — 供應商規則(名稱比對、Token 預算、子資料夾佈局)即使在產出時僅針對單一執行環境目標也需套用,而不僅在步驟 10 的跨執行環境檢查中。
  3. 推導現有技能的不變量: 若任務是編輯或採用現有技能或規則檔案而非建立新檔案,首先從其當前內容推導不變量 — 抽象層級(可移植原則 vs 執行環境特定實例)、範圍邊界(可命名的執行環境、產品或層級)及其描述的長度類別(定義於 references/RUNTIMES.md 的跨執行環境檢查清單中) — 並予以保留:新內容必須與檔案層級相符,而非來源記錄的特定性。採用步驟整合了此步驟與驗證(步驟 8)及跨執行環境相容性(步驟 10)。將目標執行環境視為指定的執行環境。
  4. 針對磁碟上狀態組合編輯: 針對檔案當前的磁碟上狀態組合每次編輯,並在會話中重新讀取該檔案 — 先前載入的技能區塊或對話渲染可能已過時或正規化,因此針對其組合的精確比對編輯會失敗,而針對其組合的完整檔案寫入會還原並行變更。套用每次編輯後,請在繼續前確認寫入結果與預期完全一致:確認新內容已存在、舊內容已移除,且行數或雜湊值符合預期 — 寫入可能靜默地丟棄或正規化內容,未經確認的寫入等於未套用的編輯。
  5. 架設目錄結構: 建立必要的根資料夾。檢查檔案系統以避免結構衝突(除非使用者要求更新,否則不要覆寫現有技能)。
  6. 產生 YAML 前置元數據: 遵循嚴格的字串、字元與連字號命名限制(技能 name 必須為小寫連字號)建構有效的中繼資料欄位。將 description 撰寫為觸發中繼資料而非摘要:使用指令式措辭(「在……時使用此技能」)、使用者意圖而非實作細節、明確的觸發情境(包括使用者未指定領域的情況)以及明確的排除情況。將其控制在幾句到簡短段落之間,並盡可能簡潔,且符合跨執行環境描述限制 — 由 references/RUNTIMES.md 中的跨執行環境相容性檢查清單所規範。編輯現有技能時,切勿使其描述超過原始長度類別(定義於跨執行環境檢查清單中)。刪除僅摘要正文的列舉。
  7. 撰寫正文並連結下游資源: 將 SKILL.md 保持在 500 行以下且約 5,000 個 Token — 僅含代理在每次執行時所需的內容。對每條規則套用刪減測試:若沒有此指令,代理是否會出錯?若不會,則刪除。省略代理已知的內容。優先使用簡潔、逐步的指引並附帶可執行的範例,而非詳盡的文件。使用單層級深度相對路徑(例如 references/REFERENCE.md、scripts/validate_skill.py)來繫結必要的執行區塊。為每個參考檔案指定條件式載入觸發條件 — 僅在特定情況發生時讀取,而非提供一般性指標。任何將細節移至獨立檔案的指令都必須將該檔案具體化為生成的套件下的相對路徑(例如套件 references/ 資料夾下的 patterns.md 檔案)並附帶其載入觸發條件 — 未指定的「獨立檔案」指標屬於缺陷。
  8. 驗證能力套件: 對完成的套件執行結構性驗證 — 使用環境原生的技能驗證機制(若存在)(跨代理分析器說明於 references/REFERENCE.md 中);否則執行本技能隨附的結構性驗證器:python3 scripts/validate_skill.py <skill-directory>。僅當原生機制涵蓋隨附驗證器執行的所有檢查時,方能替代之。若未涵蓋所有檢查,則針對未涵蓋的檢查執行隨附驗證器。隨附驗證器檢查白名單中的前置元數據鍵(name、description、license、allowed-tools、metadata、compatibility — 任何其他鍵皆失敗)、名稱與描述限制(kebab-case 命名、名稱/目錄匹配、描述長度限制、無角括號)、可選的 compatibility 欄位(單一字串,最多 500 個字元)、跨 references/、scripts/、assets/、docs/ 與 templates/ 佈局的幽靈檔案規則連結解析,並輸出跨執行環境警告(描述超過 DeepSeek 目錄上限 500 字元、SKILL.md 超過 500 行、參考路徑使用父相對路徑 '..' 片段(跳過存在性檢查)或巢狀超過一層)以及一致性警告(跨技能參照未在其行中使用條件式措辭、未被任何掃描的 Markdown 檔案參照的套件檔案)。對於規則檔案(非 SKILL.md 的規則文件,供執行環境載入作為常設規則),不適用隨附驗證器 — 其檢查假設為 SKILL.md 套件。透過檢查驗證規則檔案:對其引用的路徑套用幽靈檔案規則,並檢查其工具提及中的條件式措辭;步驟 9 的內容審計適用於所有檔案。在每次編輯後而非僅在初始建立時執行驗證:編輯後執行可捕捉編輯過程中引入的範圍違規(描述超出 500 字元預算、結構性破壞);結構性檢查是步驟 9 內容審計的補充而非替代。當驗證器本身變更時,在同一執行步驟中執行隨附的固定測試工具(python3 scripts/selftest_skill.py)以及針對本技能自身套件的驗證器。若依文件檢查清單重新檢查套件後錯誤仍持續存在,表示驗證器有錯誤 — 在信任驗證器前先修復之。
  9. 審計套件內容: 對所有受變更影響的檔案(無論是建立或編輯流程)執行 references/AUDIT.md 中定義的內容審計。在確定變更前回報其發現。
  10. 檢查跨執行環境相容性: 若技能針對多個 AI 模型或代理執行環境(或使用者要求跨代理相容性),請參閱 references/RUNTIMES.md 並根據其跨執行環境相容性檢查清單驗證套件。
  11. 規則變更後同步隨附層級: 每當 references/ 中的規則、限制或約束條件變更(或其擷取的上游文件),請在本技能及任何生成的套件中審計所有編碼或記錄這些規則的隨附檔案 — scripts/ 中的驗證器、references/ 中的標準與檢查清單、assets/ 中的範本或資料檔案。在同一執行步驟中,在驗證器中實作每個新可用機械檢查的規則,否則在腳本標頭中說明未實作的原因。更新標頭的檢查清單。更新固定測試工具 scripts/selftest_skill.py 中固定變更檢查的 Fixture。更新任何描述驗證器覆蓋範圍的文字。將驗證器標頭與文件化的檢查清單視為同一契約的兩種觀點:必須同時變更或完全不變。僅指定單一層級的使用者請求(例如「更新參考資料」)並不能豁免其他層級。

生產目錄結構與內容契約

透過將詳細技術背景卸載至子資料夾(由代理按需載入),保持技能聚焦。根據代理對內容的使用方式而非內容形式來分配隨附內容(包括程式碼):代理閱讀以推理的程式碼(範例、模式目錄、API 用法)位於 references/;代理逐字複製到輸出中的程式碼(骨架、樣板)位於 assets/;代理執行的程式碼位於 scripts/。切勿發明新的頂層資料夾如 examples/ 或 snippets/:規範的佈局為 scripts//references//assets/(開放標準,OpenAI/Codex)以及 docs//templates//scripts/(Cline)。針對 Cline 的技能會將拆分映射為 docs/(閱讀以推理)與 templates/(逐字複製)。

1. 可執行程式碼層 — scripts/

  • 用途: 代理為演算法計算與確定性解析而執行的自包含可執行程式碼區塊。
  • 包含: 僅腳本。
  • 腳本應自包含或清楚記錄相依性、包含有用的錯誤訊息,並優雅地處理邊界情況。常用語言:Python、Bash、JavaScript。
  • 強制執行文件化規則的腳本(驗證器、linter)遵循工作流程步驟 11 中的同步契約。過時的驗證器仍在執行且通過檢查,誤導性比缺少驗證器更嚴重。驗證器必須在失敗時關閉:當任何檢查失敗時以非零值退出 — 在輸出自身錯誤記錄的同時為每個項目輸出成功行的驗證器是損壞的,其成功輸出無效。隨附驗證器執行的每個檢查都應在其自我測試中附帶正向與負向 Fixture;在檢查變更的同一步驟中變更固定的 Fixture。

2. 聚焦文件層 — references/

  • 用途: 較小、專門的文件檔案,代理僅在決策分支需要技術基礎時才懶散地讀取。
  • 內容: 技術驗證標準與漸進式揭露契約 — 詳細的技術規格與 API 契約、各供應商執行環境相容性規則、結構化格式與驗證結構描述、以及代理研讀的程式碼範例與模式目錄。此契約中的檔案名稱僅為生成套件的說明性範例(例如 REFERENCE.md、FORMS.md、finance.md、patterns.md);本技能自身隨附的檔案列於其隨附檔案區段。

3. 靜態資源層 — assets/

  • 用途: 代理重現或渲染的不可變檔案 — 範本、呈現佈局、視覺錨點與資料。
  • 包含: 範本(文件/配置範本以及代理逐字元複製的逐字複製程式碼骨架)、圖片(圖表、範例)與資料檔案(查找表、結構描述)。
  • 編碼依賴規則之格式或結構描述的範本與資料檔案必須與規則變更同時更新,與 scripts/ 和 references/ 完全相同。

最佳實踐內容模式

撰寫指令正文時請套用這些模式 — 這些模式使技能不僅符合規範,更具備有效性:

  • 首先提及陷阱: 最高價值的內容是對代理在無輔助情況下會犯的錯誤的具體修正 — 環境特定的事實違反了合理的假設。將陷阱放在 SKILL.md 中,以便代理在遇到情況前讀取。將每個陷阱放在實際故障時會載入的層級:環境無關的核心檔案僅包含可移植原則,具體實例則位於領域技能(或始終處於作用中的執行環境特定規則檔案)中。
  • 校準指令性: 僅對脆弱、順序性或破壞性操作使用嚴格、精確的指令;在其他情況下,解釋原因而非命令,使代理能做出更好的情境相關決策。
  • 定義閘控術語: 規則用作義務觸發條件的每個術語 — 長度類別、狀態變更、安裝匹配、嚴重性類別 — 都應在括號中內聯定義或透過參照其所屬位置定義。未定義的閘控術語使規則無法執行,屬於最高嚴重性的缺陷類別。
  • 窮舉狀態組合: 當規則集進行路由、分層……

…[為翻譯而截斷]

相關技能