Logga inBoka en genomgång

Kapitel 2.20

Färdigheter

Hur man skriver, testar och publicerar en Skills Engine-färdighet, var den visas när den är i drift och hur manifestfärdigheter i ett insticksprogram skiljer sig åt. Inkluderar en genomarbetad sammanfattning av kajplatstilldelning för Harrow Port Authority.

Denna sida har översatts av AI från det engelska originalet. Om något är oklart är den engelska sidan referensen. Läs denna sida på engelska

17 minuters läsning

Tomás Reilly, plattformsingenjören på Harrow Port Authority, frågade mig förra månaden varför hans kajplanerare fick olika svar varje gång de frågade assistenten "vem ligger vid vilken kaj imorgon, och vad har flyttats?". Svaret var att ingen hade talat om för assistenten hur ett bra svar ser ut. En färdighet i Skills Engine löste det på en eftermiddag: planerarna får nu samma tredelade sammanfattning varje gång, med kajtabellen först, ändringarna sedan den senaste planen därunder och konflikterna sist. Det här kapitlet går igenom den färdigheten från början till slut och tar sedan upp den andra typen av färdighet, den som finns i ett insticksprograms manifest.

Två typer av färdigheter

Nexus använder ordet "färdighet" (skill) för två olika saker, och de är uppbyggda på olika sätt.

Skills Engine-färdighet Manifestfärdighet
Vad det är Ett SKILL.md-paket i färdighetsbiblioteket En typad rad i ett insticksprograms skills[]-fält
Vem som skriver den Alla med behörighet, i skaparen eller i sin egen redigerare En utvecklare, inuti ett insticksprogram
Vad den innehåller Instruktioner, de verktyg den får anropa, valfria filer och skript Ett in- och utdataschema, en nivå och de fält som den nivån behöver
Hur den når plattformen Valideras, laddas upp och publiceras till Skills Engine Kompileras från manifestet och synkroniseras till färdighetsregistret
Vad som kör den Assistenten, agenter, arbetsflöden, AI-knappar (artificiell intelligens), Claude Code UNO-anrop (arbetsflödesmotorn)
Typisk användning "Sammanfatta kajplanen på samma sätt varje gång" "Kör vår omloppsbanpropagator på den här passagen"

Resten av kapitlet håller isär dem. Om ett stycke nämner "färdighet" utan närmare bestämning avses en färdighet i Skills Engine.

Del 1: Skills Engine-färdigheter

Vad en färdighet är

En färdighet är en mapp. Dess SKILL.md anger vad färdigheten är till för och hur arbetet ska utföras; bredvid den ligger eventuella filer som arbetet behöver och skript som den kör. Motorn läser in en färdighet i tre lager: namn och beskrivning läses alltid in, instruktionerna läses in när en uppgift kräver färdigheten och filerna endast när ett steg behöver dem. Det är därför en installation kan rymma tvåhundra färdigheter och knappt kosta någonting för dem förrän en av dem används.

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

Katalognamnet måste vara identiskt med färdighetens slug. Om de inte stämmer överens ger det en valideringsvarning, och det är värt att åtgärda eftersom denna slug är hur biblioteket matchar en uppladdning mot en befintlig färdighet.

SKILL.md frontmatter

Frontmatter är YAML mellan två ----rader högst upp i filen. Formatet kräver tre fält. Själva valideringen blockerar bara vid ett fåtal saker: ett saknat namn eller en saknad beskrivning, samt en slug eller jobbtyp som redan är upptagen. Allt annat rapporteras som en varning.

Fält Typ Obligatoriskt Vad den innehåller
name sträng ja Den unika identifieraren, i kebab-case
description sträng ja Vad färdigheten gör, högst 500 tecken. Biblioteket och matcharen läser den, så skriv den för en läsare som ska avgöra om det här är rätt färdighet
allowed-tools sträng eller lista ja De verktyg som färdigheten får anropa. Den kan bara begränsa tillåtelselistan för den som kör den
triggers lista nej Snedstreckskommandon som anropar färdigheten direkt
capabilities lista nej Strukturerade förmågor, var och en med name, description och valfritt input_schema, output_schema och examples
version sträng nej En semantisk version; 1.0.0 när den utelämnas
visibility sträng nej private, team eller public
status sträng nej draft, testing eller published

