Version 1.0.0-alpha.1seneste
Kapitel 2.20
Færdigheder
Hvordan man skriver, tester og udgiver en Skills Engine-færdighed, hvor den vises, når den er aktiv, og hvordan manifestfærdigheder i et plugin adskiller sig. Indeholder en gennemarbejdet oversigt over kajpladstildeling for Harrow Port Authority.
Denne side er oversat af AI fra den engelske original. Hvis noget er uklart, er den engelske side gældende. Læs denne side på engelsk

Tomás Reilly, platformsingeniøren hos Harrow Port Authority, spurgte mig i sidste måned, hvorfor hans kajplanlæggere fik et forskelligt svar, hver gang de spurgte assistenten "hvem ligger på hvilken kaj i morgen, og hvad er flyttet?". Svaret var, at ingen havde fortalt assistenten, hvordan et godt svar ser ud. En færdighed i Skills Engine løste det på en eftermiddag: planlæggerne får nu det samme tredelte resumé hver gang, med kajtabellen først, ændringerne siden den sidste plan nedenunder og konflikterne til sidst. Dette kapitel gennemgår den færdighed fra ende til anden og dækker derefter den anden slags færdighed – den, der ligger i et plugins manifest.
To slags færdigheder
Nexus bruger ordet "skill" (færdighed) om to forskellige ting, og de er bygget forskelligt.
| Skills Engine-færdighed | Manifest-færdighed | |
|---|---|---|
| Hvad det er | En SKILL.md-pakke i færdighedsbiblioteket |
En typet række i et plugins skills[]-array |
| Hvem skriver den | Alle med rettigheden, i oprettelsesværktøjet eller deres egen editor | En udvikler, inde i et plugin |
| Hvad den indeholder | Instruktioner, de værktøjer den må kalde, valgfrie filer og scripts | Et input- og outputskema, et niveau (tier) og de felter, som det niveau kræver |
| Hvordan den når platformen | Valideret, uploadet og publiceret til Skills Engine | Kompileret fra manifestet og synkroniseret til færdighedsregistret |
| Hvad kører den | Assistenten, agenter, workflows, AI-knapper (kunstig intelligens), Claude Code | UNO-afsendelse (workflowmotoren) |
| Typisk brug | "Opsummer kajplanen på samme måde hver gang" | "Kør vores kredsløbspropagator på denne passage" |
Resten af kapitlet holder dem adskilt. Hvis et afsnit blot nævner "færdighed" alene, er det en Skills Engine-færdighed.
Del 1: Skills Engine-færdigheder
Hvad en færdighed er
En færdighed er en mappe. Dens SKILL.md fortæller, hvad færdigheden er til for, og hvordan opgaven udføres; ved siden af den ligger eventuelle filer, som opgaven har brug for, og eventuelle scripts, den kører. Motoren indlæser en færdighed i tre lag: navnet og beskrivelsen indlæses altid, instruktionerne indlæses, når en opgave kalder på færdigheden, og filerne indlæses kun, når et trin har brug for dem. Det er grunden til, at en installation kan rumme to hundrede færdigheder og næsten intet betale for dem, før en af dem tages i brug.
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 skal være lig med færdighedens slug. En uoverensstemmelse udløser en valideringsadvarsel, og den er værd at rette, fordi dette slug er måden, hvorpå biblioteket matcher et upload med en eksisterende færdighed.
SKILL.md frontmatter
Frontmatter er YAML mellem to ----linjer øverst i filen. Formatet kræver tre felter. Selve valideringen blokerer kun på få ting: et manglende navn eller en manglende beskrivelse samt et slug eller en jobtype, der allerede er optaget. Alt andet rapporterer den som en advarsel.
| Felt | Type | Påkrævet | Hvad den indeholder |
|---|---|---|---|
name |
streng | ja | Den unikke identifikator, i kebab-case |
description |
streng | ja | Hvad færdigheden gør, højst 500 tegn. Biblioteket og matcheren læser den, så skriv den til en læser, der skal afgøre, om dette er den rette færdighed |
allowed-tools |
streng eller liste | ja | De værktøjer, færdigheden må kalde. Den kan kun indsnævre tilladelseslisten (allow-list) for den, der kører den |
triggers |
liste | nej | Skråstregskommandoer (slash commands), der kalder færdigheden direkte |
capabilities |
liste | nej | Strukturerede kapabiliteter, hver med et name, en description og valgfrit input_schema, output_schema og examples |
version |
streng | nej | En semantisk version; 1.0.0 hvis udeladt |
visibility |
streng | nej | private, team eller public |
status |
streng | nej | draft, testing eller published |
Hold instruktionerne under cirka 5.000 tokens. Vær specifik og giv eksempler. Hver færdighed bør udføre én opgave godt; hvis De tager Dem selv i at skrive "og desuden", har De sandsynligvis to færdigheder.
skill.yaml
skill.yaml indeholder det, motoren skal bruge til fremsøgning og biblioteket, så SKILL.md forbliver læsbar. De felter, motoren læser, omfatter name, display_name, description, version, status, visibility, triggers, aliases, category, tags, allowed_tools og capabilities. En kapabilitet kan indeholde query_patterns, som er de formuleringer, matcheren skal sende til den. Der er også vink til motorens egen budgettering: complexity, estimated_tokens og required_services.
scripts/
Alt under scripts/ pakkes ordret sammen med færdigheden som en komponent. Et script køres, det læses aldrig ind i modellens kontekst, og det kører i en sandkasse (sandbox). Brug et, når et trin består af aritmetik eller parsning, som en model ikke bør udføre i hovedet.
Synlighed og status
Synlighed angiver, hvem der kan finde færdigheden: private er Dem, team er Deres team, og public er alle i den organisation, som biblioteket betjener. I konsollen hedder det samme valg "Kun mig", et team såsom "Toldkontor" eller hele organisationen, og en færdighed kan også deles ind i en domænepakke gennem den pågældende pakkes egen gennemgang.
Status angiver, hvor færdigheden befinder sig i sin livscyklus.
| Status | Betydning |
|---|---|
draft |
Under udarbejdelse; kan ikke fremsøges |
testing |
Under validering, med begrænset adgang |
published |
Tilgængelig til almindelig brug |
deprecated |
Erstattet; på vej til udfasning |
Når en version først er publiceret, ændres den aldrig. I konsollen er "live", "canary" og "shadow" mærkater på versioner, og når man skifter tilbage til en tidligere version, flyttes en mærkat. Igangværende kørsler afsluttes på den version, de startede med.
SKILL.md, filerne ved siden af den og hvornår hver enkelt indlæses, samt de værktøjer, færdigheden må kalde. En kontrollerende færdighed tilbydes intet værktøj, der skriver, og en færdighed kan kun indsnævre den kørende brugers tilladelsesliste.Fra en mappe til en færdighed i drift
Fem npm-scripts i Skills Engines kodelager (repository) fører en færdighed fra Deres editor til biblioteket og beviser, at den er nået frem.
| Kommando | Hvad den gør |
|---|---|
npm run skill:validate skills/<slug> |
Kontrollerer (linter) pakken. Publicering kræver nul fejl |
npm run skill:upload skills/<slug> |
Validerer og publicerer i ét trin; idempotent |
npm run skill:upload skills/<slug> --dry-run |
Validerer og udskriver planen uden at skrive noget |
npm run skill:publish -- --dry-run skills/<slug> |
Den lavere liggende publicering bag upload, samme pipeline |
npm run skill:reconcile |
Sammenligner færdighederne i Deres kodelager med det, som biblioteket og færdighedsregistret indeholder |
npm run skill:live:verify |
Kontrollerer en publiceret færdighed fra ende til anden på den kørende installation |
Publicering skriver to poster, og begge er vigtige. Den ene er selve færdigheden med dens SKILL.md-indhold, kapabiliteter, komponenter og kvalitetsregistrering; det er den, biblioteket, fremsøgningen og matchningen læser. Den anden er den registerpost, som workflowmotoren slår en afsendelse op imod. En færdighed, der kun er nået til registret, kan køre, men den er usynlig i biblioteket, indtil De uploader den.
Publicering er idempotent. En uændret færdighed udløser ingen handling (no-op), og en eksisterende færdighed matches via sit slug og opdateres på stedet – den genskabes aldrig. Hvis De uploader de samme bytes som en version, der allerede er publiceret, får De den pågældende version tilbage med CONTENT_HASH_ALREADY_PUBLISHED, ikke en dublet.
skill:reconcile gennemgår færdighederne i Deres kodelager op imod biblioteket, registret og workflowmotorens beholdning og rapporterer alt, hvad der findes ét sted og ikke et andet. skill:live:verify går skridtet videre på den kørende installation: begge poster findes og peger på hinanden med den samme indholds-hash, en prøveafsendelse (dry-run) af færdighedens jobtype accepteres, færdigheden vises i bibliotekslisten og detaljevisningen, den kan kaldes, og revisionssporet (audit trail) knytter publiceringen, afsendelsen og kørslen sammen via slug og anmodnings-id.
Fra en arbejdsstation når uploadet installationens videnstjeneste, nexus-graphrag, gennem en port-forward, og det kræver Skills Engines tjenestenøgle i miljøet. Indlæs nøglen uden at udskrive den på skærmen:
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-summaryInde i klyngen, i et pipeline-job, opløses standardadressen af sig selv, og GRAPHRAG_URL er ikke nødvendig. Hent nøglen gennem Deres organisations egen proces for hemmeligheder (secrets). Den må aldrig havne i kodelageret, i Deres kommandohistorik eller i en kommandos output.
Test, godkendelse og idriftsættelse
En færdighed når biblioteket som en kladde, og oprettelsesværktøjet fastholder den dér, indtil tre ting er bestået.
| Kontrol | Hvad den gør |
|---|---|
| Testcases | Hver eneste case skal bestås, før færdigheden kan sendes til godkendelse. En case kan kun fjernes med en begrundelse, som godkenderne kan se. |
| En prøvekørsel i shadow | Færdigheden kører på tidligere arbejde, hvor ingen ser svarene, og dens resultater sammenlignes med det, en person besluttede på daværende tidspunkt. |
| En blind gennemgang foretaget af en model fra en anden familie | Den leder efter en overset kontrol, en opdigtet kilde og en plantet instruktion, som færdigheden fulgte, selvom den ikke burde have gjort det. |
Derefter følger godkendelse. En færdighed, der tilføjer et værktøj, som skriver, tilbageholdes, indtil to personer godkender den med deres adgangsnøgler (passkeys), og den person, der foreslog den, må ikke være en af dem (PUBLISH_NEEDS_APPROVAL). Derefter sættes den i drift i shadow, dernæst i canary for én enhed bag navngivne kontrolpunkter (gates) og derefter for alle. Hvis et canary-kontrolpunkt ikke opfyldes, stopper canary-udrulningen sig selv, og alle forbliver på den forrige version; at sende den ud til alle før tid kræver en begrundelse og en anden godkender (CANARY_GATE_NOT_MET).
På Community er oprettelsesværktøjet, biblioteket, versioner og test alle til stede, og ejeren publicerer alene, når testene er bestået. Canary, topersonersgodkendelse, pluginsynkronisering og sammenlægning af dubletter følger med Enterprise.
Hvor færdigheder dukker op
Den samme publicerede færdighed når ud til brugerne fem steder.
- Assistenten matcher en anmodning med en færdighed ud fra dens beskrivelse, udløsere (triggers) og forespørgselsmønstre og følger færdighedens instruktioner.
- Agenter og workflows kalder færdigheder som trin. Et workflowtrin navngiver færdigheden; kørslen registrerer, hvilken version den brugte.
- AI-knapper på skærmbilleder kører hver især én færdighed. En administrator kan åbne "Om denne knap" for at se, hvilken færdighed en knap kører, hvad den læser, og hvem der senest har ændret den, og vedkommende kan slå knappen fra uden at røre ved selve færdigheden.
- Deres IDE (integrerede udviklingsmiljø) og Claude Code tilgår biblioteket gennem Workbench og tretten MCP-værktøjer (Model Context Protocol): heriblandt
list_skills,get_skill,match_prompt,discover_skills,invoke_skill,record_execution,create_skill,import_skill,get_generation_jobogsync_skills_local. Hvert kald kører som den person, der startede det, inden for vedkommendes tilladelsesliste. - Selve færdighedsbiblioteket, hvor folk gennemser, kører og foreslår ændringer til færdigheder, og hvor administratorer kan se hver færdigheds ejer, brugere, kørsler og forbrug.
Uanset hvad der kører en færdighed, kan færdigheden ikke udvide, hvad den kørende bruger har tilladelse til: den kalder kun værktøjer inden for brugerens tilladelsesliste og læser kun det, som den pågældende person må åbne (SKILL_CANNOT_WIDEN_TOOLS). En kørsel uden en modelrute afvises frem for at blive gættet (SKILLS_ENGINE_BINDING_MISSING); afsenderen (dispatcher) vælger ruten ud fra organisationens egen modelopsætning.
Gennemgået eksempel: et resumé af kajallokering for Harrow
Harrows planlæggere havde allerede to skrivebeskyttede værktøjer på deres tilladelsesliste fra Harrows eget kajplanlægnings-plugin: berth-plan.read returnerer planen for en dato, og vessel-call.read returnerer et skibsanløb med dets ankomstvindue og længde. Færdigheden behøver intet andet. Den skriver aldrig, så den behøver aldrig to godkendere.
---
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.Filen skill.yaml ved siden af giver biblioteket et visningsnavn, en kategori og de formuleringer, som matcheren skal dirigere hertil:
# 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 *"Derefter kommandoerne, fra kodelagerets rodmappe:
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 tilføjede seks testcases i oprettelsesværktøjet: en almindelig dag, en dag med en forsinket ankomst, der flyttede to anløb, en dag med en reel konflikt, en dato hvor der endnu ikke forelå en plan, et skib der var for langt til sin kaj, og en anmodning der forsøgte at få færdigheden til at foreslå en ny kaj (det bør den ikke; den har intet værktøj, der skriver). Prøvekørslen genafspillede tyve tidligere planer i shadow. Da testcasene var bestået, godkendte en kontrollant ved planlægningsbordet den, og den blev sat i drift for planlægningsteamet. Assistenten besvarer nu spørgsmålet i samme form hver gang, og planlæggernes AI-knap på kajplansiden kører den samme færdighed.
Del 2: manifestfærdigheder
En manifest-færdighed er den beregningsenhed, et plugin publicerer. Den erklæres i manifestets skills[], valideres af SDK'et (softwareudviklingssættet), når De kører create-nexus-plugin validate, kompileres ind i registerindholdet af compileRegistry og synkroniseres til færdighedsregistret. De skriver aldrig register-SQL i hånden, så den række, platformen afsender, og den deskriptor, De har erklæret, kan ikke glide fra hinanden.
Hver manifest-færdighed kræver id, displayName, description, tier, classification, inputSchema og outputSchema. Erklær også timeoutMs: det er et heltal fra 1.000 til 21.600.000 (ét sekund til seks timer), og en værdi uden for dette interval afvises med TIMEOUT_OUT_OF_BOUNDS. dataResidency er any, eu eller us, og any er standardværdien.
id skrives i lower_snake, og registrets afsendelsesnøgle er den navnerumsopdelte (namespaced) jobtype <plugin name>.<skill id>, så to plugins begge kan have en summarise-færdighed uden at kollidere. Her er skabelonens ene færdighed, beskåret:
{
"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 niveauer
Niveauet (tier) er ikke blot en mærkat. Hvert niveau har sine egne felter, og et felt, der tilhører et andet niveau, afvises med FIELD_NOT_FOR_TIER frem for blot at blive ignoreret i stilhed.
| Niveau | Kræver | Tilgår en model | Hvem kører den |
|---|---|---|---|
host_callback |
hostCallback: Deres Service, dens port, en sti og begge bytegrænser |
Nej | Platformen sender inputtet med POST til Deres egen Service, inde i Deres navnerum (namespace) |
plugin_queue |
queueName, stavet <plugin name>.<name> |
Nej | Deres worker, der trækker fra Deres kø |
tool_using |
systemPrompt og tools[]; tillidsniveau core eller verified |
Ja | Platformen, gennem AI Provider Router; hvert værktøjskald kører gennem en godkendt (allowlisted) executor |
llm_only |
systemPrompt; tillidsniveau core eller verified |
Ja | Platformen, ét kald gennem AI Provider Router |
map |
map.perItemJobType, der navngiver en anden færdighed i det samme manifest, som ikke er en map |
Kun gennem sit mål (target) | Platformen kører målet én gang pr. element og samler resultaterne |
Ingen af modelniveauerne navngiver en udbyder eller en model. Routeren vælger begge dele fra den afsendende organisations egen pulje. Et værktøj i en tool_using-færdighed navngiver en af seks executors: standing_service_call (Deres egen Service), graphrag, graphrag_query, graphrag_search, h3 eller web_search. Enhver anden afvises med EXECUTOR_NOT_PERMITTED. De tre vidensgraf-executors accepterer kun værktøjsnavnene graphrag_query og graphrag_search, fordi executoren kører den operation, som værktøjet er opkaldt efter.
Der findes to niveauer i registret, som et plugin ikke kan erklære: kæder (chains) og færdigheder, der kører af sig selv, skrives udelukkende af platformen. En synkronisering, der navngiver en af disse, afvises i sin helhed.
Hvilket niveau man skal bruge
host_callback, når arbejdet er en funktion af det input, som Deres egen kode beregner: en score, en udregning, et opslag i Deres eget skema. Det er det enkleste at teste og skabelonens standard. Beskyt callback-ruten: en sti i et manifest er ikke en hemmelighed, og ruten skal verificere platformens kald og hente organisationen derfra, aldrig fra selve beskedkroppen (body). Erklær den somauth: internalog monterrequireService(Fastify) ellerserviceMiddleware(Express) på den. Vagten (guard) afviser et token, der er udstedt til nogen anden. Svar hurtigt, og sørg for, at en eventuel anden levering af det samme job er harmløs.plugin_queuetil længerevarende arbejde, som en person venter på, hvor Deres worker ejer livscyklussen. Workeren skal flytte kørslen tilrunning, når den starter, og til en afsluttende status, når den er færdig; en worker, der blot indsender sit resultat, efterlader kørslen med visningenqueuedfor evigt.llm_only, når ét modelkald med en fast systemprompt klarer opgaven, og Deres plugin ercoreellerverified.tool_using, når modellen har brug for at kalde værktøjer i en løkke, igen kun vedcoreellerverified.map, når De ønsker, at platformen skal sprede (fan out) en af Deres andre færdigheder ud over en liste.
Min færdighed til kredsløbspropagering hos Corrán Orbital er en host_callback. Vores plugin er community, så modelniveauerne var aldrig en mulighed, og jeg savner dem ikke: en propagator, der gav et andet svar om tirsdagen, ville være værre end ubrugelig.
Godkendelse før hver kørsel
En manifest-færdighed, der aldrig må køre alene på en maskines foranledning, erklærer det således:
"approval": { "required": true, "reason": "Re-planning a pass needs the flight dynamics lead." }required er altid true; en færdighed, der ikke kræver godkendelse, udelader blokken. reason er det, godkenderen ser, 1 til 500 tegn efter trimning, og enhver anden form afvises med APPROVAL_INVALID. En afsendelse af færdigheden tilbageholdes derefter: afsendelsen svarer 202 med status: "awaiting_approval" og et waitpointId, og kun en navngiven persons godkendelse frigiver den, én gang. En batch-, map- eller kædeafsendelse af en tilbageholdt færdighed afvises med SKILL_APPROVAL_NOT_HOLDABLE, fordi en spredning (fan-out) ikke kan tilbageholde sine elementer. Vis det tilbageholdte svar og lad godkenderen træffe afgørelse; send ikke afsted for bagefter at bede om samtykke.
Synkronisering til registret
Hver synkronisering er deklarativ og kontrolleres i sin helhed. Send det fulde sæt af færdigheder hver gang: en færdighed, De udelader, deaktiveres, mens dens kørselshistorik bevares. Én fejlbehæftet færdighed afviser hele synkroniseringen med SYNC_CONTRACT_VIOLATION, hvor alle overtrædelser oplistes samlet, og intet skrives, så et plugin aldrig bliver halvt opdateret. Kapitel 2.22, Plugin-afviklingsmiljøet (The plugin runtime), dækker synkroniseringskaldet, og hvordan platformen ved, hvilket plugin der kalder.
Valg mellem de to slags
Hvis opgaven lyder "sig dette på samme måde hver gang", er det en Skills Engine-færdighed. Hvis opgaven lyder "kør min kode og giv mig dens svar", er det en manifest-færdighed. Det meste reelle arbejde ender med at være begge dele: Harrows kajresumé er en Skills Engine-færdighed, hvis værktøjer kommer fra et plugin, og pluginets værktøjer er selv erklæret i dets manifest. Skills Engine-færdigheden er den billigste af de to at ændre, hvilket er en god grund til at beholde ordlyden og vurderingen dér og lade aritmetikken ligge i pluginet.
Omkostningen er reel uanset hvad. En Skills Engine-færdighed er ikke færdig, når SKILL.md er velskrevet; den er færdig, når dens testcases er bestået, dens prøvekørsel stemmer overens med det, folk besluttede, og en person, der ikke er Dem, har godkendt den. Afsæt en uge til en færdighed, der skriver – størstedelen af tiden går med canary-udrulningen.



