Формат файла
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 | args, переданные в use_skill. Если в теле нет $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 символов, сначала сокращаются общие навыки; собственные навыки сотрудника сохраняют полные записи. |
Ограничения для файлов, которые вы публикуете в маркетплейсе, приведены на странице Публикация.