uvwt/agentdock

技能創作

用於創建或維護 AgentDock 第一方 Skill。Skill 的本體是模型可讀取的說明文件；工具負責真實檢查、編輯、命令執行、打包、安裝和驗證。

目標 Skill 應由兩部分構成：

可移植核心契約
+
可選的宿主適配說明

移除 AgentDock 專屬適配說明後，Skill 的業務流程、包內引用、環境變數契約和輔助腳本仍應完整可用。

何時使用

使用本 Skill 處理：

• 創建新的第一方 Skill；
• 修改、重構或升級現有 Skill；
• 調整觸發描述、正文流程、引用資料或輔助腳本；
• 補充測試、範例、安全約束和可移植性檢查；
• 遞增版本並完成原始碼側與當前啟動版本驗證。

不要使用本 Skill 處理第三方 Skill 的正式安全審查、真實憑證配置或已安裝版本回滾。這些屬於 skill-installation。

核心原則

1. 先定義模型何時應該選擇該 Skill，再寫正文。
2. Skill 只描述方法、邊界和工具選擇，不承擔統一執行職責。
3. Skill 核心契約必須與宿主無關；包內文件使用相對路徑，環境由運行宿主注入。
4. 簡單 Skill 優先只有一份 SKILL.md；只有確有必要時才增加引用、腳本或測試。
5. 修改正文、引用、腳本或行為後必須遞增語義化版本。
6. 同名同版本內容必須保持不可變。
7. 環境值、設備狀態和運行資料不得進入 Skill 包。
8. 所有驗證都要落到當前已安裝並啟動的版本，不能只看原始碼目錄。
9. 第一方 Skill 必須通過本 Skill 的 lint，不能只通過包安裝校驗。

完整規範見包內 references/skill-package-spec.md。

標準流程

1. 理解需求和觸發條件

先明確：

• 用戶真正要解決的問題；
• 模型在什麼請求下應選擇該 Skill；
• 哪些相鄰任務不屬於該 Skill；
• 需要呼叫哪些真實工具；
• 是否需要輔助腳本、引用資料或測試；
• 是否涉及網路、寫入、刪除、憑證或高風險動作。

不要用「管理某能力全生命週期」這類寬泛描述。description 必須讓模型能穩定判斷何時選中它。

2. 確定職責邊界

正文至少說明：

• 適用場景和不適用場景；
• 讀取或修改的對象；
• 預設唯讀行為；
• 寫操作和破壞性操作的確認規則；
• 失敗時需要返回的證據。

一個 Skill 應圍繞一個穩定能力邊界組織。需求已經跨越獨立職責時，應拆成多個 Skill。

3. 創建原始碼目錄

普通第一方和社群 Skill 預設放在獨立的 agentdock-skills 倉庫：

skills/<skill-name>/

只有隨 AgentDock 安裝包自舉、與運行時版本強綁定的核心 Skill 才放在 AgentDock 主倉庫：

core-skills/<skill-name>/

按需選擇結構：

skills/<skill-name>/
└── SKILL.md

skills/<skill-name>/
├── SKILL.md
├── references/
├── scripts/
└── tests/

skills/<skill-name>/
├── SKILL.md
├── run.py
└── tests/

不要為了形式創建空目錄，也不要把普通整合重新放回 AgentDock 主倉庫。

4. 編寫 Frontmatter

當前 AgentDock 正式解析：

---
name: example-skill
description: 清楚說明何時使用、解決什麼問題
version: 1.0.0
---

要求：

• name 使用穩定、簡短、全小寫的連字號名稱；
• description 同時覆蓋觸發場景和能力邊界；
• version 使用語義化版本；
• Frontmatter 後必須有非空 Markdown 正文；
• 不增加當前解析器未支援的環境變數或執行欄位。

5. 編寫可移植核心

目標 Skill 的正文和腳本預設只假設：

• 當前工作目錄是 Skill 包根目錄；
• 包內資源可透過相對路徑存取；
• 環境變數來自當前行程環境；
• 運行宿主負責選擇工具、切換目錄和注入環境；
• 不依賴 AgentDock 的安裝目錄、狀態目錄或專屬變數。

