Что такое навык
Навык — это папка, имя которой совпадает с name навыка. В папке лежит файл SKILL.md и, по желанию, любые другие файлы, на которые ссылаются инструкции: справочные документы, шаблоны или скрипты.
SKILL.md состоит из двух частей. Фронтматтер YAML между строками --- содержит имя и описание. Тело на Markdown после него содержит инструкции.
Как сотрудники используют навыки
Сотрудник работает с навыком в три шага.
- Выбор. На каждом ходе сотрудник видит список доступных ему навыков: имя каждого навыка, его описание и до трёх его триггеров. Именно описание сотрудник читает, чтобы принять решение, поэтому пишите в нём, что делает навык и когда его использовать.
- Загрузка. Сотрудник вызывает инструмент
use_skillс именем навыка. Инструмент возвращает инструкции, путь к папке навыка и имена его файлов. Это единственный способ, которым сотрудник читает навык. - Работа. Сотрудник следует инструкциям. Он читает вспомогательные файлы с помощью
read_skill_fileи запускает встроенные скрипты с помощьюexecute.
Триггеры никогда не загружают навык сами по себе. Выбор всегда делает сотрудник. Когда список становится длинным, сотрудник может искать в нём с помощью find_skills.
Напишите свой первый навык
Создайте папку с именем навыка и одним файлом внутри.
meeting-notes/ └── SKILL.md
--- name: meeting-notes description: Turn a meeting transcript into decisions, action items with owners, and open questions. Use when someone shares meeting notes or a transcript. --- # Meeting notes 1. List the decisions that were made. 2. List action items as "owner — task — due date". 3. List open questions that need a follow-up. Keep each list short. If the transcript names no owner for an item, write "unassigned".
Положите папку в каталог пользовательских навыков бота (см. Где хранятся навыки). Nebo замечает новую папку примерно за секунду, и навыком может пользоваться любой сотрудник на этом боте.
Сотрудник может и сам написать для вас навык. Попросите его сохранить навык, и он вызовет save_skill, который запишет папку в тот же каталог пользовательских навыков.
Правила, которые проверяет загрузчик
Навык, нарушающий одно из этих правил, не загружается. Nebo записывает предупреждение в журнал и пропускает его.
| Правило | Подробности |
|---|---|
Файл начинается с --- | Фронтматтер должен идти в файле первым. Файл должен быть в UTF-8. |
name обязательно | Только строчные буквы, цифры и дефисы; без дефиса в начале или в конце; без двойного дефиса; не более 64 байт. |
description обязательно | Не более 1 024 байт. |
| Поля имеют правильный тип | Поле с неверным типом YAML делает недействительным весь файл. Берите версии в кавычки, например "1.0.0". |
platform совпадает | Если поле есть, навык загружается только в перечисленных операционных системах. |
Ключи фронтматтера, которые Nebo не распознаёт, игнорируются. Размер тела не ограничен, но чем короче инструкции, тем больше места остаётся для работы. Длинные материалы выносите в файлы, которые сотрудник читает, когда они ему нужны.
Добавьте файлы
Любой файл в папке, кроме SKILL.md и файлов, начинающихся с точки, доступен сотруднику. Имена папок выбираете вы; Nebo не придаёт особого значения references/ или assets/. Файлы в scripts/ или bin/ можно запускать.
invoice-check/
├── SKILL.md # required
├── references/
│ └── policy.md # read with read_skill_file
└── scripts/
└── totals.py # run with execute Ссылайтесь на файлы по их пути внутри папки, например references/policy.md. Сотрудник читает их с помощью read_skill_file, который отклоняет любой путь, выходящий за пределы папки. Скрипты запускаются инструментом execute в песочнице. Среды выполнения, переменные окружения, секреты и доступ к сети описаны в справочнике по SKILL.md.
Где хранятся навыки
Бот собирает навыки из нескольких мест. Когда два источника дают навык с одним и тем же именем, побеждает источник, который стоит в этом списке позже.
| Источник | Расположение | Кто может использовать |
|---|---|---|
| Встроенные | Встроены в Nebo при сборке | Все сотрудники |
| Маркетплейс | <data>/nebo/skills/<slug>/<version>/ | Все сотрудники |
| Плагин | Папка skills/ установленного плагина | Все сотрудники |
| Пользовательские | <data>/user/skills/<name>/ | Все сотрудники |
| Пакет сотрудника | skills/ внутри установленного пакета сотрудника | Только этот сотрудник |
| Изученные | <data>/learned/skills/<employee>/<name>/ | Только этот сотрудник |
<data> — это ~/Library/Application Support/Nebo в macOS, %APPDATA%\Nebo в Windows и ~/.local/share/nebo в Linux. Переменная окружения NEBO_HOME его переопределяет. Когда у сотрудника есть собственный навык и общий навык с тем же именем, побеждает собственный.
Nebo следит за этими папками и перезагружает изменённый навык через секунду. Чтобы выключить навык, не удаляя его, переименуйте его файл в SKILL.md.disabled.
Навыки описывают работу, а не инструменты. Стройте навык вокруг обязанности, например сверки чеков, и позвольте сотруднику использовать любое подключение, которое предоставил владелец. Когда навыку действительно нужен плагин, объявите его в поле plugins.
Далее
- Справочник по SKILL.md: все поля, инструменты и переменные.
- Примеры: готовые навыки для копирования.
- Публикация: разместите навык в маркетплейсе.