Versiune 1.0.0-alpha.1cea mai recentă
Capitolul 2.20
Abilități (Skills)
Cum să scrieți, să testați și să publicați o abilitate Skills Engine, unde apare odată ce este activă și cum diferă abilitățile din manifest într-un plugin. Include un exemplu practic de rezumat pentru alocarea danelor destinat Harrow Port Authority.
Această pagină a fost tradusă cu ajutorul IA din originalul în limba engleză. Dacă există neclarități, pagina în limba engleză rămâne cea de referință. Citiți această pagină în limba engleză

Tomás Reilly, inginerul de platformă de la Harrow Port Authority, m-a întrebat luna trecută de ce planificatorii săi de dane primeau un răspuns diferit de fiecare dată când întrebau asistentul „cine se află la ce dană mâine și ce s-a schimbat?”. Răspunsul era că nimeni nu îi spusese asistentului cum arată un răspuns bun. O competență din Skills Engine a rezolvat problema într-o după-amiază: planificatorii primesc acum de fiecare dată același rezumat în trei părți, cu tabelul danelor la început, modificările de la ultimul plan dedesubt și conflictele la final. Acest capitol prezintă acea competență de la un capăt la altul, apoi tratează celălalt tip de competență, cea care se află în manifestul unui plugin.
Două tipuri de abilități
Nexus folosește cuvântul „competență” pentru două lucruri diferite, iar acestea sunt construite diferit.
| Abilitate Skills Engine | Competență de manifest | |
|---|---|---|
| Ce reprezintă | Un pachet SKILL.md în biblioteca de competențe |
Un rând tipizat în matricea skills[] a unui plugin |
| Cine o scrie | Oricine are dreptul, în creator sau în propriul editor | Un dezvoltator, în cadrul unui plugin |
| Ce conține | Instrucțiuni, instrumentele pe care le poate apela, fișiere și scripturi opționale | O schemă de intrare și de ieșire, un nivel și câmpurile de care are nevoie acel nivel |
| Cum ajunge pe platformă | Validată, încărcată și publicată în Skills Engine | Compilată din manifest și sincronizată cu registrul de competențe |
| Ce o rulează | Asistentul, agenții, fluxurile de lucru, butoanele IA (inteligență artificială), Claude Code | Distribuirea prin UNO (motorul de fluxuri de lucru) |
| Utilizare tipică | „Rezumă planul danelor în același mod de fiecare dată” | „Rulează propagatorul nostru de orbită pe această trecere” |
Restul capitolului le tratează separat. Dacă un paragraf spune doar „competență”, este vorba de o competență din Skills Engine.
Partea 1: abilități Skills Engine
Ce este o competență
O competență este un dosar. Fișierul său SKILL.md spune la ce servește competența și cum se realizează sarcina; alături se află fișierele de care are nevoie sarcina și scripturile pe care le rulează. Motorul încarcă o competență în trei straturi: numele și descrierea întotdeauna, instrucțiunile atunci când o sarcină solicită competența, iar fișierele doar atunci când un pas are nevoie de ele. De aceea, o instalare poate conține două sute de competențe și nu plătește aproape nimic pentru ele până când una este folosită.
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
Numele directorului trebuie să fie identic cu slug-ul competenței. O nepotrivire generează un avertisment de validare și merită corectată, deoarece slug-ul este modul în care biblioteca asociază o încărcare cu o competență existentă.
Antetul SKILL.md
Antetul este YAML aflat între două linii --- în partea de sus a fișierului. Formatul impune trei câmpuri. Validarea în sine blochează doar câteva situații: lipsa numelui sau a descrierii și un slug sau un tip de sarcină deja ocupat. Toate celelalte sunt raportate ca avertismente.
| Câmp | Tip | Obligatoriu | Ce conține |
|---|---|---|---|
name |
string | yes | Identificatorul unic, în kebab-case |
description |
string | yes | Ce face competența, cel mult 500 de caractere. Biblioteca și mecanismul de potrivire o citesc, așa că scrieți-o pentru un cititor care decide dacă aceasta este competența potrivită |
allowed-tools |
string sau listă | yes | Instrumentele pe care competența le poate apela. Poate doar să restrângă lista de permisiuni a celui care o rulează |
triggers |
listă | no | Comenzi slash care invocă direct competența |
capabilities |
listă | no | Capabilități structurate, fiecare cu un name, un description și, opțional, input_schema, output_schema și examples |
version |
string | no | O versiune semantică; 1.0.0 dacă este omisă |
visibility |
string | no | private, team sau public |
status |
string | no | draft, testing sau published |
Păstrați instrucțiunile sub aproximativ 5,000 de tokeni. Fiți specific și dați exemple. Fiecare competență ar trebui să facă bine un singur lucru; dacă vă surprindeți scriind „și de asemenea”, probabil aveți două competențe.
skill.yaml
skill.yaml conține ceea ce îi trebuie motorului pentru descoperire și pentru bibliotecă, astfel încât SKILL.md să rămână lizibil. Câmpurile citite de motor includ name, display_name, description, version, status, visibility, triggers, aliases, category, tags, allowed_tools și capabilities. O capabilitate poate conține query_patterns, formulările pe care mecanismul de potrivire ar trebui să le direcționeze către ea. Există și indicații pentru propria gestionare a bugetului de către motor: complexity, estimated_tokens și required_services.
scripts/
Tot ce se află sub scripts/ este inclus ca atare în competență, sub formă de componentă. Un script este rulat, niciodată citit în contextul modelului, și rulează într-un sandbox. Folosiți unul atunci când un pas implică aritmetică sau analiză sintactică pe care un model nu ar trebui să o facă din cap.
Vizibilitate și stare
Vizibilitatea indică cine poate găsi competența: private înseamnă dumneavoastră, team înseamnă echipa dumneavoastră, iar public înseamnă toată lumea din organizația deservită de bibliotecă. În consolă, aceeași opțiune apare ca „Doar eu”, o echipă precum „Biroul vamal” sau întreaga organizație, iar o competență poate fi partajată și într-un pachet de domeniu, prin propria revizuire a acelui pachet.
Starea indică stadiul în care se află competența în ciclul său de viață.
| Stare | Semnificație |
|---|---|
draft |
În lucru; nu poate fi descoperită |
testing |
În curs de validare, cu acces limitat |
published |
Disponibilă pentru uz general |
deprecated |
Înlocuită; în curs de retragere |
Odată publicată, o versiune nu se mai schimbă niciodată. În consolă, „live”, „canary” și „shadow” sunt etichete pe versiuni, iar revenirea la o versiune anterioară mută o etichetă. Rulările în curs se încheie pe versiunea cu care au început.
SKILL.md, fișierele de alături și momentul în care se încarcă fiecare, precum și instrumentele pe care competența le poate apela. Unei competențe de verificare nu i se oferă niciun instrument care scrie, iar o competență poate doar să restrângă lista de permisiuni a celui care o rulează.De la un dosar la o competență activă
Cinci scripturi npm din depozitul Skills Engine duc o competență din editorul dumneavoastră în bibliotecă și dovedesc că a ajuns acolo.
| Comandă | Ce face |
|---|---|
npm run skill:validate skills/<slug> |
Verifică pachetul. Publicarea necesită zero erori |
npm run skill:upload skills/<slug> |
Validează și publică într-un singur pas; idempotent |
npm run skill:upload skills/<slug> --dry-run |
Validează și afișează planul fără a scrie nimic |
npm run skill:publish -- --dry-run skills/<slug> |
Publicarea de nivel inferior din spatele încărcării, același flux |
npm run skill:reconcile |
Compară competențele din depozitul dumneavoastră cu cele din bibliotecă și din registrul de competențe |
npm run skill:live:verify |
Verifică de la un capăt la altul o competență publicată pe instalarea în funcțiune |
Publicarea scrie două înregistrări și ambele contează. Una este competența însăși, cu corpul SKILL.md, capabilitățile, componentele și istoricul de calitate; biblioteca, descoperirea și potrivirea o citesc pe aceasta. Cealaltă este înregistrarea din registru pe baza căreia motorul de fluxuri de lucru rezolvă o distribuire. O competență care a ajuns doar în registru rulează, dar este invizibilă în bibliotecă până când o încărcați.
Publicarea este idempotentă. O competență neschimbată nu produce niciun efect, iar o competență existentă este identificată după slug și actualizată pe loc, niciodată recreată. Dacă încărcați aceiași octeți ca o versiune deja publicată, primiți înapoi acea versiune cu CONTENT_HASH_ALREADY_PUBLISHED, nu un duplicat.
skill:reconcile parcurge competențele din depozitul dumneavoastră comparându-le cu biblioteca, registrul și inventarul motorului de fluxuri de lucru și raportează orice există într-un loc și nu în altul. skill:live:verify merge mai departe pe instalarea în funcțiune: ambele înregistrări există și indică una spre cealaltă cu același hash de conținut, o distribuire de probă a tipului de sarcină al competenței este acceptată, competența apare în lista și în detaliile bibliotecii, poate fi invocată, iar jurnalul de audit leagă publicarea, distribuirea și rularea prin slug și ID-ul cererii.
De pe o stație de lucru, încărcarea ajunge la serviciul de cunoștințe al instalării, nexus-graphrag, printr-un port-forward și necesită cheia de serviciu a Skills Engine în mediu. Încărcați cheia fără a o afișa:
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În interiorul clusterului, într-o sarcină de pipeline, adresa implicită se rezolvă singură și GRAPHRAG_URL nu este necesar. Obțineți cheia prin procesul propriu de gestionare a secretelor al organizației dumneavoastră. Aceasta nu ajunge niciodată în depozit, în istoricul shell-ului sau în ieșirea unei comenzi.
Teste, aprobare și punere în funcțiune
O competență ajunge în bibliotecă ca schiță, iar creatorul o păstrează astfel până când trec trei verificări.
| Verificare | Ce face |
|---|---|
| Cazuri de test | Fiecare caz trebuie să treacă înainte ca competența să poată fi trimisă spre aprobare. Un caz poate fi eliminat doar cu o justificare, pe care aprobatorii o văd. |
| O rulare de probă în modul shadow | Competența rulează pe activități trecute, unde nimeni nu vede răspunsurile, iar rezultatele sale sunt comparate cu ce a decis o persoană la momentul respectiv. |
| O revizuire oarbă realizată de un model din altă familie | Aceasta caută o verificare omisă, o sursă inventată și o instrucțiune plantată pe care competența a urmat-o când nu ar fi trebuit. |
Urmează aprobarea. O competență care adaugă un instrument care scrie este reținută până când două persoane o aprobă cu passkey-urile lor, iar persoana care a propus-o nu poate fi una dintre ele (PUBLISH_NEEDS_APPROVAL). Apoi intră în funcțiune în modul shadow, apoi în canary pentru o unitate, în spatele unor praguri denumite, apoi pentru toată lumea. Dacă un prag canary nu este îndeplinit, canary se oprește singur și toată lumea rămâne pe versiunea anterioară; trimiterea timpurie către toată lumea necesită o justificare și un al doilea aprobator (CANARY_GATE_NOT_MET).
În Community, creatorul, biblioteca, versiunile și testele sunt toate disponibile, iar proprietarul publică singur după ce testele trec. Canary, aprobarea de către două persoane, sincronizarea pluginurilor și unificarea duplicatelor vin odată cu Enterprise.
Unde apar competențele
Aceeași competență publicată ajunge la utilizatori în cinci locuri.
- Asistentul asociază o cerere cu o competență după descrierea, declanșatorii și tiparele de interogare ale acesteia și urmează instrucțiunile competenței.
- Agenții și fluxurile de lucru apelează competențe ca pași. Un pas de flux de lucru numește competența; rularea înregistrează ce versiune a folosit.
- Butoanele IA de pe ecrane rulează fiecare câte o competență. Un administrator poate deschide „Despre acest buton” pentru a vedea competența pe care o rulează un buton, ce citește aceasta și cine a modificat-o ultima dată, și poate dezactiva butonul fără a atinge competența.
- IDE-ul dumneavoastră (mediu de dezvoltare integrat) și Claude Code accesează biblioteca prin Workbench și treisprezece instrumente MCP (Model Context Protocol), printre care
list_skills,get_skill,match_prompt,discover_skills,invoke_skill,record_execution,create_skill,import_skill,get_generation_jobșisync_skills_local. Fiecare apel rulează în numele persoanei care l-a inițiat, în cadrul listei sale de permisiuni. - Biblioteca de competențe însăși, unde utilizatorii răsfoiesc, rulează și propun modificări ale competențelor, iar administratorii văd proprietarul, utilizatorii, rulările și costurile fiecărei competențe.
Indiferent ce rulează o competență, aceasta nu poate extinde ce are voie să facă cel care o rulează: apelează doar instrumente din lista de permisiuni a acestuia și citește doar ce poate deschide acea persoană (SKILL_CANNOT_WIDEN_TOOLS). O rulare fără o rută de model este refuzată, nu ghicită (SKILLS_ENGINE_BINDING_MISSING); dispecerul alege ruta, din propria configurație de modele a organizației.
Exemplu practic: un rezumat al alocării danelor pentru Harrow
Planificatorii Harrow aveau deja în lista de permisiuni două instrumente doar pentru citire, din pluginul propriu de planificare a danelor al Harrow: berth-plan.read returnează planul pentru o dată, iar vessel-call.read returnează o escală de navă cu fereastra de sosire și lungimea acesteia. Competența nu are nevoie de nimic altceva. Nu scrie niciodată, deci nu are niciodată nevoie de doi aprobatori.
---
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.Fișierul skill.yaml de alături oferă bibliotecii un nume afișat, o categorie și formulările pe care mecanismul de potrivire ar trebui să le direcționeze aici:
# 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 *"Apoi comenzile, din rădăcina depozitului:
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 a adăugat șase cazuri de test în creator: o zi obișnuită, o zi cu o sosire întârziată care a mutat două escale, o zi cu un conflict real, o dată fără plan încă, o navă prea lungă pentru dana sa și o cerere care încerca să determine competența să propună o dană nouă (nu ar trebui; nu are niciun instrument care scrie). Rularea de probă a reluat douăzeci de planuri anterioare în modul shadow. După ce cazurile au trecut, un evaluator de la biroul de planificare a aprobat-o, iar aceasta a intrat în funcțiune pentru echipa de planificare. Asistentul răspunde acum la întrebare în aceeași formă de fiecare dată, iar butonul IA al planificatorilor de pe pagina planului danelor rulează aceeași competență.
Partea 2: abilități din manifest
O competență de manifest este unitatea de calcul pe care o publică un plugin. Este declarată în skills[] din manifest, validată de SDK (kit de dezvoltare software) când rulați create-nexus-plugin validate, compilată în corpul din registru de compileRegistry și sincronizată cu registrul de competențe. Nu scrieți niciodată manual SQL pentru registru, astfel încât rândul pe care platforma îl distribuie și descriptorul pe care l-ați declarat nu se pot desincroniza.
Fiecare competență de manifest necesită id, displayName, description, tier, classification, inputSchema și outputSchema. Declarați și timeoutMs: este un număr întreg de la 1.000 la 21.600.000 (de la o secundă la șase ore), iar o valoare din afara acestui interval este refuzată cu TIMEOUT_OUT_OF_BOUNDS. dataResidency este any, eu sau us, iar any este valoarea implicită.
id este în format lower_snake, iar cheia de dispecerizare din registru este tipul de job cu spațiu de nume <plugin name>.<skill id>, astfel încât două pluginuri pot avea fiecare o abilitate summarise fără a intra în conflict. Iată singura abilitate a șablonului, prescurtată:
{
"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
}Cele cinci niveluri
Nivelul nu este o simplă etichetă. Fiecare nivel are propriile câmpuri, iar un câmp care aparține altui nivel este refuzat cu FIELD_NOT_FOR_TIER, în loc să fie ignorat în tăcere.
| Nivel | Necesită | Ajunge la un model | Cine îl rulează |
|---|---|---|---|
host_callback |
hostCallback: Service-ul dumneavoastră, portul său, o cale și ambele limite de octeți |
Nu | Platforma trimite prin POST datele de intrare către propriul dumneavoastră Service, în namespace-ul dumneavoastră |
plugin_queue |
queueName, scris <plugin name>.<name> |
Nu | Worker-ul dumneavoastră, care preia din coada dumneavoastră |
tool_using |
systemPrompt și tools[]; încredere core sau verified |
Da | Platforma, prin AI Provider Router; fiecare apel de instrument rulează printr-un executor aflat pe lista de permisiuni |
llm_only |
systemPrompt; încredere core sau verified |
Da | Platforma, printr-un singur apel prin AI Provider Router |
map |
map.perItemJobType, care numește o altă abilitate din același manifest care nu este de tip map |
Doar prin ținta sa | Platforma rulează ținta o dată pentru fiecare element și colectează rezultatele |
Niciunul dintre nivelurile bazate pe model nu numește un furnizor sau un model. Router-ul le alege pe amândouă din propriul fond al organizației care face dispecerizarea. Un instrument dintr-o abilitate tool_using numește unul dintre cele șase executoare: standing_service_call (propriul dumneavoastră Service), graphrag, graphrag_query, graphrag_search, h3 sau web_search. Oricare altul este refuzat cu EXECUTOR_NOT_PERMITTED. Cele trei executoare de graf de cunoștințe acceptă doar numele de instrumente graphrag_query și graphrag_search, deoarece executorul rulează orice operație după care este numit instrumentul.
În registru există două niveluri pe care un plugin nu le poate declara: lanțurile și abilitățile care rulează independent sunt scrise doar de platformă. O sincronizare care numește unul dintre ele este refuzată în întregime.
Ce nivel să utilizați
host_callbackatunci când lucrarea este o funcție a datelor de intrare pe care o calculează propriul dumneavoastră cod: un scor, un calcul, o căutare în propria dumneavoastră schemă. Este cel mai simplu de testat și este opțiunea implicită a șablonului. Protejați ruta de callback: o cale dintr-un manifest nu este un secret, iar ruta trebuie să verifice apelul platformei și să preia organizația din acesta, niciodată din corpul cererii. Declarați-oauth: internalși montațirequireService(Fastify) sauserviceMiddleware(Express) pe ea. Protecția refuză un token emis pentru oricine altcineva. Răspundeți rapid și faceți ca o a doua livrare a aceluiași job să fie inofensivă.plugin_queuepentru lucrări mai lungi pe care o persoană le așteaptă, unde worker-ul dumneavoastră gestionează ciclul de viață. Worker-ul trebuie să treacă rularea înrunningcând începe și într-o stare finală când se termină; un worker care doar își publică rezultatul lasă rularea afișândqueuedpentru totdeauna.llm_onlyatunci când un singur apel de model cu un prompt de sistem fix face treaba, iar pluginul dumneavoastră estecoresauverified.tool_usingatunci când modelul trebuie să apeleze instrumente într-o buclă, din nou doar lacoresauverified.mapatunci când doriți ca platforma să distribuie una dintre celelalte abilități ale dumneavoastră peste o listă.
Abilitatea mea de propagare a orbitelor de la Corrán Orbital este de tip host_callback. Pluginul nostru este community, deci nivelurile bazate pe model nu au fost niciodată o opțiune și nu îmi lipsesc: un propagator care ar da un răspuns diferit marțea ar fi mai rău decât inutil.
Aprobare înaintea fiecărei rulări
O abilitate din manifest care nu trebuie să ruleze niciodată doar la comanda unei mașini declară acest lucru:
"approval": { "required": true, "reason": "Re-planning a pass needs the flight dynamics lead." }required este întotdeauna true; o abilitate care nu necesită aprobare omite blocul. reason este ceea ce vede aprobatorul, între 1 și 500 de caractere după eliminarea spațiilor, iar orice altă formă este refuzată cu APPROVAL_INVALID. O dispecerizare a abilității este apoi reținută: dispecerizarea răspunde 202 cu status: "awaiting_approval" și un waitpointId, și doar aprobarea unei persoane nominalizate o eliberează, o singură dată. O dispecerizare de tip batch, map sau lanț a unei abilități reținute este refuzată cu SKILL_APPROVAL_NOT_HOLDABLE, deoarece o distribuire nu își poate reține elementele. Afișați răspunsul de reținere și lăsați aprobatorul să decidă; nu dispecerizați pentru ca apoi să cereți consimțământul.
Sincronizarea cu registrul
Fiecare sincronizare este declarativă și verificată în întregime. Trimiteți de fiecare dată setul complet de abilități: o abilitate pe care o omiteți este dezactivată, iar istoricul rulărilor sale se păstrează. O singură abilitate greșită refuză întreaga sincronizare cu SYNC_CONTRACT_VIOLATION, toate încălcările fiind listate împreună și nimic nefiind scris, astfel încât un plugin nu este niciodată actualizat doar pe jumătate. Capitolul 2.22, Mediul de rulare al pluginurilor, tratează apelul de sincronizare și modul în care platforma știe ce plugin face apelul.
Alegerea între cele două tipuri
Dacă sarcina este „spune acest lucru în același mod de fiecare dată”, este o abilitate Skills Engine. Dacă sarcina este „rulează codul meu și dă-mi răspunsul lui”, este o abilitate din manifest. Majoritatea lucrărilor reale ajung să fie ambele: rezumatul danelor de la Harrow este o abilitate Skills Engine ale cărei instrumente provin dintr-un plugin, iar instrumentele pluginului sunt ele însele declarate în manifestul acestuia. Abilitatea Skills Engine este cea mai ieftină dintre cele două de modificat, ceea ce este un motiv bun pentru a păstra formularea și judecata acolo, iar calculele în plugin.
Costul este real în ambele cazuri. O abilitate Skills Engine nu este gata atunci când SKILL.md sună bine; este gata atunci când cazurile sale trec, rularea sa de probă concordă cu ceea ce au decis oamenii și cineva care nu sunteți dumneavoastră a aprobat-o. Alocați o săptămână pentru o abilitate care scrie, cea mai mare parte pentru etapa canary.



