Формат файлу
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 символів, спершу скорочуються спільні навички; власні навички співробітника зберігають свої повні записи. |
Обмеження для файлів, які ви публікуєте в маркетплейсі, наведено на сторінці Публікація.