Версія 1.0.0-alpha.1найновіша
Розділ 2.20
Навички (Skills)
Як написати, протестувати й опублікувати навичку Skills Engine, де вона з'являється після публікації та чим відрізняються навички з маніфесту в плагіні. Містить практичний приклад зведення про розподіл причалів для Harrow Port Authority.
Цю сторінку перекладено за допомогою ШІ з англійського оригіналу. Якщо щось незрозуміло, орієнтуйтеся на англійську версію сторінки. Читати цю сторінку англійською

Минулого місяця Tomás Reilly, інженер платформи в Harrow Port Authority, запитав мене, чому його планувальники причалів щоразу отримували різну відповідь, коли питали в асистента: «хто на якому причалі завтра і що змінилося?». Причина полягала в тому, що ніхто не пояснив асистенту, як має виглядати правильна відповідь. Навичка Skills Engine вирішила це за пів дня: тепер планувальники щоразу отримують однакове зведення з трьох частин — спочатку таблицю причалів, під нею зміни з моменту останнього плану, а в кінці — конфлікти. У цьому розділі ми детально розберемо цю навичку від початку до кінця, а потім розглянемо інший вид навичок — ті, що описуються в маніфесті плагіна.
Два види навичок
У Nexus слово «навичка» (skill) вживається для позначення двох різних речей, і створюються вони по-різному.
| Навичка Skills Engine | Навичка маніфесту | |
|---|---|---|
| Що це таке | Пакет SKILL.md у бібліотеці навичок |
Типізований запис у масиві skills[] плагіна |
| Хто її створює | Будь-хто з відповідними правами — у конструкторі або у власному редакторі | Розробник — усередині плагіна |
| Що вона містить | Інструкції, інструменти, які вона може викликати, необов'язкові файли та скрипти | Схему вхідних і вихідних даних, рівень (tier) та поля, необхідні для цього рівня |
| Як вона потрапляє на платформу | Проходить валідацію, завантажується та публікується в Skills Engine | Компілюється з маніфесту та синхронізується з реєстром навичок |
| Що її запускає | Асистент, агенти, робочі процеси, кнопки ШІ (штучного інтелекту), Claude Code | Диспетчер UNO (рушія робочих процесів) |
| Типове використання | «Формувати зведення плану причалів щоразу однаково» | «Запустити наш пропагатор орбіти на цьому проході» |
У решті розділу ці поняття чітко розмежовуються. Якщо в абзаці вжито просто слово «навичка» без уточнень, ідеться про навичку Skills Engine.
Частина 1: навички Skills Engine
Що таке навичка
Навичка — це папка. Її файл SKILL.md визначає, для чого призначена навичка і як виконувати роботу; поруч із ним розміщуються всі необхідні для роботи файли та скрипти, які вона запускає. Рушій завантажує навичку в три рівні: назву та опис — завжди, інструкції — коли завдання вимагає цієї навички, а файли — лише тоді, коли вони потрібні на певному кроці. Саме тому інсталяція може містити двісті навичок і майже не витрачати на них ресурсів, доки одна з них не буде використана.
skills/<slug>/
├── SKILL.md # required: YAML frontmatter, then the instructions
├── skill.yaml # optional: engine metadata (triggers, aliases, tags, capabilities)
└── scripts/ # optional: bundled with the skill as components
Назва каталогу має збігатися зі слагом (slug) навички. Невідповідність викличе попередження під час валідації, і це варто виправити, оскільки саме за слагом бібліотека зіставляє завантажений пакет із наявною навичкою.
Метадані (frontmatter) у SKILL.md
Метадані (frontmatter) — це блок YAML між двома рядками --- на початку файлу. Формат вимагає наявності трьох полів. Сама валідація блокує процес лише в кількох випадках: якщо відсутня назва або опис, а також якщо слаг або тип завдання вже зайняті. Про все інше вона повідомляє як про попередження.
| Поле | Тип | Обов'язкове | Що містить |
|---|---|---|---|
name |
string | так | Унікальний ідентифікатор у форматі kebab-case |
description |
string | так | Опис того, що робить навичка, щонайбільше 500 символів. Його читають бібліотека та механізм зіставлення (matcher), тому пишіть його для читача, який вирішує, чи це саме та навичка, яка потрібна |
allowed-tools |
string або list | так | Інструменти, які може викликати навичка. Цей параметр може лише звузити список дозволених інструментів (allow-list) того, хто її запускає |
triggers |
list | ні | Слеш-команди, які безпосередньо викликають навичку |
capabilities |
list | ні | Структуровані можливості (capabilities), кожна з яких має name, description та необов'язково input_schema, output_schema і examples |
version |
string | ні | Семантична версія; 1.0.0, якщо не вказано |
visibility |
string | ні | private, team або public |
status |
string | ні | draft, testing або published |
Намагайтеся вкласти інструкції приблизно в 5,000 токенів. Формулюйте конкретно та наводьте приклади. Кожна навичка має добре виконувати одне завдання; якщо ви ловите себе на тому, що пишете «а також», імовірно, вам потрібні дві окремі навички.
skill.yaml
Файл skill.yaml містить дані, необхідні рушію для виявлення (discovery) та роботи бібліотеки, завдяки чому SKILL.md залишається зручним для читання. Поля, які зчитує рушій, включають name, display_name, description, version, status, visibility, triggers, aliases, category, tags, allowed_tools та capabilities. Можливість (capability) може містити query_patterns — формулювання запитів, які механізм зіставлення має спрямовувати до неї. Є також підказки для планування власного бюджету рушія: complexity, estimated_tokens та required_services.
scripts/
Усе, що знаходиться в каталозі scripts/, додається до пакета навички як компонент без жодних змін. Скрипт виконується, але ніколи не зчитується в контекст моделі, і працює він в ізольованому середовищі (пісочниці). Використовуйте скрипти, коли крок вимагає арифметичних обчислень або парсингу, які модель не повинна виконувати «в умі».
Видимість і статус
Видимість визначає, хто може знайти навичку: private — лише ви, team — ваша команда, а public — усі співробітники організації, яку обслуговує бібліотека. У консолі цей самий вибір відображається як «Лише я», назва команди, наприклад «Митний відділ», або вся організація; крім того, навичку можна додати до галузевого пакета (domain pack) після проходження процедури перевірки цього пакета.
Статус показує, на якому етапі життєвого циклу перебуває навичка.
| Статус | Значення |
|---|---|
draft |
У розробці; недоступна для пошуку |
testing |
Проходить валідацію, з обмеженим доступом |
published |
Доступна для загального використання |
deprecated |
Замінена новішою; готується до виведення з експлуатації |
Після публікації версія ніколи не змінюється. У консолі «live», «canary» та «shadow» — це мітки на версіях, і повернення до попередньої версії просто переміщує мітку. Запуски, які вже виконуються, завершують роботу на тій версії, з якою вони стартували.
SKILL.md, супутні файли з інформацією про те, коли кожен із них завантажується, та інструменти, які навичка може викликати. Навичці, призначеній для перевірки, не пропонуються інструменти із записом даних, а сама навичка може лише звузити список дозволених інструментів ініціатора запуску.Від папки до робочої навички
П'ять скриптів npm у репозиторії Skills Engine переносять навичку з вашого редактора до бібліотеки та підтверджують її успішне доставлення.
| Команда | Що він робить |
|---|---|
npm run skill:validate skills/<slug> |
Перевіряє пакет лінтером. Для публікації потрібно нуль помилок |
npm run skill:upload skills/<slug> |
Валідує та публікує за один крок; ідемпотентна операція |
npm run skill:upload skills/<slug> --dry-run |
Валідує та виводить план дій без запису жодних даних |
npm run skill:publish -- --dry-run skills/<slug> |
Низькорівнева публікація, що лежить в основі завантаження, той самий конвеєр |
npm run skill:reconcile |
Порівнює навички у вашому репозиторії з вмістом бібліотеки та реєстру навичок |
npm run skill:live:verify |
Наскрізно перевіряє опубліковану навичку на працюючій інсталяції |
Під час публікації створюються два записи, і обидва є важливими. Перший — це сама навичка з вмістом її SKILL.md, можливостями, компонентами та записом про якість; саме його читають бібліотека, механізми виявлення та зіставлення. Другий — це запис у реєстрі, за яким рушій робочих процесів визначає куди спрямувати виклик (dispatch). Навичка, яка потрапила лише до реєстру, працюватиме, але залишатиметься невидимою в бібліотеці, доки ви її не завантажите.
Публікація є ідемпотентною. Якщо навичка не змінилася, жодних дій не виконується (no-op), а наявна навичка знаходиться за її слагом і оновлюється на місці, без повторного створення. Якщо завантажити ті самі байти, що й у вже опублікованій версії, ви отримаєте назад ту саму версію зі статусом CONTENT_HASH_ALREADY_PUBLISHED, а не дублікат.
Команда skill:reconcile звіряє навички вашого репозиторію з бібліотекою, реєстром та інвентарем рушія робочих процесів і повідомляє про все, що існує в одному місці, але відсутнє в іншому. Команда skill:live:verify виконує глибшу перевірку на працюючій інсталяції: обидва записи існують і посилаються один на одного з однаковим хешем вмісту, пробний виклик (dry-run dispatch) типу завдання навички приймається, навичка відображається у списку бібліотеки та в детальному перегляді, її можна викликати, а журнал аудиту пов'язує публікацію, виклик і виконання за слагом та ідентифікатором запиту.
Із робочої станції завантаження звертається до сервісу знань інсталяції, nexus-graphrag, через перенаправлення портів (port-forward) і вимагає наявності сервісного ключа Skills Engine у змінних середовища. Завантажте ключ без виведення його на екран:
kubectl -n nexus port-forward svc/nexus-graphrag 8090:8090
read -rs GRAPHRAG_SKILLS_ENGINE_SERVICE_KEY
export GRAPHRAG_SKILLS_ENGINE_SERVICE_KEY
GRAPHRAG_URL=http://localhost:8090 npm run skill:upload skills/berth-allocation-summaryУсередині кластера, у завданні конвеєра (pipeline job), адреса за замовчуванням визначається автоматично, тому GRAPHRAG_URL не потрібен. Отримайте ключ через стандартний процес керування секретами вашої організації. Він ніколи не повинен потрапляти в репозиторій, історію командної оболонки чи вивід команд.
Тестування, затвердження та запуск у роботу
Навичка потрапляє до бібліотеки як чернетка, і конструктор утримує її в цьому стані, доки не буде успішно пройдено три етапи.
| Перевірка | Що він робить |
|---|---|
| Тестові сценарії | Кожен сценарій має пройти успішно, перш ніж навичку можна буде відправити на затвердження. Видалити тестовий сценарій можна лише із зазначенням причини, яку побачать відповідальні за затвердження. |
| Пробний прогін у тіньовому режимі (shadow) | Навичка запускається на минулих завданнях, де ніхто не бачить відповідей, а її результати порівнюються з рішеннями, які свого часу ухвалила людина. |
| Сліпе рецензування моделлю з іншого сімейства | Вона шукає пропущені перевірки, вигадані джерела та приховані інструкції (ін'єкції), які навичка виконала, хоча не повинна була цього робити. |
Далі — затвердження. Навичка, яка додає інструмент із правом запису, утримується, доки її не затвердять дві особи за допомогою своїх ключів доступу (passkeys), причому автор пропозиції не може бути однією з них (PUBLISH_NEEDS_APPROVAL). Після цього вона запускається в тіньовому режимі (shadow), потім у канарковому (canary) для одного підрозділу за визначеними критеріями пропуску (gates), а вже потім — для всіх. Якщо критерій канаркового випуску не виконується, такий випуск автоматично зупиняється, і всі залишаються на попередній версії; для дострокового розгортання на всіх потрібні обґрунтування та другий затверджувач (CANARY_GATE_NOT_MET).
У редакції Community доступні конструктор, бібліотека, версії та тести, а власник публікує навичку одноосібно після успішного проходження тестів. Канаркові випуски, затвердження двома особами, синхронізація плагінів та об'єднання дублікатів доступні в редакції Enterprise.
Де з'являються навички
Одна й та сама опублікована навичка стає доступною користувачам у п'яти місцях.
- Асистент зіставляє запит із навичкою за її описом, тригерами та шаблонами запитів і виконує інструкції цієї навички.
- Агенти та робочі процеси викликають навички як окремі кроки. Крок робочого процесу вказує назву навички; під час виконання фіксується, яку саме версію було використано.
- Кнопки ШІ на екранах — кожна запускає одну навичку. Адміністратор може відкрити вікно «Про цю кнопку», щоб побачити, яку навичку вона запускає, які дані читає і хто востаннє її змінював, а також може вимкнути кнопку, не зачіпаючи саму навичку.
- Ваше IDE (інтегроване середовище розробки) та Claude Code отримують доступ до бібліотеки через Workbench і тринадцять інструментів MCP (Model Context Protocol), серед яких
list_skills,get_skill,match_prompt,discover_skills,invoke_skill,record_execution,create_skill,import_skill,get_generation_jobтаsync_skills_local. Кожен виклик виконується від імені особи, яка його ініціювала, у межах її списку дозволів. - Сама бібліотека навичок, де користувачі переглядають, запускають навички та пропонують зміни до них, а адміністратори бачать власника кожної навички, її користувачів, історію запусків і витрати.
Незалежно від того, що саме запускає навичку, вона не може розширити повноваження ініціатора запуску: навичка викликає лише інструменти зі списку дозволених для цього ініціатора і читає лише ті дані, які ця особа має право відкривати (SKILL_CANNOT_WIDEN_TOOLS). Запуск без маршруту моделі відхиляється, а не вгадується (SKILLS_ENGINE_BINDING_MISSING); диспетчер обирає маршрут із власних налаштувань моделей організації.
Практичний приклад: зведення розподілу причалів для Harrow
Планувальники Harrow вже мали у своєму списку дозволів два інструменти лише для читання з власного плагіна планування причалів Harrow: berth-plan.read повертає план на вказану дату, а vessel-call.read повертає суднозахід із вікном прибуття та довжиною судна. Більше нічого навичці не потрібно. Вона нічого не записує, тому їй ніколи не потрібні два затверджувачі.
---
name: berth-allocation-summary
description: Summarise tomorrow's berth plan at Harrow for the planning desk. Use when someone asks who is on which berth, what moved since the last plan, or where two calls clash.
allowed-tools: berth-plan.read, vessel-call.read
triggers:
- /berth-summary
capabilities:
- name: summarise_berth_plan
description: The berth table, the changes since the last plan and any clashes, for one date
version: 1.0.0
visibility: team
status: draft
---
# Berth allocation summary
## When to use
A planner asks about the berth plan for a date, or asks what changed.
## Steps
1. Read the plan for the date with berth-plan.read. If no date is given, use tomorrow.
2. For each call on the plan, read it with vessel-call.read.
3. Write the berth table first: berth, vessel, arrival window, length overall.
4. Then list what moved since the previous plan, one line per change, with the reason the plan records.
5. Then list clashes: two calls whose windows overlap on one berth, or a vessel longer than the berth.
6. Cite the plan's version for every line. Never guess a time the plan doesn't give.
## Output
Three headed sections, in this order: Berths, Changes, Clashes. Write "No clashes" when there are none.Файл skill.yaml поруч із нею надає бібліотеці відображувану назву, категорію та формулювання запитів, які механізм зіставлення має спрямовувати сюди:
# skill.yaml, beside SKILL.md
name: berth-allocation-summary
display_name: "Berth allocation summary"
version: "1.0.0"
status: draft
visibility: team
category: operations
tags:
- berths
- planning
triggers:
- "/berth-summary"
allowed_tools:
- berth-plan.read
- vessel-call.read
capabilities:
- name: "summarise_berth_plan"
description: "Berth table, changes since the last plan and clashes, for one date"
query_patterns:
- "who is on which berth tomorrow"
- "what moved on the berth plan"
- "any berth clashes on *"Далі виконуються команди з кореня репозиторію:
npm run skill:validate skills/berth-allocation-summary
npm run skill:upload skills/berth-allocation-summary --dry-run
npm run skill:upload skills/berth-allocation-summaryTomás додав у конструкторі шість тестових сценаріїв: звичайний день; день із запізненням прибуття, через яке змістилися два суднозаходи; день зі справжнім конфліктом; дата, на яку ще немає плану; судно, занадто довге для свого причалу; і запит, який намагався змусити навичку запропонувати новий причал (вона не повинна цього робити; у неї немає інструменту для запису). Під час пробного прогону в тіньовому режимі було відтворено двадцять минулих планів. Коли всі сценарії пройшли успішно, рецензент із відділу планування затвердив навичку, і вона запрацювала для команди планування. Тепер асистент щоразу відповідає на запитання за однаковою структурою, а кнопка ШІ на сторінці плану причалів запускає ту саму навичку.
Частина 2: навички з маніфесту
Навичка маніфесту — це одиниця обчислень, яку публікує плагін. Вона оголошується в секції skills[] маніфесту, валідується за допомогою SDK (набору засобів розробки) під час запуску create-nexus-plugin validate, компілюється у формат реєстру командою compileRegistry і синхронізується з реєстром навичок. Ви ніколи не пишете SQL-запити до реєстру вручну, тому рядок, який викликає платформа, і оголошений вами дескриптор не можуть розійтися.
Кожна навичка маніфесту вимагає полів id, displayName, description, tier, classification, inputSchema та outputSchema. Оголосіть також timeoutMs: це ціле число від 1,000 до 21,600,000 (від однієї секунди до шести годин), а значення поза цим діапазоном відхиляється з помилкою TIMEOUT_OUT_OF_BOUNDS. Поле dataResidency може набувати значень any, eu або us, де any є значенням за замовчуванням.
Поле id записується у форматі lower_snake, а ключем виклику в реєстрі є тип завдання з простором імен <plugin name>.<skill id>, тому два плагіни можуть мати власну навичку summarise без конфліктів. Ось скорочений приклад однієї навички із шаблону:
{
"id": "sentiment_score",
"displayName": "Sentiment score",
"description": "Deterministic lexicon-based sentiment score for a piece of text.",
"tier": "host_callback",
"classification": "tenant",
"dataResidency": "any",
"inputSchema": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1 } }, "required": ["text"] },
"outputSchema": { "type": "object", "properties": { "score": { "type": "number" } }, "required": ["score"] },
"hostCallback": {
"service": "my-plugin",
"port": 8080,
"path": "/internal/skills/sentiment_score",
"maxRequestBytes": 262144,
"maxResponseBytes": 16384,
"tenantHeader": "X-Organization-ID"
},
"timeoutMs": 10000
}П'ять рівнів (tiers)
Рівень — це не просто мітка. Кожен рівень має власні специфічні поля, і поле, що належить до іншого рівня, не просто тихо ігнорується, а відхиляється з помилкою FIELD_NOT_FOR_TIER.
| Рівень | Вимагає | Звертається до моделі | Хто виконує |
|---|---|---|---|
host_callback |
hostCallback: ваш Service, його порт, шлях та обидва обмеження на розмір у байтах |
Ні | Платформа надсилає POST-запит із вхідними даними до вашого власного Service усередині вашого простору імен |
plugin_queue |
queueName, записується як <plugin name>.<name> |
Ні | Ваш воркер (worker), який забирає завдання з вашої черги |
tool_using |
systemPrompt та tools[]; рівень довіри core або verified |
Так | Платформа через AI Provider Router; кожен виклик інструменту проходить через дозволений виконавець (executor) |
llm_only |
systemPrompt; рівень довіри core або verified |
Так | Платформа, один виклик через AI Provider Router |
map |
map.perItemJobType, що вказує на іншу навичку того самого маніфесту, яка не є map |
Лише через свою цільову навичку | Платформа запускає цільову навичку один раз для кожного елемента та збирає результати |
Жоден із рівнів, що працюють із моделями, не вказує конкретного провайдера чи модель. Маршрутизатор обирає обидва параметри з власного пулу організації, яка ініціювала виклик. Інструмент у навичці рівня tool_using вказує один із шести виконавців (executors): standing_service_call (ваш власний Service), graphrag, graphrag_query, graphrag_search, h3 або web_search. Будь-який інший відхиляється з помилкою EXECUTOR_NOT_PERMITTED. Три виконавці графа знань приймають лише назви інструментів graphrag_query та graphrag_search, оскільки виконавець запускає саме ту операцію, на честь якої названо інструмент.
У реєстрі існують два рівні, які плагін не може оголосити: ланцюжки (chains) та навички, що запускаються самостійно, створюються виключно платформою. Синхронізація, у якій вказано один із них, відхиляється повністю.
Який рівень обрати
- Обирайте
host_callback, коли робота є функцією від вхідних даних, яку обчислює ваш власний код: оцінка, розрахунок, пошук у вашій власній схемі. Його найпростіше тестувати, і він використовується в шаблоні за замовчуванням. Захистіть маршрут зворотного виклику (callback): шлях у маніфесті не є секретом, тому маршрут повинен перевіряти виклик платформи і брати ідентифікатор організації саме з нього, а не з тіла запиту. Оголосіть його якauth: internalі підключіть до ньогоrequireService(Fastify) абоserviceMiddleware(Express). Цей захисний механізм відхиляє токени, випущені для когось іншого. Відповідайте швидко і зробіть так, щоб повторне доставлення того самого завдання було безпечним. - Обирайте
plugin_queueдля тривалішої роботи, на результат якої очікує людина і де життєвим циклом керує ваш воркер. Воркер повинен перевести виконання у статусrunningпід час старту і в кінцевий статус після завершення; воркер, який лише надсилає результат, залишає виконання у статусіqueuedназавжди. - Обирайте
llm_only, коли для виконання завдання достатньо одного виклику моделі з фіксованим системним промптом, а ваш плагін має рівень довіриcoreабоverified. - Обирайте
tool_using, коли моделі потрібно викликати інструменти в циклі — знову ж таки, лише за рівня довіриcoreабоverified. - Обирайте
map, коли вам потрібно, щоб платформа паралельно застосувала одну з ваших інших навичок до кожного елемента списку.
Моя навичка прогнозування орбіти в Corrán Orbital належить до рівня host_callback. Наш плагін має рівень community, тому рівні з використанням моделей ніколи не були доступні, і я за ними не сумую: пропагатор, який у вівторок давав би іншу відповідь, був би гіршим за марний.
Затвердження перед кожним запуском
Навичка маніфесту, яка в жодному разі не повинна запускатися лише за рішенням машини, оголошує це так:
"approval": { "required": true, "reason": "Re-planning a pass needs the flight dynamics lead." }Поле required завжди має значення true; навичка, яка не потребує затвердження, просто опускає цей блок. Поле reason — це текст, який бачить затверджувач, від 1 до 500 символів після обрізання пробілів, а будь-який інший формат відхиляється з помилкою APPROVAL_INVALID. Після цього виклик навички утримується: система відповідає кодом 202 зі статусом status: "awaiting_approval" та ідентифікатором waitpointId, і лише затвердження вказаною особою розблоковує його — один раз. Пакетний (batch) виклик, виклик через map або ланцюжок (chain) для навички з утриманням відхиляється з помилкою SKILL_APPROVAL_NOT_HOLDABLE, оскільки розгалужений запуск не може утримувати свої окремі елементи. Відобразіть відповідь про утримання та дозвольте затверджувачу ухвалити рішення; не викликайте навичку, щоб потім питати згоди.
Синхронізація з реєстром
Кожна синхронізація є декларативною і перевіряється цілісно. Щоразу надсилайте повний набір навичок: навичка, яку ви пропустите, буде вимкнена, але історія її запусків збережеться. Одна некоректна навичка скасовує всю синхронізацію з помилкою SYNC_CONTRACT_VIOLATION, причому всі порушення виводяться разом і нічого не записується, тож плагін ніколи не оновлюється лише наполовину. У Розділі 2.22, Середовище виконання плагінів, детально описано виклик синхронізації та те, як платформа визначає, який саме плагін звертається.
Вибір між двома видами
Якщо завдання звучить як «формулюй це щоразу однаково» — це навичка Skills Engine. Якщо ж завдання — «запусти мій код і поверни його відповідь», то це навичка маніфесту. Більшість реальних завдань зрештою поєднують обидва підходи: зведення по причалах Harrow — це навичка Skills Engine, чиї інструменти надходять із плагіна, а самі інструменти плагіна оголошені в його маніфесті. Навичку Skills Engine змінювати дешевше з-поміж цих двох, і це вагома причина залишити формулювання та судження в ній, а арифметику — у плагіні.
Проте витрати є цілком реальними в обох випадках. Робота над навичкою Skills Engine не закінчується тоді, коли файл SKILL.md добре читається; вона закінчується, коли проходять її тестові сценарії, пробний прогін збігається з рішеннями людей, і хтось інший, окрім вас, її затвердив. Закладайте тиждень на навичку, яка виконує запис даних, — більшу частину цього часу займе канарковий випуск.



