檔案格式
SKILL.md 是 UTF-8 文字檔。開頭是一行三個連字號,接著是 YAML 前置資料,再以一行三個連字號結束。其後的所有內容都是本文:員工載入技能時收到的 Markdown 指示。Nebo 依名稱尋找這個檔案,不區分大小寫。
---
name: expense-review
description: Check submitted expenses against the company policy and flag anything that needs a receipt or an approval. Use when someone asks to review expenses or a reimbursement request.
version: "1.2.0"
author: Example Co
license: MIT
tags: [finance, expenses]
triggers: [reimbursement, expense report]
platform: [macos, linux, windows]
capabilities: [network]
metadata:
allowed_domains: [api.example.com]
secrets:
- key: EXAMPLE_API_KEY
label: Example API key
hint: Create one at https://example.com/settings/keys
required: true
requires:
- name: receipt-capture
version: ">=1.0.0"
plugins:
- name: example-ledger
version: ">=2.0.0"
optional: true
---
# Expense review
Follow the policy in references/policy.md ... 前置資料欄位
只有 name 和 description 是必填。類型錯誤的欄位會讓整個檔案失效,技能也就不會載入。此處未列出的鍵會被忽略。
| 欄位 | 類型 | 預設值 | 意義 |
|---|---|---|---|
name | string | 必填 | 識別碼。[a-z0-9-],開頭、結尾不可有連字號,也不可有連續兩個連字號,最多 64 位元組。須與資料夾名稱相同。 |
description | string | 必填 | 技能的作用與使用時機。最多 1,024 位元組。顯示在員工的技能清單中,並由 find_skills 評分。 |
version | string | "1.0.0" | 語意化版本。供其他技能的 requires 範圍檢查。請加上引號。 |
triggers | 字串清單 | [] | 描述技能適用時機的字詞與片語。技能清單中最多顯示三個;全部都會計入 find_skills。它們絕不會自行載入技能。 |
platform | 字串清單 | 全部 | macos、linux、windows。技能只會在相符的系統上載入。 |
capabilities | 字串清單 | [] | network 和 storage 會放寬指令碼沙箱。請參閱「指令碼沙箱」。 |
metadata | map | {} | 包含 secrets 與 allowed_domains。請見下文。 |
requires | {name, version} 的清單 | [] | 此技能所依據的其他技能。name 是技能簡稱;version 是 semver 範圍,預設為 "*"。 |
plugins | {name, version, optional} 的清單 | [] | 此技能使用的外掛。version 預設為 "*",optional 預設為 false。 |
dependencies | 字串清單 | [] | 必須存在的技能簡稱。 |
priority | integer | 0 | 決定技能在管理清單中的排序。不影響員工選擇哪個技能。 |
author | string | "" | 儲存以供顯示。 |
license | string | "" | 儲存以供顯示。 |
compatibility | string | "" | 自由文字備註,最多 500 位元組。 |
tags | 字串清單 | [] | 儲存以供顯示。 |
allowed-tools | string | "" | 以空格分隔的字串。會儲存,但不強制執行。 |
當 requires 或 dependencies 中指名的技能不存在或超出範圍,或必要的外掛尚未安裝時,技能仍會載入,但會標示為功能受限。擁有者會看到缺少了什麼。
機密
在 metadata.secrets 下宣告技能指令碼需要的憑證。由擁有者提供值,Nebo 會為該技能加密儲存。
metadata:
secrets:
- key: EXAMPLE_API_KEY
label: Example API key
hint: Create one at https://example.com/settings/keys
required: true | 鍵 | 意義 |
|---|---|
key | 指令碼接收的環境變數名稱。必填。 |
label | 向擁有者顯示的名稱。 |
hint | 取得此值的地方。 |
required | 設為 true 時,在設定此值之前,execute 會拒絕執行技能的指令碼。預設為 false。 |
員工會用 configure_skill 設定值。你可以在內文中以 ${secret.KEY} 參照密鑰,不過指令碼應該改讀環境變數。
範本變數
員工載入技能時,Nebo 會取代本文中的這些變數。其他檔案中的變數不會被取代;指令碼改為讀取環境變數。
| 變數 | 值 |
|---|---|
${NEBO_SKILL_DIR} | 技能資料夾的絕對路徑。 |
${NEBO_DATA_DIR} | 此技能可寫入的資料夾:<data>/appdata/skills/<name>。首次使用時建立。 |
${NEBO_USER_NAME} | 擁有者的名稱。 |
${NEBO_OS} | 作業系統。 |
${NEBO_ARCH} | 處理器架構。 |
${plugin.SLUG_BIN} | 已宣告外掛的二進位檔路徑。slug 會轉成大寫,連字號換成底線:example-ledger 會變成 ${plugin.EXAMPLE_LEDGER_BIN}。 |
${secret.KEY} | 已宣告機密的值。 |
$ARGUMENTS | 傳給 use_skill 的 args。當本文中沒有 $ARGUMENTS 時,引數會附加在本文之後。 |
技能工具
員工透過這些工具使用技能。use_skill 一律可用;其他工具會在員工需要時載入。
| 工具 | 參數 | 作用 |
|---|---|---|
use_skill | name, args | 載入技能。回傳展開後的本文、資料夾路徑,以及前 20 個檔案名稱。也會重新啟用已停用的技能。 |
find_skills | query | 依名稱、觸發詞和說明的相符程度排序,回傳最多 10 個技能。 |
read_skill_file | name, path | 讀取技能資料夾中的檔案。未提供 path 時,列出檔案及其大小。 |
save_skill | name, content | 將完整的 SKILL.md 寫入使用者技能資料夾。市集技能無法被覆寫。 |
delete_skill | name | 刪除使用者技能。 |
install_skill | code | 以 SKIL- 安裝代碼安裝市集技能。 |
configure_skill | name, key, value | 設定機密。未提供 key 時,顯示技能需要哪些項目。 |
rate_skill | name, rating, review | 為市集技能評分,從 1 到 5。 |
read_skill_reviews | name | 讀取市集技能的評論。 |
execute | skill, script, args, timeout | 從技能資料夾執行指令碼。請參閱「指令碼沙箱」。 |
指令碼沙箱
execute 工具會從技能資料夾執行一個指令碼。它依檔案決定執行環境。
| 指令碼 | 執行環境 |
|---|---|
.py | Python,有 Nebo 隨附的 uv 時透過它執行,否則使用 python3。 |
.ts, .js | 有 Nebo 隨附的 Bun 時使用它,否則使用 node。 |
bin/<file> 或 binary | 直接執行。 |
.sh | 不支援。 |
每次執行都從空白環境開始,並帶有下列變數:
| 變數 | 值 |
|---|---|
SKILL_ARGS | 以 JSON 表示的 args 物件。 |
每個機密的 key | 解密後的機密值。 |
<PLUGIN>_BIN | 每個已宣告外掛的二進位檔路徑。外掛資料夾也會加入 PATH。 |
import json, os
args = json.loads(os.environ.get("SKILL_ARGS", "{}"))
api_key = os.environ["EXAMPLE_API_KEY"]
print(json.dumps({"checked": len(args.get("items", []))})) 指令碼在技能資料夾的暫存副本中執行,預設逾時為 30 秒。在 macOS 和 Linux 上,它會在作業系統沙箱中執行:
- 它無法讀取憑證儲存區、瀏覽器與鑰匙圈資料,也無法讀取 Nebo 自身的設定與資料庫。
- 它只能寫入自己的工作資料夾和
/tmp/nebo。storage能力會再加上 Nebo 的資料資料夾。 - 它沒有網路存取權。
network能力允許存取套件登錄庫和metadata.allowed_domains中列出的網域。
檔案與限制
| 項目 | 規則 |
|---|---|
| 資源 | 除了 SKILL.md、manifest.json、signatures.json 和點檔案以外的所有檔案。 |
| 執行檔 | scripts/ 或 bin/ 下的檔案,以及根目錄中名為 binary 的檔案。 |
| 路徑 | 相對於技能資料夾。含有 .. 或會跳出資料夾的路徑會被拒絕。 |
| 已停用的技能 | 含有 SKILL.md.disabled 而非 SKILL.md 的資料夾。 |
| 技能清單 | 每個項目最多 250 個字元,超過的部分會被截斷。當整份清單超過 8,000 個字元時,會先縮短共用技能;員工自己的技能則保留完整項目。 |
發布到市集的檔案限制,請見發布頁面。