NeboAI
NeboAI
開始使用

SKILL.md 參考

本頁列出 Nebo 會讀取的技能各部分:前置資料欄位、它會展開的變數、員工用來操作技能的工具,以及指令碼的執行環境。

檔案格式

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 是必填。類型錯誤的欄位會讓整個檔案失效,技能也就不會載入。此處未列出的鍵會被忽略。

欄位類型預設值意義
namestring必填識別碼。[a-z0-9-],開頭、結尾不可有連字號,也不可有連續兩個連字號,最多 64 位元組。須與資料夾名稱相同。
descriptionstring必填技能的作用與使用時機。最多 1,024 位元組。顯示在員工的技能清單中,並由 find_skills 評分。
versionstring"1.0.0"語意化版本。供其他技能的 requires 範圍檢查。請加上引號。
triggers字串清單[]描述技能適用時機的字詞與片語。技能清單中最多顯示三個;全部都會計入 find_skills。它們絕不會自行載入技能。
platform字串清單全部macos、linux、windows。技能只會在相符的系統上載入。
capabilities字串清單[]network 和 storage 會放寬指令碼沙箱。請參閱「指令碼沙箱」。
metadatamap{}包含 secrets 與 allowed_domains。請見下文。
requires{name, version} 的清單[]此技能所依據的其他技能。name 是技能簡稱;version 是 semver 範圍,預設為 "*"。
plugins{name, version, optional} 的清單[]此技能使用的外掛。version 預設為 "*",optional 預設為 false。
dependencies字串清單[]必須存在的技能簡稱。
priorityinteger0決定技能在管理清單中的排序。不影響員工選擇哪個技能。
authorstring""儲存以供顯示。
licensestring""儲存以供顯示。
compatibilitystring""自由文字備註,最多 500 位元組。
tags字串清單[]儲存以供顯示。
allowed-toolsstring""以空格分隔的字串。會儲存,但不強制執行。

當 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_skillname, args載入技能。回傳展開後的本文、資料夾路徑,以及前 20 個檔案名稱。也會重新啟用已停用的技能。
find_skillsquery依名稱、觸發詞和說明的相符程度排序,回傳最多 10 個技能。
read_skill_filename, path讀取技能資料夾中的檔案。未提供 path 時,列出檔案及其大小。
save_skillname, content將完整的 SKILL.md 寫入使用者技能資料夾。市集技能無法被覆寫。
delete_skillname刪除使用者技能。
install_skillcode以 SKIL- 安裝代碼安裝市集技能。
configure_skillname, key, value設定機密。未提供 key 時,顯示技能需要哪些項目。
rate_skillname, rating, review為市集技能評分,從 1 到 5。
read_skill_reviewsname讀取市集技能的評論。
executeskill, script, args, timeout從技能資料夾執行指令碼。請參閱「指令碼沙箱」。

指令碼沙箱

execute 工具會從技能資料夾執行一個指令碼。它依檔案決定執行環境。

指令碼執行環境
.pyPython,有 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 個字元時,會先縮短共用技能;員工自己的技能則保留完整項目。

發布到市集的檔案限制,請見發布頁面。