Håll instruktionerna under cirka 5 000 tokens. Var specifik och ge exempel. Varje färdighet bör göra ett jobb bra; om ni märker att ni skriver "och dessutom" har ni förmodligen två färdigheter.

skill.yaml

skill.yaml innehåller det som motorn behöver för identifiering och biblioteket, så att SKILL.md förblir läsbar. De fält som motorn läser inkluderar name, display_name, description, version, status, visibility, triggers, aliases, category, tags, allowed_tools och capabilities. En förmåga kan innehålla query_patterns, de formuleringar som matcharen ska skicka till den. Det finns också ledtrådar för motorns egen budgetering: complexity, estimated_tokens och required_services.

scripts/

Allt under scripts/ paketeras ordagrant med färdigheten som en komponent. Ett skript körs, läses aldrig in i modellens kontext, och det körs i en sandlåda. Använd ett skript när ett steg utgörs av aritmetik eller parsning som en modell inte bör göra i huvudet.

Synlighet och status

Synlighet anger vem som kan hitta färdigheten: private är ni, team är ert team och public är alla i organisationen som biblioteket betjänar. I konsolen lyder samma val "Endast jag", ett team som "Tullavdelningen" eller hela organisationen, och en färdighet kan också delas till ett domänpaket genom det paketets egen granskning.

Status anger var i livscykeln färdigheten befinner sig.

Status Betydelse
draft Pågående arbete; inte sökbar
testing Valideras, med begränsad åtkomst
published Tillgänglig för allmänt bruk
deprecated Ersatt; på väg att fasas ut

När en version väl har publicerats ändras den aldrig. I konsolen är "live", "canary" och "shadow" etiketter på versioner, och att byta tillbaka till en tidigare version flyttar en etikett. Pågående körningar slutförs på den version de startade med.

Ny färdighet · 2 Instruktioner och verktyg
Ny färdighet · 2 Instruktioner och verktyg
Skaparens andra steg visar utkastet SKILL.md, filerna bredvid det och när var och en läses in, samt de verktyg som färdigheten får anropa. En kontrollerande färdighet erbjuds inget verktyg som skriver, och en färdighet kan bara begränsa körarens tillåtelselista.

Från en mapp till en aktiv färdighet

Fem npm-skript i lagringsplatsen för Skills Engine tar en färdighet från er redigerare till biblioteket och bevisar att den har kommit fram.

Kommando Vad den gör
npm run skill:validate skills/<slug> Granskar (lintar) paketet. Publicering kräver noll fel
npm run skill:upload skills/<slug> Validerar och publicerar i ett steg; idempotent
npm run skill:upload skills/<slug> --dry-run Validerar och skriver ut planen utan att skriva något
npm run skill:publish -- --dry-run skills/<slug> Den underliggande publiceringen bakom uppladdning, samma pipeline
npm run skill:reconcile Jämför färdigheterna i er lagringsplats med vad biblioteket och färdighetsregistret innehåller
npm run skill:live:verify Kontrollerar en publicerad färdighet från början till slut på den körande installationen

Publicering skriver två poster, och båda är viktiga. Den ena är själva färdigheten, med dess SKILL.md-innehåll, förmågor, komponenter och kvalitetspost; biblioteket, identifieringen och matchningen läser den posten. Den andra är registerposten som arbetsflödesmotorn slår upp ett anrop mot. En färdighet som bara har nått registret går att köra, men den är osynlig i biblioteket tills ni laddar upp den.

Publicering är idempotent. En oförändrad färdighet gör ingenting (no-op), och en befintlig färdighet matchas via sin slug och uppdateras på plats, utan att någonsin återskapas. Om ni laddar upp samma byte som en version som redan är publicerad får ni tillbaka den versionen med CONTENT_HASH_ALREADY_PUBLISHED, inte en dubblett.

skill:reconcile går igenom färdigheterna i er lagringsplats mot biblioteket, registret och arbetsflödesmotorns inventarium, och rapporterar allt som finns på ett ställe men inte på ett annat. skill:live:verify går längre på den körande installationen: båda posterna finns och pekar på varandra med samma innehållshash, ett torrkörningsanrop av färdighetens jobbtyp accepteras, färdigheten visas i bibliotekslistan och detaljvyn, den kan anropas, och granskningsloggen knyter ihop publiceringen, anropet och körningen via slug och begärans-id.

