Versjon 1.0.0-alpha.1nyeste
Kapittel 2.20
Ferdigheter
Hvordan du skriver, tester og publiserer en ferdighet i Skills Engine, hvor den dukker opp når den er i bruk, og hvordan manifestferdigheter i et programtillegg skiller seg ut. Inkluderer et gjennomarbeidet sammendrag av kaiplasstildeling for Harrow Port Authority.
Denne siden er oversatt med KI fra den engelske originalen. Hvis noe er uklart, er den engelske siden referansen. Les denne siden på engelsk

Tomás Reilly, plattformingeniøren hos Harrow Port Authority, spurte meg i forrige måned hvorfor kaiplanleggerne hans fikk et ulikt svar hver gang de spurte assistenten «hvem ligger ved hvilken kai i morgen, og hva er flyttet?». Svaret var at ingen hadde fortalt assistenten hvordan et godt svar ser ut. En ferdighet i Skills Engine løste det på en ettermiddag: Planleggerne får nå det samme tredelte sammendraget hver gang, med kaitabellen først, endringene siden forrige plan under og konfliktene til slutt. Dette kapittelet gjennomgår den ferdigheten fra start til slutt, og tar deretter for seg den andre typen ferdighet – den som ligger i en utvidelses manifest.
To typer ferdigheter
Nexus bruker ordet «ferdighet» (skill) om to forskjellige ting, og de bygges ulikt.
| Skills Engine-ferdighet | Manifestferdighet | |
|---|---|---|
| Hva det er | En SKILL.md-pakke i ferdighetsbiblioteket |
En typet rad i en utvidelses skills[]-tabell |
| Hvem som skriver den | Alle med tilgang, i verktøyet for oppretting eller i eget redigeringsprogram | En utvikler, inne i en utvidelse |
| Hva den inneholder | Instruksjoner, verktøyene den kan kalle, valgfrie filer og skript | Et skjema for inndata og utdata, et nivå (tier) og feltene dette nivået krever |
| Hvordan den når plattformen | Validert, lastet opp og publisert til Skills Engine | Kompilert fra manifestet og synkronisert til ferdighetsregisteret |
| Hva som kjører den | Assistenten, agenter, arbeidsflyter, KI-knapper (kunstig intelligens), Claude Code | UNO-utsendelse (arbeidsflytmotoren) |
| Typisk bruk | «Oppsummer kaiplanen på samme måte hver gang» | «Kjør banepropagatoren vår på denne passeringen» |
Resten av kapittelet holder dem adskilt. Hvis et avsnitt bare sier «ferdighet», gjelder det en ferdighet i Skills Engine.
Del 1: ferdigheter i Skills Engine
Hva en ferdighet er
En ferdighet er en mappe. Dens SKILL.md sier hva ferdigheten er til for og hvordan jobben skal gjøres; ved siden av den ligger eventuelle filer jobben trenger og skript den kjører. Motoren laster inn en ferdighet i tre lag: navnet og beskrivelsen alltid, instruksjonene når en oppgave ber om ferdigheten, og filene kun når et trinn trenger dem. Det er grunnen til at en installasjon kan inneholde to hundre ferdigheter og nesten ikke betale noe for dem før en av dem tas i bruk.
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
Mappenavnet må være likt ferdighetens slug. Et avvik gir en valideringsadvarsel, og det er verdt å rette opp, ettersom slug-en er måten biblioteket kobler en opplasting til en eksisterende ferdighet på.
SKILL.md-frontmatter
Frontmatter er YAML mellom to ----linjer øverst i filen. Formatet krever tre felt. Selve valideringen blokkerer kun på noen få ting: et manglende navn eller en manglende beskrivelse, og en slug eller jobbtype som allerede er i bruk. Alt annet rapporteres som en advarsel.
| Felt | Type | Påkrevd | Hva den inneholder |
|---|---|---|---|
name |
streng | ja | Den unike identifikatoren, i kebab-case |
description |
streng | ja | Hva ferdigheten gjør, på maksimalt 500 tegn. Biblioteket og koblingsfunksjonen leser den, så skriv den for en leser som skal avgjøre om dette er den rette ferdigheten |
allowed-tools |
streng eller liste | ja | Verktøyene ferdigheten kan kalle. Den kan kun snevre inn tillatelseslisten til den som kjører den |
triggers |
liste | nei | Skråstrekskommandoer som starter ferdigheten direkte |
capabilities |
liste | nei | Strukturerte kapabiliteter, hver med en name, en description og valgfritt input_schema, output_schema og examples |
version |
streng | nei | En semantisk versjon; 1.0.0 når utelatt |
visibility |
streng | nei | private, team eller public |
status |
streng | nei | draft, testing eller published |
Hold instruksjonene under omtrent 5 000 tokens. Vær spesifikk og gi eksempler. Hver ferdighet bør gjøre én jobb godt; hvis du tar deg selv i å skrive «og i tillegg», har du sannsynligvis to ferdigheter.
skill.yaml
skill.yaml inneholder det motoren trenger for oppdagelse og for biblioteket, slik at SKILL.md forblir lesbar. Feltene motoren leser, omfatter name, display_name, description, version, status, visibility, triggers, aliases, category, tags, allowed_tools og capabilities. En kapabilitet kan inneholde query_patterns, formuleringene som koblingsfunksjonen skal sende til den. Det finnes også hint for motorens egen budsjettering: complexity, estimated_tokens og required_services.
scripts/
Alt under scripts/ pakkes ordrett sammen med ferdigheten som en komponent. Et skript blir kjørt, aldri lest inn i modellens kontekst, og det kjører i en sandkasse. Bruk et skript når et trinn består av aritmetikk eller tolking (parsing) som en modell ikke bør gjøre i hodet.
Synlighet og status
Synlighet avgjør hvem som kan finne ferdigheten: private er deg, team er teamet ditt, og public er alle i organisasjonen som biblioteket betjener. I konsollen vises det samme valget som «Kun meg», et team som «Tollkontoret», eller hele organisasjonen, og en ferdighet kan også deles inn i en domenepakke gjennom pakkens egen gjennomgang.
Status angir hvor ferdigheten er i livsløpet sitt.
| Status | Betydning |
|---|---|
draft |
Under arbeid; ikke søkbar |
testing |
Under validering, med begrenset tilgang |
published |
Tilgjengelig for allmenn bruk |
deprecated |
Erstattet; på vei til å fases ut |
Når en versjon er publisert, endres den aldri. I konsollen er «live», «canary» og «shadow» etiketter på versjoner, og det å bytte tilbake til en tidligere versjon flytter en etikett. Kjøringer som pågår, fullføres på den versjonen de startet med.
SKILL.md, filene ved siden av den og når hver av dem lastes inn, samt verktøyene ferdigheten kan kalle. En kontrollferdighet tilbys ingen verktøy som skriver, og en ferdighet kan kun snevre inn tillatelseslisten til den som kjører den.Fra en mappe til en ferdighet i produksjon
Fem npm-skript i kodelageret til Skills Engine tar en ferdighet fra redigeringsprogrammet ditt til biblioteket og bekrefter at den kom frem.
| Kommando | Hva den gjør |
|---|---|
npm run skill:validate skills/<slug> |
Kjører lint-kontroll på pakken. Publisering krever null feil |
npm run skill:upload skills/<slug> |
Validerer og publiserer i ett trinn; idempotent |
npm run skill:upload skills/<slug> --dry-run |
Validerer og skriver ut planen uten å skrive noe |
npm run skill:publish -- --dry-run skills/<slug> |
Publiseringen på lavere nivå bak opplastingen, samme rørledning (pipeline) |
npm run skill:reconcile |
Sammenligner ferdighetene i kodelageret ditt med det biblioteket og ferdighetsregisteret inneholder |
npm run skill:live:verify |
Kontrollerer en publisert ferdighet fra start til slutt på den kjørende installasjonen |
Publisering skriver to oppføringer, og begge er viktige. Den ene er selve ferdigheten, med dens SKILL.md-innhold, kapabiliteter, komponenter og kvalitetslogg; biblioteket, oppdagelse og kobling leser denne. Den andre er registeroppføringen som arbeidsflytmotoren løser en utsendelse mot. En ferdighet som kun nådde registeret, kan kjøre, men den er usynlig i biblioteket inntil du laster den opp.
Publisering er idempotent. En uendret ferdighet gjør ingenting (no-op), og en eksisterende ferdighet kobles via sin slug og oppdateres på stedet, aldri gjenopprettet. Laster du opp de samme bytene som en versjon som allerede er publisert, får du den versjonen tilbake med CONTENT_HASH_ALREADY_PUBLISHED, ikke et duplikat.
skill:reconcile gjennomgår ferdighetene i kodelageret ditt opp mot biblioteket, registeret og arbeidsflytmotorens beholdning, og rapporterer alt som finnes ett sted og ikke et annet. skill:live:verify går lenger på den kjørende installasjonen: Begge oppføringene finnes og peker på hverandre med samme innholds-hash, en prøvekjørt utsendelse av ferdighetens jobbtype godtas, ferdigheten vises i bibliotekets liste og detaljvisning, den kan kalles, og revisjonsloggen knytter publiseringen, utsendelsen og kjøringen sammen via slug og forespørsels-ID.
Fra en arbeidsstasjon når opplastingen installasjonens kunnskapstjeneste, nexus-graphrag, gjennom en portvideresending, og den krever tjenestenøkkelen til Skills Engine i miljøet. Last inn nøkkelen uten å skrive den ut på skjermen:
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-summaryInne i klyngen, i en rørledningsjobb, løses standardadressen av seg selv og GRAPHRAG_URL er ikke nødvendig. Hent nøkkelen gjennom organisasjonens egen prosess for hemmeligheter. Den skal aldri inn i kodelageret, skallhistorikken din eller i utdataene fra en kommando.
Tester, godkjenning og produksjonssetting
En ferdighet når biblioteket som et utkast, og opprettingsverktøyet holder den der til tre ting er bestått.
| Kontroll | Hva den gjør |
|---|---|
| Testtilfeller | Hvert tilfelle må bestås før ferdigheten kan sendes til godkjenning. Et tilfelle kan kun fjernes med en begrunnelse, som godkjennerne ser. |
| En prøvekjøring i skyggemodus (shadow) | Ferdigheten kjører på tidligere arbeid, der ingen ser svarene, og resultatene sammenlignes med hva en person bestemte den gangen. |
| En blind gjennomgang av en modell fra en annen familie | Den ser etter en oversett kontroll, en oppdiktet kilde og en plantet instruksjon som ferdigheten fulgte da den ikke burde gjort det. |
Deretter følger godkjenning. En ferdighet som legger til et verktøy som skriver, holdes tilbake til to personer godkjenner den med passnøklene sine, og personen som foreslo den, kan ikke være en av dem (PUBLISH_NEEDS_APPROVAL). Den settes deretter i produksjon i skyggemodus, så i kanarimodus (canary) for én enhet bak navngitte kontrollpunkter (gates), og deretter for alle. Hvis et kontrollpunkt for kanarimodus ikke innfris, stopper kanarikjøringen seg selv og alle forblir på forrige versjon; å sende den ut til alle før tiden krever en begrunnelse og en ekstra godkjenner (CANARY_GATE_NOT_MET).
I Community er opprettingsverktøyet, biblioteket, versjoner og tester på plass, og eieren publiserer alene så snart testene er bestått. Kanarimodus, topersonsgodkjenning, utvidelsessynkronisering og sammenslåing av duplikater følger med Enterprise.
Hvor ferdigheter dukker opp
Den samme publiserte ferdigheten når brukere på fem steder.
- Assistenten kobler en forespørsel til en ferdighet basert på beskrivelse, utløsere og spørremønstre, og følger ferdighetens instruksjoner.
- Agenter og arbeidsflyter kaller ferdigheter som trinn. Et arbeidsflyttrinn navngir ferdigheten; kjøringen registrerer hvilken versjon den brukte.
- KI-knapper på skjermbilder kjører én ferdighet hver. En administrator kan åpne «Om denne knappen» for å se hvilken ferdighet en knapp kjører, hva den leser og hvem som sist endret den, og kan slå av knappen uten å røre ferdigheten.
- Ditt IDE (integrert utviklingsmiljø) og Claude Code når biblioteket gjennom Workbench og tretten MCP-verktøy (Model Context Protocol):
list_skills,get_skill,match_prompt,discover_skills,invoke_skill,record_execution,create_skill,import_skill,get_generation_jobogsync_skills_localer blant dem. Hvert kall kjører som personen som startet det, innenfor vedkommendes tillatelsesliste. - Selve ferdighetsbiblioteket, der folk blar gjennom, kjører og foreslår endringer i ferdigheter, og administratorer ser hver ferdighets eier, brukere, kjøringer og forbruk.
Uansett hva som kjører en ferdighet, kan ikke ferdigheten utvide hva den som kjører den har lov til å gjøre: Den kaller kun verktøy innenfor kjørerens tillatelsesliste og leser kun det denne personen har tilgang til å åpne (SKILL_CANNOT_WIDEN_TOOLS). En kjøring uten en modellrute avvises i stedet for å gjettes (SKILLS_ENGINE_BINDING_MISSING); utsenderen velger ruten fra organisasjonens eget modelloppsett.
Praktisk eksempel: et sammendrag av kaitildeling for Harrow
Planleggerne hos Harrow hadde allerede to skrivebeskyttede verktøy på tillatelseslisten sin fra Harrows egen utvidelse for kaiplanlegging: berth-plan.read returnerer planen for en dato, og vessel-call.read returnerer et skipsanløp med ankomstvindu og lengde. Ferdigheten trenger ingenting annet. Den skriver aldri, så den trenger aldri to godkjennere.
---
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-filen ved siden av den gir biblioteket et visningsnavn, en kategori og formuleringene som koblingsfunksjonen skal rute hit:
# 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 *"Deretter kommandoene, fra kodelagerets rotmappe:
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 la til seks testtilfeller i opprettingsverktøyet: en vanlig dag, en dag med en sen ankomst som flyttet to anløp, en dag med en reell konflikt, en dato uten plan ennå, et fartøy som var for langt for kaien sin, og en forespørsel som forsøkte å få ferdigheten til å foreslå en ny kai (det skal den ikke; den har intet verktøy som skriver). Prøvekjøringen spilte av tjue tidligere planer på nytt i skyggemodus. Da tilfellene var bestått, godkjente en kontrollør ved planleggingskontoret den, og den ble satt i produksjon for planleggingsteamet. Assistenten svarer nå på spørsmålet i samme form hver gang, og planleggernes KI-knapp på kaiplansiden kjører den samme ferdigheten.
Del 2: manifestferdigheter
En manifestferdighet er beregningsenheten en utvidelse publiserer. Den deklareres i manifestets skills[], valideres av SDK-en (programvareutviklingssettet) når du kjører create-nexus-plugin validate, kompileres inn i registerinnholdet av compileRegistry og synkroniseres til ferdighetsregisteret. Du skriver aldri register-SQL for hånd, så raden plattformen sender ut og beskrivelsen du deklarerte, kan ikke gli fra hverandre.
Hver manifestferdighet krever id, displayName, description, tier, classification, inputSchema og outputSchema. Deklarer timeoutMs også: Det er et heltall fra 1 000 til 21 600 000 (ett sekund til seks timer), og en verdi utenfor dette området avvises med TIMEOUT_OUT_OF_BOUNDS. dataResidency er any, eu eller us, og any er standard.
id er i lower_snake, og registerets utsendelsesnøkkel er jobbtypen <plugin name>.<skill id> med navnerom, slik at to utvidelser begge kan ha en summarise-ferdighet uten å kollidere. Her er malens ene ferdighet, nedkortet:
{
"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
}De fem nivåene
Nivået (tier) er ikke en etikett. Hvert nivå har sine egne felt, og et felt som tilhører et annet nivå, avvises med FIELD_NOT_FOR_TIER i stedet for å bli droppet i det stille.
| Nivå | Krever | Når en modell | Hvem som kjører den |
|---|---|---|---|
host_callback |
hostCallback: din Service, dens port, en sti og begge bytegrensene |
Nei | Plattformen sender inndata via POST til din egen Service, innenfor ditt navnerom |
plugin_queue |
queueName, stavet <plugin name>.<name> |
Nei | Din arbeidsprosess (worker), som henter fra din kø |
tool_using |
systemPrompt og tools[]; tillit core eller verified |
Ja | Plattformen, gjennom AI Provider Router; hvert verktøykall kjører gjennom en godkjent utfører (executor) |
llm_only |
systemPrompt; tillit core eller verified |
Ja | Plattformen, ett kall gjennom AI Provider Router |
map |
map.perItemJobType, som navngir en annen ferdighet i samme manifest som ikke er en map |
Kun gjennom målet sitt | Plattformen kjører målet én gang per element og samler resultatene |
Ingen av modellnivåene navngir en leverandør eller en modell. Ruteren velger begge fra den utsendende organisasjonens egen ressursgruppe. Et verktøy i en tool_using-ferdighet navngir én av seks utførere: standing_service_call (din egen Service), graphrag, graphrag_query, graphrag_search, h3 eller web_search. Alle andre avvises med EXECUTOR_NOT_PERMITTED. De tre utførerne for kunnskapsgrafer godtar kun verktøynavnene graphrag_query og graphrag_search, fordi utføreren kjører den operasjonen verktøyet er oppkalt etter.
Det finnes to nivåer i registeret som en utvidelse ikke kan deklarere: Kjeder (chains) og ferdigheter som kjører på egen hånd, skrives kun av plattformen. En synkronisering som navngir en av disse, avvises i sin helhet.
Hvilket nivå du bør bruke
host_callbacknår arbeidet er en funksjon av inndataene som din egen kode beregner: en poengsum, en utregning, et oppslag i ditt eget skjema. Det er det enkleste å teste og malens standard. Beskytt tilbakekallingsruten: En sti i et manifest er ikke en hemmelighet, og ruten må verifisere plattformens kall og hente organisasjonen fra det, aldri fra meldingskroppen. Deklarer den somauth: internalog monterrequireService(Fastify) ellerserviceMiddleware(Express) på den. Vakten avviser et token som er utstedt for noen andre. Svar raskt, og gjør en eventuell andre levering av samme jobb harmløs.plugin_queuefor lengre arbeid som en person venter på, der arbeidsprosessen din eier livssyklusen. Arbeidsprosessen må flytte kjøringen tilrunningnår den starter, og til en sluttstatus når den er ferdig; en arbeidsprosess som kun poster resultatet sitt, lar kjøringen bli stående somqueuedfor alltid.llm_onlynår ett modellkall med en fast systeminstruks (system prompt) gjør jobben, og utvidelsen din ercoreellerverified.tool_usingnår modellen må kalle verktøy i en løkke, igjen kun vedcoreellerverified.mapnår du vil at plattformen skal spre en av de andre ferdighetene dine ut over en liste.
Ferdigheten min for banepropagering hos Corrán Orbital er en host_callback. Utvidelsen vår er community, så modellnivåene var aldri et alternativ, og jeg savner dem ikke: En propagator som ga et annet svar på tirsdag, ville vært verre enn ubrukelig.
Godkjenning før hver kjøring
En manifestferdighet som aldri må kjøre kun på en maskins avgjørelse alene, deklarerer dette:
"approval": { "required": true, "reason": "Re-planning a pass needs the flight dynamics lead." }required er alltid true; en ferdighet som ikke krever godkjenning, utelater blokken. reason er det godkjenneren ser, 1 til 500 tegn etter trimming, og enhver annen form avvises med APPROVAL_INVALID. En utsendelse av ferdigheten holdes deretter tilbake: Utsendelsen svarer 202 med status: "awaiting_approval" og en waitpointId, og kun en navngitt persons godkjenning frigir den, én gang. En batch-, map- eller kjedeutsendelse av en tilbakeholdt ferdighet avvises med SKILL_APPROVAL_NOT_HOLDABLE, fordi en utspredning (fan-out) ikke kan holde tilbake enkeltelementene sine. Vis det tilbakeholdte svaret og la godkjenneren avgjøre; ikke send ut for deretter å be om samtykke.
Synkronisering til registeret
Hver synkronisering er deklarativ og kontrolleres som en helhet. Send hele ferdighetssettet hver gang: En ferdighet du utelater, deaktiveres, og kjøringshistorikken dens blir værende. Én ugyldig ferdighet avviser hele synkroniseringen med SYNC_CONTRACT_VIOLATION, der alle brudd listes opp samlet og ingenting skrives, slik at en utvidelse aldri blir halvveis oppdatert. Kapittel 2.22, Kjøretidsmiljøet for utvidelser, dekker synkroniseringskallet og hvordan plattformen vet hvilken utvidelse som kaller.
Velge mellom de to typene
Hvis jobben er «si dette på samme måte hver gang», er det en ferdighet i Skills Engine. Hvis jobben er «kjør koden min og gi meg svaret», er det en manifestferdighet. Det meste av reelt arbeid ender opp som begge deler: Harrows kaisammendrag er en ferdighet i Skills Engine der verktøyene kommer fra en utvidelse, og utvidelsens verktøy er selv deklarert i dens manifest. Ferdigheten i Skills Engine er den rimeligste av de to å endre, noe som er en god grunn til å beholde ordlyden og skjønnsutøvelsen der, og aritmetikken i utvidelsen.
Kostnaden er reell uansett. En ferdighet i Skills Engine er ikke ferdig når SKILL.md ser bra ut; den er ferdig når testtilfellene er bestått, prøvekjøringen samsvarer med det folk bestemte, og noen andre enn deg har godkjent den. Sett av en uke for en ferdighet som skriver, det meste av tiden til kanarikjøringen.



