啟動契約
當為 Pi 或其他代理執行環境建立或更新可重複使用的 AI 技能時，使用此技能。
在以下情況建立技能：
- 某個工作流程或慣例會跨階段重複使用；
- 通用代理行為需要加入專案特定的約束；
- 存在一個能幫助代理安全選擇的決策樹；
- 範例、模板或參考資料能使未來執行更可靠。
請勿為一次性任務、通用文件，或應歸屬於程式碼/測試的規則建立技能。
嚴格規則
- 遵循
docs/skill-style-guide.md作為技能結構與風格的規範來源。 - 技能是 LLM 執行合約，而非面向人類的文件。
- 保持
SKILL.md簡潔：目標 180–450 tokens，最多 1000 tokens。 - 使用命令式指令與具體門檻；避免教學或背景敘述。
- frontmatter 中的
description須為單行 YAML 安全的字串，並以觸發詞開頭。 - 不要添加
Keywords區段；將必要的觸發詞放入description。 - 將模板、結構與生成的範例放入
assets/。 - 將較長的解釋或本機文件連結放入
references/。 - 修改專案技能後，若有可用功能，請使用
/skill-registry:refresh重新整理註冊表。
決策門檻
| 需求 | 動作 |
|---|---|
| 小型可重複使用的行為 | 僅建立 skills/{skill-name}/SKILL.md |
| 模板、結構、配置檔案 | 加入 skills/{skill-name}/assets/ |
| 較長的說明或邊界情況 | 加入 skills/{skill-name}/references/ |
| 已有技能涵蓋此需求 | 改為更新現有技能 |
| 技能影響代理發現機制 | 確保觸發詞出現在 description 中 |
執行步驟
- 在建立或更新技能前，先閱讀
docs/skill-style-guide.md。 - 檢查現有技能，確認新技能不與任何技能重複。
- 選擇一個符合使用者觸發詞的 kebab-case 技能名稱。
- 建立或更新以下結構：
skills/{skill-name}/
├── SKILL.md
├── assets/ # 選用
└── references/ # 選用
- 使用此 frontmatter 格式：
---
name: {skill-name}
description: "Trigger: {使用者或代理會說出的短語}。{技能的功能說明}。"
license: Apache-2.0
metadata:
author: gentleman-programming
version: "1.0"
---
- 依此順序撰寫各區段：啟動契約、嚴格規則、決策門檻、執行步驟、輸出契約、參考資料。
- 若這是一個打包的
gentle-pi技能，請將其加入scripts/verify-package-files.mjs。 - 重新整理或記錄技能註冊表的更新路徑。
輸出契約
回傳：
- 已建立或修改的檔案。
- 是建立新技能還是更新現有技能。
- 任何已加入的輔助
assets/或references/檔案。 - 是否需要套件驗證或技能註冊表重新整理。
參考資料
docs/skill-style-guide.md— 以 LLM 為優先的技能風格指南。skills/skill-registry/SKILL.md— 註冊表重新整理與索引契約。