Från en arbetsstation når uppladdningen installationens kunskapstjänst, nexus-graphrag, genom en port-forward, och den behöver tjänstenyckeln för Skills Engine i miljön. Läs in nyckeln utan att skriva ut 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-summary

Inuti klustret, i ett pipeline-jobb, slås standardadressen upp av sig själv och GRAPHRAG_URL behövs inte. Hämta nyckeln via er organisations egen process för hemligheter. Den ska aldrig hamna i lagringsplatsen, i er skalhistorik eller i utdata från ett kommando.

Tester, godkännande och driftsättning

En färdighet når biblioteket som ett utkast, och skaparen håller kvar den där tills tre saker har godkänts.

Kontroll Vad den gör
Testfall Varje fall måste godkännas innan färdigheten kan skickas för godkännande. Ett fall kan endast tas bort med en motivering, vilken godkännarna ser.
En torrkörning i skuggläge (shadow) Färdigheten körs på tidigare arbete, där ingen ser svaren, och dess resultat jämförs med vad en person beslutade vid den tidpunkten.
En blind granskning av en modell från en annan familj Den letar efter en missad kontroll, en påhittad källa och en planterad instruktion som färdigheten följde när den inte borde ha gjort det.

Därefter följer godkännande. En färdighet som lägger till ett verktyg som skriver hålls kvar tills två personer godkänner den med sina passkeys, och den person som föreslog den kan inte vara en av dem (PUBLISH_NEEDS_APPROVAL). Den går sedan live i skuggläge (shadow), därefter i canary-läge för en enhet bakom namngivna spärrar, och sedan för alla. Om en canary-spärr inte uppfylls stoppar canary-körningen sig själv och alla stannar kvar på den föregående versionen; att skicka ut den till alla i förtid kräver en motivering och en andra godkännare (CANARY_GATE_NOT_MET).

I Community finns skaparen, biblioteket, versionerna och testerna på plats, och ägaren publicerar på egen hand när testerna har godkänts. Canary, godkännande av två personer, synkronisering av insticksprogram och sammanslagning av dubbletter ingår i Enterprise.

Ny färdighet · 4 Publicera
Ny färdighet · 4 Publicera
Publicering visar varför en färdighet hålls kvar, vem som måste godkänna och hur den går live: godkänd, i skuggläge, i canary-läge bakom namngivna spärrar och sedan för alla. Förslagsställaren kan inte godkänna sin egen ändring, och den senaste versionen förblir redo att byta tillbaka till.

Var färdigheter dyker upp

Samma publicerade färdighet når användarna på fem ställen.

  1. Assistenten matchar en begäran mot en färdighet utifrån dess beskrivning, utlösare och frågemönster, och följer färdighetens instruktioner.
  2. Agenter och arbetsflöden anropar färdigheter som steg. Ett steg i ett arbetsflöde namnger färdigheten; körningen registrerar vilken version den använde.
  3. AI-knappar på skärmar kör var och en sin egen färdighet. En administratör kan öppna "Om den här knappen" för att se vilken färdighet en knapp kör, vad den läser och vem som senast ändrade den, och kan stänga av knappen utan att röra själva färdigheten.
  4. Er IDE (integrerad utvecklingsmiljö) och Claude Code når biblioteket genom Workbench och tretton MCP-verktyg (Model Context Protocol): däribland list_skills, get_skill, match_prompt, discover_skills, invoke_skill, record_execution, create_skill, import_skill, get_generation_job och sync_skills_local. Varje anrop körs som den person som startade det, inom dennes tillåtelselista.
  5. Färdighetsbiblioteket i sig, där användare bläddrar bland, kör och föreslår ändringar av färdigheter, och där administratörer ser varje färdighets ägare, användare, körningar och kostnader.

Oavsett vad som kör en färdighet kan färdigheten inte utvidga vad köraren får göra: den anropar endast verktyg inom körarens tillåtelselista och läser endast vad den personen har behörighet att öppna (SKILL_CANNOT_WIDEN_TOOLS). En körning utan en modellrutt nekas snarare än att gissas (SKILLS_ENGINE_BINDING_MISSING); anroparen väljer rutten från organisationens egen modellkonfiguration.

Om denna knapp
Om denna knapp
Om den här knappen visar vilken färdighet en AI-knapp kör, de tre källor den läser, vem som har skrivit och granskat den, samt vad den senaste versionen ändrade. Om knappen stängs av tas den bort överallt på en gång; färdigheten och alla tidigare svar finns kvar.

