Community寫作與編輯github.com

ebursztein/agent-skills — 領域創作(Realm Authoring)

編寫或改進「代碼領域」(Realms of Code)的領域指南,包含實際觸發條件、具體行動、證據與奇幻風味。適用於撰寫憲章本身,而非在日常軟體工作中套用角色。

agent-skills — 領域創作(Realm Authoring) 是什麼?

此技能專為 AI 代理(如 Claude Code、Cursor 等)設計,用於指導其如何撰寫或改進「Realms of Code」框架中的領域指南(realm guide)。它提供了一套完整的創作流程,從閱讀現有指南與憲章開始,到撰寫具體的觸發條件,再到填充最佳實踐、證據與奇幻想像。技能強調「觸發條件必須放在主技能表」中,以便代理能根據具體情境(如測試檔案刪除、選擇 API 標準)快速選擇正確的領域。每個領域指南應包含名稱、紀律、座右銘、故事背景、公理、具體行動步驟與可觀察的證據。技能還透過「無面者」(Faceless Men)與「艾林」(Arryn)的範例,展示了如何將抽象設計模式(如依賴隔離、協定選擇)轉化為實用且可驗證的行動。最終目的是讓代理能自主判斷何時切換角色、如何執行任務,並確保每個領域指南簡潔、具體且不含冗餘資訊。支援平台:任何可讀寫 Markdown 並遵循 Realms of Code 約定的 AI 代理工具。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ebursztein/agent-skills/tree/HEAD/skills/realm-authoring

Installed? Explore more 寫作與編輯 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜歡的 AI 中提問

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

說明文件

領域創作

領域告訴代理何時執勤、下一步做什麼,以及如何確認任務完成。為這套紀律賦予一個令人印象深刻的組織風格。

寫作前

閱讀目標指南與憲章的觸發表。保留已商定的領域分配,並與相鄰領域區分開來。從使用者希望處理的真實開發情境出發。使用可識別的技術名稱:「mocks、stubs 和 fakes」比單用「controlled doubles」更易被發現。

將選擇邏輯放在主技能中

主要的 realms-of-code SKILL.md 擁有何時使用每個領域的決定權。其表格必須讓代理在載入指南前就能做出選擇。使用具體情境:測試檔案刪除、選擇 API 標準、或保護查詢計數改進。將觸發條件放在主技能中一次,而不是在各個指南中重複。

將最佳實踐放在領域指南中

  • 名稱、紀律、座右銘: 一個標題、一句具體的範圍說明、以及座右銘。
  • 故事背景: 一段簡短生動的文字,將派系與其工程角色連結起來。讓比喻解釋實際工作。
  • 公理: 幾條精簡的原則,指導決策。修改既有領域時,保留已建立的承諾。
  • 要做什麼: 以動詞開頭的實際步驟。說明要檢查或修改什麼、如何選擇方法、以及要驗證什麼。使用明確的技術名稱並重複使用專案的工具。解釋有意義的替代方案與陷阱。
  • 證據: 支援完成的可觀察結果或產出,以及該證據能證明什麼的重要限制。

公理解釋判斷;步驟使其可執行。避免在兩者中重複相同的建議。每個章節長度以完成其工作所需為準。領域參考檔案是純 Markdown:無 ID、無重複 YAML 欄位、無座右銘來源標籤或歸屬閒聊。只有可被發現的 SKILL.md 才需要技能前端資料。

校正範例

對於「無面者」,"controlling dependencies" 過於抽象。一個有用的觸發條件是「測試一個刪除檔案或呼叫外部支付服務的作業」。下一步是隔離該邊界,選擇 mock/stub/fake,並在不造成非預期真實影響的情況下,測試成功、失敗和重試行為。證據包括預期目標與最終狀態,以及在真正合約重要的地方提供整合證明。一個仍會呼叫真實服務的 spy 是值得命名的陷阱。

當伴隨的 realms-of-code 技能可用時,其 references/realms/faceless-men.md 是完整的示範範例。

對於「艾林」,「選擇協定」屬於主要觸發表。其指南必須說明:尋找現有標準與技術、驗證當前維護與棄用狀態、評估可行性、重複使用已支援的實作、以及測試互通性。

教導在實作期間進行保護:將重要規則編碼為護欄,將已驗證的改進編碼為棘輪。棘輪記錄可重現的基線、拒絕倒退、並在改進後收緊。學城建構保護;鐵金庫執行保護。絕不要透過悄悄地削弱檢查來解決失敗的檢查。

發布前審查

嘗試兩個真實的匹配任務,以及一個屬於其他領域的相近任務。從主表格中選擇領域,然後從其指南中找出第一個具體行動及所需的證據。如果任何一步仍不明確,則修改對應的檔案。避免與任務無關的籠統閘門。

在座右銘、故事背景和偶爾使用的工作語句中保持風味,例如「我們對 Bug 說什麼?今天不行。」將其與有用的工程指導搭配。刪除既不增加決策也不增添角色的文字。遵循儲存庫的發布工作流程,並在受影響時驗證相對連結與技能的可發現性。

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

相關技能