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Аргументи args, передані в 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 символів, спершу скорочуються спільні навички; власні навички співробітника зберігають свої повні записи.

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