Praktiskt exempel: en sammanfattning av kajtilldelning för Harrow

Harrows planerare hade redan två skrivskyddade verktyg på sin tillåtelselista från Harrows eget insticksprogram för kajplanering: berth-plan.read returnerar planen för ett datum, och vessel-call.read returnerar ett fartygsanlöp med dess ankomstfönster och längd. Färdigheten behöver ingenting annat. Den skriver aldrig, så den behöver aldrig två godkännare.

---
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 bredvid den ger biblioteket ett visningsnamn, en kategori och de formuleringar som matcharen ska dirigera 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 *"

Sedan kommandona, från lagringsplatsens rot:

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-summary

Tomás lade till sex testfall i skaparen: en vanlig dag, en dag med en sen ankomst som flyttade två anlöp, en dag med en verklig konflikt, ett datum utan någon plan ännu, ett fartyg som var för långt för sin kaj, samt en begäran som försökte få färdigheten att föreslå en ny kaj (det ska den inte göra; den har inget verktyg som skriver). Torrkörningen spelade upp tjugo tidigare planer i skuggläge. När fallen hade godkänts godkände en granskare vid planeringsbordet den, och den gick live för planeringsteamet. Assistenten svarar nu på frågan i samma form varje gång, och planerarnas AI-knapp på sidan för kajplanen kör samma färdighet.

Del 2: manifestfärdigheter

En manifestfärdighet är den beräkningsenhet som ett insticksprogram publicerar. Den deklareras i manifestets skills[], valideras av SDK:t (programutvecklingskitet) när ni kör create-nexus-plugin validate, kompileras till registerinnehållet av compileRegistry och synkroniseras till färdighetsregistret. Ni skriver aldrig register-SQL för hand, så den rad som plattformen anropar och den beskrivning ni deklarerade kan inte glida isär.

Varje manifestfärdighet behöver id, displayName, description, tier, classification, inputSchema och outputSchema. Deklarera även timeoutMs: det är ett heltal från 1,000 till 21,600,000 (en sekund till sex timmar), och ett värde utanför det intervallet nekas med TIMEOUT_OUT_OF_BOUNDS. dataResidency är any, eu eller us, och any är standardvärdet.

id är i formatet lower_snake, och registrets anropsnyckel är den namnrymdsindelade jobbtypen <plugin name>.<skill id>, så att två insticksprogram båda kan ha en summarise-färdighet utan att kollidera. Här är mallens enda färdighet, nedkortad:

