文件格式
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 | args 对象的 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 个字符时,先缩短共享技能;员工自己的技能保留完整条目。 |
发布到市场的文件有哪些限制,请参见发布页面。