有根目錄腳本時，通用執行範例應寫成：

printf '%s' '{"skill_action":"status"}' | python3 run.py

不得把以下內容作為核心運行前提：

• ~/.agentdock/skill-store/installed/...；
• 固定安裝版本號；
• AGENTDOCK_DIR、AGENTDOCK_HOME 或 AGENTDOCK_SKILL_DIR 用於定位包內腳本或私有資料；
• skill_env、exec_command 或 skill://；
• 固定用戶絕對路徑；
• 主動讀取或 source AgentDock 私有環境檔案。

AgentDock 工具呼叫可以出現在單獨的「AgentDock 適配/驗證」說明中，但刪除該部分後，Skill 仍必須可用。

6. 宣告環境變數

每個需要配置的目標 Skill 都必須在正文中明確宣告變數：

## 環境變數

| 變數 | 類型 | 必填 | 說明 |
|---|---:|---:|---|
| EXAMPLE_BASE_URL | config | 是 | 服務位址 |
| EXAMPLE_API_KEY | secret | 是 | API Key |

類型至少區分 config 和 secret，並說明缺失變數時哪些能力不可用。

目標 Skill 只宣告變數名稱和用途，不宣告 AgentDock 私有儲存路徑，不儲存真實值。輔助腳本只從當前行程環境讀取變數。

在 AgentDock 本機驗證時，環境值由 skill_package env_set/env_unset/env_list 管理，並由 exec_command 的 skill 上下文注入本次子行程。環境不會寫入 AgentDock 主行程或系統環境。

7. 編寫引用資料

適合放入 references/ 的內容包括：

• 穩定協定說明；
• 較長檢查清單；
• API 欄位或錯誤碼表；
• 不需要每次完整載入的背景資料。

目標 SKILL.md 使用包內相對路徑，例如：

references/api.md

不要把 skill://<name>/... 寫成核心引用契約，也不要依賴另一個 Skill 的安裝目錄。AgentDock 在驗證當前啟動包時可透過 read_file skill://<name>/... 讀取資源。

8. 編寫輔助腳本

輔助腳本只是可選資源，不是 Skill 本體。需要腳本時：

• 輸入使用 stdin JSON 物件；
• 頂層動作欄位統一使用 skill_action；
• 金鑰只從當前行程環境讀取；
• 不透過命令列參數傳遞秘密；
• 輸出結構化 JSON；
• 錯誤返回穩定 code 和可讀 message；
• 狀態檢查優先唯讀；
• 寫操作遵守用戶確認規則；
• 日誌和錯誤不得回顯秘密；
• 包內文件使用相對路徑或基於腳本自身目錄定位。

推薦輸入：

{
  "skill_action": "status"
}

通用執行在 Skill 包根目錄運行：

python3 run.py

AgentDock 驗證時使用 exec_command 的 skill: "<skill-name>" 綁定當前啟動目錄與獨立環境，不手工解析版本目錄。

9. 運行可移植性 lint

本 Skill 的 run.py 提供：

• status：報告 lint 版本和規則數量；
• lint：檢查目標 Skill 的可移植核心和宿主綁定問題。

輸入範例：

{
  "skill_action": "lint",
  "source": "/path/to/agentdock-skills/skills/example-skill"
}

結果包含：

• portable；
• error_count；
• warning_count；
• 每條 issue 的 code、severity、檔案、行號、說明和修復建議。

硬編碼已安裝版本目錄、依賴 AgentDock 專屬目錄變數、主動讀取 AgentDock 環境檔案和固定用戶絕對路徑屬於 error。AgentDock 專屬工具或 URI 出現在目標 SKILL.md 中屬於 warning，需要確認它們只存在於可選適配說明。

對已安裝目錄運行 lint 時，會忽略包根目錄下由 AgentDock 安裝器生成的 .agentdock-install.json。該檔案屬於宿主安裝回執，不是 Skill 包內容；同名檔案出現在包內其他目錄時仍會正常掃描。