{
  "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åerna

Nivån är inte en etikett. Varje nivå har sina egna fält, och ett fält som tillhör en annan nivå nekas med FIELD_NOT_FOR_TIER i stället för att tyst ignoreras.

Nivå Kräver Når en modell Vem som kör den
host_callback hostCallback: er Service, dess port, en sökväg och båda bytegränserna Nej Plattformen skickar indata med POST till er egen Service, inuti er namnrymd
plugin_queue queueName, stavat <plugin name>.<name> Nej Er worker, som hämtar från er kö
tool_using systemPrompt och tools[]; förtroendenivå core eller verified Ja Plattformen, via AI Provider Router; varje verktygsanrop körs genom en tillåten exekverare
llm_only systemPrompt; förtroendenivå core eller verified Ja Plattformen, ett anrop via AI Provider Router
map map.perItemJobType, som namnger en annan färdighet i samma manifest som inte är en map Endast genom sitt mål Plattformen kör målet en gång per objekt och samlar in resultaten

Ingendera modellnivån namnger en leverantör eller en modell. Routern väljer båda från den anropande organisationens egen pool. Ett verktyg i en tool_using-färdighet namnger en av sex exekverare: standing_service_call (er egen Service), graphrag, graphrag_query, graphrag_search, h3 eller web_search. Alla andra nekas med EXECUTOR_NOT_PERMITTED. De tre kunskapsgraf-exekverarna accepterar endast verktygsnamnen graphrag_query och graphrag_search, eftersom exekveraren kör den åtgärd som verktyget är uppkallat efter.

Det finns två nivåer i registret som ett insticksprogram inte kan deklarera: kedjor och färdigheter som körs på egen hand skrivs endast av plattformen. En synkronisering som namnger en sådan nekas i sin helhet.

Vilken nivå som ska användas

  • host_callback när arbetet är en funktion av indata som er egen kod beräknar: en poäng, en beräkning, en slagning i ert eget schema. Den är enklast att testa och är mallens standardval. Skydda callback-rutten: en sökväg i ett manifest är inte en hemlighet, och rutten måste verifiera plattformens anrop och hämta organisationen därifrån, aldrig från meddelandekroppen. Deklarera den som auth: internal och montera requireService (Fastify) eller serviceMiddleware (Express) på den. Skyddet nekar en token som har utfärdats för någon annan. Svara snabbt och gör en andra leverans av samma jobb ofarlig.
  • plugin_queue för längre arbeten som en person väntar på, där er worker äger livscykeln. Workern måste flytta körningen till running när den startar och till en slutstatus när den är klar; en worker som bara skickar in sitt resultat lämnar körningen med statusen queued för alltid.
  • llm_only när ett modellanrop med en fast systemprompt gör jobbet, och ert insticksprogram har förtroendenivån core eller verified.
  • tool_using när modellen behöver anropa verktyg i en loop, återigen endast vid core eller verified.
  • map när ni vill att plattformen ska sprida ut (fan out) en av era andra färdigheter över en lista.

Min färdighet för omloppsbanpropagering på Corrán Orbital är en host_callback. Vårt insticksprogram är community, så modellnivåerna var aldrig ett alternativ, och jag saknar dem inte: en propagator som skulle ge ett annorlunda svar på tisdagen vore värre än värdelös.

Godkännande före varje körning

En manifestfärdighet som aldrig får köras enbart på en maskins begäran deklarerar detta:

"approval": { "required": true, "reason": "Re-planning a pass needs the flight dynamics lead." }

required är alltid true; en färdighet som inte behöver något godkännande utelämnar blocket. reason är vad godkännaren ser, 1 till 500 tecken efter trimning, och alla andra format nekas med APPROVAL_INVALID. Ett anrop av färdigheten hålls sedan kvar: anropet svarar 202 med status: "awaiting_approval" och ett waitpointId, och endast en namngiven persons godkännande släpper fram det, en gång. Ett batch-, map- eller kedjeanrop av en kvarhållen färdighet nekas med SKILL_APPROVAL_NOT_HOLDABLE, eftersom en utspridning (fan-out) inte kan hålla kvar sina objekt. Visa det kvarhållna svaret och låt godkännaren besluta; anropa inte först för att sedan be om samtycke.

Synkronisering till registret

Varje synkronisering är deklarativ och kontrolleras i sin helhet. Skicka hela uppsättningen färdigheter varje gång: en färdighet som ni utelämnar inaktiveras, men dess körningshistorik finns kvar. En enda felaktig färdighet nekar hela synkroniseringen med SYNC_CONTRACT_VIOLATION, där varje överträdelse listas tillsammans och ingenting skrivs, så att ett insticksprogram aldrig blir halvuppdaterat. Kapitel 2.22, Körmiljön för insticksprogram, behandlar synkroniseringsanropet och hur plattformen vet vilket insticksprogram som anropar.

Färdigheter i IDE:n och Claude Code
Färdigheter i din IDE och Claude Code
Färdigheter i IDE:n och Claude Code visar samma steg för validering, uppladdning och publicering från en utvecklares egen terminal, där utkastet hålls kvar för godkännande eftersom dess författare inte kan godkänna sin egen ändring.

Välja mellan de två typerna

Om uppgiften är "säg det här på samma sätt varje gång" är det en färdighet i Skills Engine. Om uppgiften är "kör min kod och ge mig svaret" är det en manifestfärdighet. Det mesta av det verkliga arbetet slutar som bådadera: Harrows kajsammanfattning är en färdighet i Skills Engine vars verktyg kommer från ett insticksprogram, och insticksprogrammets verktyg är i sin tur deklarerade i dess manifest. Färdigheten i Skills Engine är den billigare av de två att ändra, vilket är ett bra skäl att behålla formuleringarna och bedömningarna där och aritmetiken i insticksprogrammet.

Kostnaden är kännbar vilket som. En färdighet i Skills Engine är inte klar när dess SKILL.md är välskriven; den är klar när dess testfall godkänns, dess torrkörning stämmer överens med vad människor har beslutat och någon annan än ni själv har godkänt den. Budgetera en vecka för en färdighet som skriver, varav merparten utgörs av canary-fasen.