skill-creator

核心原則

簡潔是關鍵。 上下文視窗是系統提示、技能、對話歷史和你推理的共享資源。SKILL.md 中的每一行都與其他內容競爭。只加入你還不知道的內容——不要記錄系統提示中已可見的工具參數，不要為你能自行解決的事情規定逐步工作流程。專注於領域知識、解讀指南、決策框架和注意事項。

漸進式揭露。 技能分三層載入：

1. 始終在上下文中 — 名稱、表情符號和描述會出現在每次對話的 <available_skills> 中。這是你決定啟用哪個技能的方式。描述必須是強烈的觸發條件。
2. 啟用時 — 當你決定技能相關時，透過 read_file 載入完整的 SKILL.md 主體。工作流程、指南和決策樹放在這裡。
3. 按需載入 — scripts/、references/ 和 assets/ 只在明確需要時載入。大量內容放在這裡，而不是主體中。

這意味著：保持 SKILL.md 主體精簡（少於 500 行）。將詳細的 API 文件放在 references/。將自動化放在 scripts/。主體應該是你開始工作所需的內容，而不是百科全書。

自由度。 將指令的具體程度與任務的脆弱性匹配：

• 高自由度（文字指導）— 當多種方法都有效時。用自然語言解釋「做什麼」和「為什麼」，而不是逐步的「怎麼做」。範例：「檢查資金費率和社交情緒來評估市場氣氛。」
• 中自由度（虛擬碼 + 參數）— 當有偏好的模式但細節可以變化時。用關鍵參數描述方法。範例：「使用週期 14 的 RSI，低於 30 買入，高於 70 賣出。」
• 低自由度（scripts/ 中的腳本）— 當操作脆弱、需要精確語法或重複性樣板時。將程式碼放在獨立腳本中執行，而不是載入到上下文。範例：使用精確顏色代碼和 API 呼叫的圖表渲染。

預設假設：你已經很聰明。只加入你還沒有的上下文。

技能的結構

my-skill/
├── SKILL.md          # 必要：前置資料 + 指令
├── scripts/          # 選用：可執行程式碼（低自由度）
│   └── render.py     #   透過 bash 執行，不載入上下文
├── references/       # 選用：按需載入的文件（中自由度）
│   └── api-guide.md  #   需要時透過 read_file 載入
└── assets/           # 選用：範本、圖片、資料檔案
    └── template.json #   不載入上下文，用於輸出

何時使用各目錄：

目錄	是否載入上下文？	用途
SKILL.md 主體	啟用時	核心工作流程、決策樹、注意事項
scripts/	永不（執行）	脆弱操作、精確語法、樣板
references/	按需	詳細 API 文件、長指南、查詢表
assets/	永不	用於輸出的範本、圖片、資料檔案

建立技能

步驟 1：理解需求

在建立之前，了解你要建構什麼：

• 什麼能力？ API 整合、工作流程自動化、知識領域？
• 什麼觸發條件？ 代理應該在何時啟用此技能？（這將成為描述。）
• 什麼自由度？ 代理可以即興發揮，還是需要精確腳本？
• 什麼依賴？ API 金鑰、二進位檔、Python 套件？

範例：

• 「我想產生圖表」→ 繪圖技能，附帶腳本（低自由度渲染）
• 「幫我思考交易策略」→ 知識技能（高自由度，對話式）
• 「整合 Binance API」→ API 技能，附帶環境變數需求和參考文件

步驟 2：建立骨架

使用初始化腳本：

python skills/skill-creator/scripts/init_skill.py my-new-skill --path ./workspace/skills

附帶資源目錄：

python skills/skill-creator/scripts/init_skill.py api-helper --path ./workspace/skills --resources scripts,references

附帶範例檔案：

python skills/skill-creator/scripts/init_skill.py my-skill --path ./workspace/skills --resources scripts --examples

步驟 3：規劃可重複使用的內容

在撰寫之前，決定內容的放置位置：

• SKILL.md 主體：代理每次啟用此技能時需要的核心指令。決策樹、解讀指南、「何時做 X vs Y」的邏輯。
• scripts/：任何必須完全按原樣執行的程式碼——帶有特定驗證的 API 呼叫、精確格式的渲染、資料處理管線。
• references/：代理偶爾需要的詳細文件——完整的 API 端點列表、結構定義、故障排除指南。
• assets/：代理複製/修改以用於輸出的輸出範本、圖片、設定檔。

步驟 4：撰寫 SKILL.md

先規劃內容——前置資料觸發條件、主體結構、自由度。然後：

1. 前置資料 — 更新描述（關鍵觸發條件）、新增需求、設定表情符號
2. 主體 — 為代理撰寫，而非使用者。使用短段落而非大量項目符號。表達觀點而非含糊其辭。

主體的設計模式：

