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}Значение объявленного секрета.
$ARGUMENTSargs, переданные в use_skill. Если в теле нет $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Объект 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 символов, сначала сокращаются общие навыки; собственные навыки сотрудника сохраняют полные записи.

Ограничения для файлов, которые вы публикуете в маркетплейсе, приведены на странице Публикация.