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_ARGSargs 对象的 JSON 形式。
每个密钥的 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 个字符时,先缩短共享技能;员工自己的技能保留完整条目。

发布到市场的文件有哪些限制,请参见发布页面。