Версия 1.0.0-alpha.1последно
Глава 2.20
Умения
Как да напишете, тествате и публикувате умение за Skills Engine, къде се появява то, след като бъде активирано, и по какво се различават уменията от манифест в плъгин. Включва разработен пример за обобщение на разпределението на корабни места за Harrow Port Authority.
Тази страница е преведена от ИИ от английския оригинал. Ако нещо е неясно, английската страница е референтна. Прочетете тази страница на английски

Tomás Reilly, платформеният инженер в Harrow Port Authority, ме попита миналия месец защо неговите планировчици на корабни места получават различен отговор всеки път, когато попитат асистента „кой на кое корабно място е утре и какво е преместено?“. Отговорът беше, че никой не е казал на асистента как изглежда един добър отговор. Едно умение от Skills Engine реши проблема за един следобед: планировчиците вече получават едно и също обобщение от три части всеки път, като първо е таблицата с корабните места, отдолу са промените от последния план, а най-накрая са конфликтите. Тази глава разглежда това умение от началото до края, а след това обхваща другия вид умение – онова, което се намира в манифеста на приставката.
Два вида умения
Nexus използва думата „умение“ (skill) за две различни неща и те се изграждат по различен начин.
| Умение в Skills Engine | Умение в манифеста | |
|---|---|---|
| Какво представлява | Пакет с SKILL.md в библиотеката с умения |
Типизиран ред в масива skills[] на приставка |
| Кой го пише | Всеки със съответните права, в инструмента за създаване или в собствения си редактор | Разработчик, вътре в приставка |
| Какво съдържа | Инструкции, инструментите, които може да извиква, незадължителни файлове и скриптове | Входна и изходна схема, ниво и полетата, от които се нуждае това ниво |
| Как достига до платформата | Валидирано, качено и публикувано в 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
Заглавната част е YAML код между два реда --- в горната част на файла. Форматът изисква три полета. Самата валидация блокира само при няколко неща: липсващо име или описание, както и слъг или тип задача, които вече са заети. Всичко останало се отчита като предупреждение.
| Поле | Тип | Задължително | Какво съдържа |
|---|---|---|---|
name |
низ | yes | Уникалният идентификатор във формат kebab-case |
description |
низ | yes | Какво прави умението, най-много 500 знака. Библиотеката и модулът за съпоставяне го четат, затова го напишете за читател, който трябва да реши дали това е правилното умение |
allowed-tools |
низ или списък | yes | Инструментите, които умението може да извиква. То може само да стеснява списъка с разрешени инструменти на този, който го изпълнява |
triggers |
списък | no | Команди с наклонена черта, които извикват умението директно |
capabilities |
списък | no | Структурирани възможности, всяка с name, description и по избор input_schema, output_schema и examples |
version |
низ | no | Семантична версия; 1.0.0, когато е пропусната |
visibility |
низ | no | private, team или public |
status |
низ | no | draft, testing или published |
Поддържайте инструкциите под около 5 000 токена. Бъдете конкретни и давайте примери. Всяко умение трябва да върши добре една работа; ако установите, че пишете „и също така“, вероятно имате две умения.
skill.yaml
skill.yaml съдържа това, от което ядрото се нуждае за откриване и за библиотеката, така че SKILL.md да остане четим. Полетата, които ядрото чете, включват name, display_name, description, version, status, visibility, triggers, aliases, category, tags, allowed_tools и capabilities. Една възможност може да съдържа query_patterns – фразите, които модулът за съпоставяне трябва да насочва към нея. Има и подсказки за собственото бюджетиране на ядрото: complexity, estimated_tokens и required_services.
scripts/
Всичко в scripts/ се пакетира дословно с умението като компонент. Скриптът се изпълнява, никога не се чете в контекста на модела и работи в изолирана среда (sandbox). Използвайте такъв, когато дадена стъпка включва аритметика или синтактичен анализ, които моделът не бива да прави наум.
Видимост и статус
Видимостта определя кой може да намери умението: private сте вие, team е вашият екип, а public са всички в организацията, която библиотеката обслужва. В конзолата същият избор гласи „Само аз“, екип като например „Митническо бюро“ или цялата организация, като умението може да бъде споделено и в домейн пакет чрез собствения процес на преглед на този пакет.
Статусът показва на какъв етап от жизнения си цикъл се намира умението.
| Състояние | Значение |
|---|---|
draft |
В процес на разработка; не може да бъде открито |
testing |
В процес на валидиране, с ограничен достъп |
published |
Достъпно за обща употреба |
deprecated |
Заменено; на път да бъде изведено от употреба |
Веднъж публикувана, дадена версия никога не се променя. В конзолата „live“ (активна), „canary“ (тестова) и „shadow“ (в сянка) са етикети върху версиите и връщането към по-ранна версия премества етикета. Текущите изпълнения завършват с версията, с която са започнали.
SKILL.md, файловете до него и кога се зарежда всеки от тях, както и инструментите, които умението може да извиква. На умение за проверка не се предлага инструмент, който записва, а умението може само да стеснява списъка с разрешени инструменти на изпълняващия.От папка до активно умение
Пет npm скрипта в хранилището на Skills Engine пренасят умението от вашия редактор до библиотеката и доказват, че е пристигнало.
| Команда | Какво прави |
|---|---|
npm run skill:validate skills/<slug> |
Проверява пакета (lint). За публикуване са нужни нула грешки |
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, възможности, компоненти и запис за качество; библиотеката, откриването и съпоставянето четат него. Другият е записът в регистъра, спрямо който ядрото за работни потоци разрешава диспечирането. Умение, което е достигнало само до регистъра, се изпълнява, но е невидимо в библиотеката, докато не го качите.
Публикуването е идемпотентно. Непроменено умение не извършва действие (no-op), а съществуващо умение се съпоставя по неговия слъг и се обновява на място, без никога да се пресъздава. Ако качите същите байтове като на вече публикувана версия, получавате обратно тази версия с CONTENT_HASH_ALREADY_PUBLISHED, а не дубликат.
skill:reconcile проверява уменията от вашето хранилище спрямо библиотеката, регистъра и инвентара на ядрото за работни потоци и докладва всичко, което съществува на едно място, но не и на друго. skill:live:verify отива по-далеч в работещата инсталация: и двата записа съществуват и сочат един към друг със същия хеш на съдържанието, пробно диспечиране (dry-run) на типа задача на умението се приема, умението се показва в списъка и детайлите на библиотеката, може да бъде извикано, а одитната следа свързва публикуването, диспечирането и изпълнението по слъг и идентификатор на заявката.
От работна станция качването достига до услугата за знания на инсталацията, 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Вътре в клъстера, в задача от конвейера, адресът по подразбиране се разрешава сам и GRAPHRAG_URL не е необходим. Вземете ключа чрез процеса за управление на тайни на вашата организация. Той никога не трябва да попада в хранилището, в историята на обвивката (shell) или в изхода на команда.
Тестове, одобрение и активиране
Умението пристига в библиотеката като чернова и инструментът за създаване го задържа там, докато не преминат успешно три неща.
| Проверка | Какво прави |
|---|---|
| Тестови случаи | Всеки случай трябва да премине успешно, преди умението да може да отиде за одобрение. Даден случай може да бъде премахнат само с посочване на причина, която одобряващите виждат. |
| Пробно изпълнение в сянка | Умението се изпълнява върху минала работа, където никой не вижда отговорите, а резултатите му се сравняват с това, което човек е решил по онова време. |
| Сляп преглед от модел от друго семейство | Той търси пропусната проверка, измислен източник и вмъкната инструкция, която умението е последвало, когато не е трябвало. |
Следва одобрението. Умение, което добавя записващ инструмент, се задържа, докато двама души не го одобрят със своите ключове за достъп (passkeys), като човекът, който го е предложил, не може да бъде един от тях (PUBLISH_NEEDS_APPROVAL). След това то се активира в сянка (shadow), после тестово (canary) за едно звено зад именувани контролни точки (gates), а накрая и за всички. Ако дадена тестова контролна точка не бъде покрита, тестовото разпространение спира само и всички остават на предишната версия; предсрочното му пускане за всички изисква причина и втори одобряващ (CANARY_GATE_NOT_MET).
В изданието Community инструментът за създаване, библиотеката, версиите и тестовете са налични и собственикът публикува сам, след като тестовете преминат успешно. Тестовото разпространение (canary), одобрението от двама души, синхронизирането на приставки и сливането на дубликати се предлагат с 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
}Петте нива
Нивото не е просто етикет. Всяко ниво има свои собствени полета и поле, което принадлежи на друго ниво, се отхвърля с 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; всяко извикване на инструмент минава през разрешен изпълнител |
llm_only |
systemPrompt; ниво на доверие core или verified |
Да | Платформата, едно извикване чрез AI Provider Router |
map |
map.perItemJobType, посочващо друго умение от същия манифест, което не е map |
Само чрез своята цел | Платформата изпълнява целта по веднъж за всеки елемент и събира резултатите |
Нито едно от нивата с модели не назовава доставчик или модел. Маршрутизаторът избира и двете от собствения пул на диспечиращата организация. Инструмент в умение от тип tool_using посочва един от шест изпълнители: standing_service_call (вашата собствена услуга), 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за по-продължителна работа, която човек изчаква и при която вашият фонов процес (worker) управлява жизнения цикъл. Фоновият процес трябва да премести изпълнението вrunning, когато започне, и в краен статус, когато приключи; фонов процес, който само публикува своя резултат, оставя изпълнението да показваqueuedзавинаги.llm_only, когато едно извикване на модел с фиксирана системна подкана върши работата и вашата приставка еcoreилиverified.tool_using, когато моделът трябва да извиква инструменти в цикъл, отново само приcoreилиverified.map, когато искате платформата да разклони (fan out) някое от другите ви умения върху списък.
Моето умение за орбитална пропагация в 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 звучи добре; то е готово, когато неговите тестови случаи преминат успешно, пробното му изпълнение съвпадне с решенията на хората и някой, който не сте вие, го е одобрил. Предвидете една седмица за умение, което записва, като по-голямата част от нея отива за тестовото разпространение (canary).