在 AgentDock 中，安裝新版 skill-authoring 後可這樣運行：

exec_command
  skill: skill-authoring
  cmd: python3 run.py
  stdin: {"skill_action":"lint","source":"/path/to/source"}

創建或修改第一方 Skill 時，portable 必須為 true；warning 必須逐項修復或說明為什麼屬於可選宿主適配。

10. 編寫測試

測試覆蓋真實風險，至少考慮：

• Frontmatter 和正文可解析；
• 輸入不是 JSON 物件時明確失敗；
• 未知 skill_action 明確失敗；
• 缺失環境變數時只報告變數名，不洩漏值；
• 唯讀狀態檢查不產生寫入；
• 破壞性動作缺少確認時拒絕；
• 日誌和錯誤不包含秘密；
• 平台或依賴缺失時返回可診斷資訊；
• 包從根目錄使用相對命令運行；
• 腳本不依賴 AgentDock 私有目錄。

11. 安全和質量檢查

提交前檢查：

• 包內沒有真實密碼、Token、Cookie、認證快取或會話檔案；
• 沒有 .env、快取、資料庫、螢幕截圖、下載檔案和運行結果；
• 沒有 __pycache__、*.pyc、node_modules 或編譯產物；
• 沒有固定用戶絕對路徑、符號連結或路徑逃逸；
• 沒有舊式統一執行協定、舊式環境工具範例或舊清單；
• 網路目標、檔案寫入、刪除、上傳和權限變化均被明確說明；
• 依賴安裝不會被隱藏執行。

明確禁止生成或恢復：

• agentdock.yaml；
• skill_run；
• skill_env_manage；
• AGENTDOCK_OPERATION；
• PLUGIN_* 舊協定；
• 舊式 operation 或 entrypoint 清單；
• 統一 Skill 執行器或舊 Skill Runtime。

設備私有狀態和 AgentDock 環境值只屬於宿主，不進入包。

12. 遞增版本

• 只修正文中錯字且不影響行為判斷，可遞增修訂版本；
• 新增相容能力、變數、動作或引用，遞增次版本；
• 改變職責邊界、移除既有能力或引入不相容流程，遞增主版本。

安裝前比較當前已安裝版本和新原始碼。不得用相同版本覆蓋不同內容。

13. 驗證和本機安裝

至少完成：

1. 檢查目錄和 Frontmatter；
2. 檢查版本正確遞增；
3. 檢查禁止檔案、符號連結和真實 secret；
4. 對輔助腳本執行語法檢查和自帶測試；
5. 運行 skill-authoring lint，確認 portable=true 並審查 warning；
6. 使用 skill_package validate 校驗包級合法性；
7. 使用 skill_package install 安裝並啟動；
8. 透過 agentdock_context 驗證名稱和描述進入輕量索引；
9. 透過 read_file skill://<name>/SKILL.md 驗證當前啟動正文；
10. 有引用時讀取至少一份引用；
11. 有輔助腳本時，用 exec_command skill=<name> 對當前啟動版本運行唯讀 status；
12. 運行一個代表性低風險動作，無法運行時記錄真實原因。

skill_package validate 負責包能否合法安裝；本 Skill 的 lint 負責第一方創作質量和可移植性，兩者不能互相替代。

環境變數

本 Skill 自身不需要環境變數。它要求被編寫的目標 Skill 宣告業務變數，並由運行宿主注入當前子行程。

完成標準

只有同時滿足以下條件才算完成：

• 描述可穩定觸發且邊界清楚；
• 可移植核心不依賴 AgentDock 私有目錄或工具參數；
• 包內腳本可從 Skill 根目錄使用相對路徑運行；
• skill-authoring lint 返回 portable=true，warning 已逐項處理；
• 安全檢查、測試和 skill_package validate 通過；
• 新版本已安裝並啟動；
• agentdock_context 和 skill:// 讀取的是新版本；
• 當前啟動版本的真實唯讀驗證通過；
• 沒有秘密、設備私有狀態或舊式架構回流。