• 基於工作流程 — 逐步流程（繪圖：取得資料 → 設定圖表 → 渲染 → 提供服務）
• 基於任務 — 按使用者可能提出的問題組織（交易：「分析幣種」/「比較策略」/「檢查情緒」）
• 參考/指南 — 規則和框架（策略：核心真理、對話風格、何時提取資料）
• 基於能力 — 按技能能做的事組織（市場資料：價格工具 / 衍生工具 / 社交工具）

步驟 5：透過 skill_manage 建立/更新

skill_manage 是主要工作流程——它驗證前置資料、執行安全掃描並自動重新載入快取。不要使用 write_file 作為主要路徑。

建立新技能：

skill_manage(action="create", name="my-skill", content="---\nname: my-skill\n...")

修補現有技能（針對性修改的首選）：

# 務必先 read_file 以取得精確的空白/內容
skill_manage(action="patch", name="my-skill", old_string="exact old text", new_string="new text")

完全重寫現有技能：

skill_manage(action="edit", name="my-skill", content="---\nname: my-skill\n...")

⚠️ 已知注意事項：

• create 在技能已存在時會報錯 → 改用 edit 或 patch。
• edit/patch 在技能不存在時會報錯 → 先使用 create。
• patch 需要精確匹配 old_string（包含空白）→ 修補前務必 read_file。
• execute() 必須接受 **kwargs——如果你看到 unexpected keyword argument 'action'，那是工具實作的錯誤（修正：def execute(self, **kwargs)）。

僅作為備用——如果 skill_manage 不可用，手動使用 write_file + skill_refresh()。

步驟 6：驗證

python skills/skill-creator/scripts/validate_skill.py ./workspace/skills/my-new-skill

在 skill_manage 之後，驗證是可選的（已自動重新載入），但執行它以及早發現結構問題。

前置資料格式

前置資料使用 metadata.starchild 來存放 Star Child 專用欄位：

---
name: skill-name
version: 1.0.0
description: "此技能的功能。在[特定觸發情境]時使用。"

metadata:
  starchild:
    emoji: "🔧"
    skillKey: skill-name
    requires:
      env: [API_KEY_NAME]
      bins: [python]
      anyBins: [curl, wget]
    install:
      - kind: pip
        package: pandas
      - kind: apt
        package: curl
        bins: [curl]

user-invocable: true
disable-model-invocation: false
---

欄位參考：

欄位	位置	必要	用途
name	頂層	是	技能識別碼（小寫連字號）
version	頂層	是	語意版本（例如 1.0.0）。發布時必要。務必包含。
description	頂層	是	觸發文字——代理何時應使用此技能？
emoji	metadata.starchild	否	顯示用表情符號
skillKey	metadata.starchild	否	去重金鑰
requires.env	metadata.starchild	否	必要的環境變數
requires.bins	metadata.starchild	否	必要的二進位檔（全部必須存在）
requires.anyBins	metadata.starchild	否	必要的二進位檔（任一存在即可）
install	metadata.starchild	否	如何安裝依賴（pip、apt、npm 等）
user-invocable	頂層	否	使用者能否透過 /command 觸發（預設：true）
disable-model-invocation	頂層	否	從 <available_skills> 隱藏（預設：false）

鏈上技能——錢包政策前提

如果技能涉及任何鏈上操作（發送交易、代幣授權、交換、跨鏈橋接、簽署、存款、提款、智慧合約互動），請在 SKILL.md 頂部附近新增「前提條件」章節：

## 前提條件——錢包政策
在執行任何[操作]之前，錢包政策必須處於啟用狀態。
載入 **wallet-policy** 技能並提議標準萬用字元
政策（拒絕金鑰匯出 + 允許 `*`）。這涵蓋所有[技能名稱]
操作，適用於所有鏈。

這確保代理在嘗試任何交易之前提議錢包政策。否則，第一筆交易會因政策違規而失敗。

不應包含的內容

• README.md — SKILL.md 就是 readme。不要重複。
• CHANGELOG.md — 技能不是版本化的套件。
• 代理已有的文件 — 不要重複系統提示中的工具描述。
• 簡單任務的逐步說明 — 代理能自行解決「讀取檔案然後處理」。
• 通用程式設計建議 — 「使用錯誤處理」是雜訊。具體注意事項才是訊號。

最佳實踐

1. 描述就是觸發條件。 這是代理決定啟用你技能的方式。包含「在……時使用」並附上具體情境。糟糕：「交易工具。」良好：「用真實歷史資料測試交易策略。在策略需要驗證或決定交易方法前使用。」

2. 為代理撰寫，而非使用者。 技能是給 AI 的指令。使用直接語言：「你產生圖表」而非「此技能可用於產生圖表」。

3. 腳本執行而不載入。 適合大型自動化。代理只在需要自訂時讀取腳本，保持上下文乾淨。

4. 不要重複系統提示。 代理已經看到工具名稱和描述。專注於它沒有的知識：解讀指南、決策樹、領域特定注意事項。

5. 最後才要求憑證。 先設計技能，然後再向使用者要求 API 金鑰。

6. 重新整理前務必驗證——執行 validate_skill.py 以及早發現問題。