Prihlásiť saRezervovať brífing

Kapitola 2.20

Zručnosti (Skills)

Ako napísať, otestovať a publikovať zručnosť pre Skills Engine, kde sa zobrazí po nasadení a v čom sa líšia zručnosti v manifeste zásuvného modulu. Obsahuje vypracovaný príklad súhrnu prideľovania kotvísk pre spoločnosť Harrow Port Authority.

Táto stránka bola preložená pomocou AI z anglického originálu. V prípade akýchkoľvek nejasností je rozhodujúca anglická verzia stránky. Prečítať túto stránku v angličtine

17 min čítania

Tomás Reilly, platformový inžinier v spoločnosti Harrow Port Authority, sa ma minulý mesiac opýtal, prečo jeho plánovači kotvísk dostali zakaždým inú odpoveď, keď sa asistenta spýtali „kto je zajtra na ktorom kotvisku a čo sa presunulo?“. Odpoveďou bolo, že asistentovi nikto nepovedal, ako má dobrá odpoveď vyzerať. Zručnosť nástroja Skills Engine to vyriešila za jedno popoludnie: plánovači teraz dostávajú zakaždým rovnaké trojdielne zhrnutie, pričom na prvom mieste je tabuľka kotvísk, pod ňou zmeny od posledného plánu a na konci kolízie. Táto kapitola podrobne rozoberá túto zručnosť od začiatku do konca a následne sa venuje druhému druhu zručnosti – tej, ktorá sa nachádza v manifeste zásuvného modulu.

Dva druhy zručností

Nexus používa slovo „zručnosť“ (skill) pre dve rôzne veci, ktoré sú aj odlišne zostavené.

Zručnosť Skills Engine Zručnosť v manifeste
Čo to je Balík SKILL.md v knižnici zručností Typizovaný riadok v poli skills[] zásuvného modulu
Kto ju píše Ktokoľvek s oprávnením, v nástroji na tvorbu alebo vo vlastnom editore Vývojár, vo vnútri zásuvného modulu
Čo obsahuje Pokyny, nástroje, ktoré môže volať, voliteľné súbory a skripty Schému vstupu a výstupu, úroveň (tier) a polia, ktoré daná úroveň vyžaduje
Ako sa dostane na platformu Overená, nahraná a publikovaná do nástroja Skills Engine Skompilovaná z manifestu a synchronizovaná do registra zručností
Čo ju spúšťa Asistent, agenty, pracovné postupy, tlačidlá AI (umelej inteligencie), Claude Code Odoslanie cez UNO (nástroj pre pracovné postupy)
Typické použitie „Zhrň plán kotvísk zakaždým rovnakým spôsobom“ „Spusti náš propagátor obežnej dráhy pri tomto prelete“

Zvyšok kapitoly ich striktne odlišuje. Ak sa v odseku uvádza len samotné slovo „zručnosť“, ide o zručnosť nástroja Skills Engine.

Časť 1: zručnosti pre Skills Engine

Čo je to zručnosť

Zručnosť je priečinok. Jeho súbor SKILL.md hovorí, na čo zručnosť slúži a ako danú úlohu vykonať; vedľa neho sa nachádzajú všetky súbory, ktoré úloha potrebuje, a skripty, ktoré spúšťa. Nástroj načítava zručnosť v troch vrstvách: názov a popis vždy, pokyny vtedy, keď si úloha zručnosť vyžiada, a súbory len vtedy, keď ich potrebuje konkrétny krok. Preto môže inštalácia obsahovať dvesto zručností a neplatiť za ne takmer nič, až kým sa niektorá nepoužije.

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

Názov adresára sa musí zhodovať s identifikátorom (slug) zručnosti. Nezhoda vyvolá upozornenie pri validácii a oplatí sa ju opraviť, pretože podľa identifikátora slug knižnica priraďuje nahrávaný súbor k existujúcej zručnosti.

Úvodná časť (frontmatter) súboru SKILL.md

Úvodná časť (frontmatter) je kód YAML medzi dvoma riadkami --- v hornej časti súboru. Formát vyžaduje tri polia. Samotná validácia zablokuje proces len pri niekoľkých veciach: chýbajúcom názve alebo popise a identifikátore slug alebo type úlohy, ktoré sú už obsadené. Všetko ostatné hlási ako upozornenie.

Pole Typ Povinné Čo obsahuje
name reťazec áno Jedinečný identifikátor vo formáte kebab-case
description reťazec áno Čo zručnosť robí, maximálne 500 znakov. Číta to knižnica a párovací algoritmus (matcher), preto popis napíšte pre čitateľa, ktorý sa rozhoduje, či ide o tú správnu zručnosť
allowed-tools string alebo list áno Nástroje, ktoré môže zručnosť volať. Môže iba zúžiť zoznam povolených nástrojov (allow-list) toho, kto ju spúšťa
triggers list nie Príkazy s lomkou, ktoré priamo vyvolajú zručnosť
capabilities list nie Štruktúrované spôsobilosti (capabilities), každá s name, description a voliteľne input_schema, output_schema a examples
version reťazec nie Sémantická verzia; 1.0.0, ak je vynechaná
visibility reťazec nie private, team alebo public
status reťazec nie draft, testing alebo published

Pokyny udržujte v rozsahu do približne 5 000 tokenov. Buďte konkrétni a uvádzajte príklady. Každá zručnosť by mala robiť dobre jednu úlohu; ak sa pristihnete pri tom, že píšete „a tiež“, pravdepodobne máte dve zručnosti.

skill.yaml

Súbor skill.yaml nesie to, čo nástroj potrebuje na vyhľadávanie a pre knižnicu, aby súbor SKILL.md zostal čitateľný. Medzi polia, ktoré nástroj číta, patria name, display_name, description, version, status, visibility, triggers, aliases, category, tags, allowed_tools a capabilities. Spôsobilosť môže obsahovať query_patterns, čo sú formulácie, ktoré by jej mal párovací algoritmus posielať. Existujú aj pomôcky pre vlastné rozpočtovanie nástroja: complexity, estimated_tokens a required_services.

scripts/

Čokoľvek pod scripts/ sa pribalí presne tak, ako je, spolu so zručnosťou ako komponent. Skript sa spúšťa, nikdy sa nenačítava do kontextu modelu a beží v izolovanom prostredí (sandbox). Použite ho, keď krok predstavuje aritmetický výpočet alebo spracovanie textu (parsing), ktoré by model nemal robiť „z hlavy“.

Viditeľnosť a stav

Viditeľnosť určuje, kto môže zručnosť nájsť: private ste vy, team je váš tím a public je každý v organizácii, ktorej knižnica slúži. V konzole tá istá voľba znie „Iba ja“, tím ako napríklad „Colné oddelenie“ alebo celá organizácia, pričom zručnosť možno zdieľať aj do doménového balíka prostredníctvom vlastného schvaľovacieho procesu daného balíka.

Stav hovorí, v akej fáze životného cyklu sa zručnosť nachádza.

Stav Význam
draft Rozpracované; nevyhľadateľné
testing Prebieha validácia, s obmedzeným prístupom
published Dostupné na všeobecné použitie
deprecated Prekonané; na ceste k vyradeniu

Keď je verzia raz publikovaná, už sa nikdy nemení. V konzole sú „live“ (v prevádzke), „canary“ (kanárikové nasadenie) a „shadow“ (tieňové nasadenie) štítky na verziách a prepnutie späť na staršiu verziu iba presunie štítok. Práve prebiehajúce behy sa dokončia na verzii, s ktorou začali.

Nová zručnosť · 2 Pokyny a nástroje
Nová zručnosť · 2 Pokyny a nástroje
Druhý krok nástroja na tvorbu zobrazuje návrh SKILL.md, súbory vedľa neho a informáciu o tom, kedy sa každý z nich načíta, ako aj nástroje, ktoré môže zručnosť volať. Kontrolnej zručnosti sa neponúka žiadny nástroj, ktorý zapisuje, a zručnosť môže iba zúžiť zoznam povolených nástrojov spúšťača.

Od priečinka k zručnosti v prevádzke

Päť skriptov npm v repozitári nástroja Skills Engine prenesie zručnosť z vášho editora do knižnice a potvrdí, že tam dorazila.

Príkaz Čo robí
npm run skill:validate skills/<slug> Skontroluje balík (linting). Publikovanie vyžaduje nula chýb
npm run skill:upload skills/<slug> Overí a publikuje v jednom kroku; idempotentné
npm run skill:upload skills/<slug> --dry-run Overí a vypíše plán bez toho, aby čokoľvek zapísal
npm run skill:publish -- --dry-run skills/<slug> Publikovanie nižšej úrovne na pozadí nahrávania, rovnaký procesný reťazec (pipeline)
npm run skill:reconcile Porovná zručnosti vo vašom repozitári s tým, čo obsahuje knižnica a register zručností
npm run skill:live:verify Skontroluje publikovanú zručnosť od začiatku do konca na bežiacej inštalácii

Publikovanie zapíše dve položky a obe sú dôležité. Jednou je samotná zručnosť s telom SKILL.md, spôsobilosťami, komponentmi a záznamom o kvalite; túto položku číta knižnica, vyhľadávanie a párovanie. Druhou je položka v registri, voči ktorej nástroj pre pracovné postupy vyhodnocuje odoslanie (dispatch). Zručnosť, ktorá sa dostala iba do registra, síce funguje, ale v knižnici je neviditeľná, až kým ju nenahráte.

Publikovanie je idempotentné. Nezmenená zručnosť nevykoná žiadnu operáciu (no-op) a existujúca zručnosť sa spáruje podľa svojho identifikátora slug a aktualizuje sa na mieste, nikdy sa nevytvára nanovo. Ak nahráte tie isté bajty ako vo verzii, ktorá je už publikovaná, dostanete späť danú verziu s CONTENT_HASH_ALREADY_PUBLISHED, nie duplikát.

Príkaz skill:reconcile prejde zručnosti vášho repozitára a porovná ich s knižnicou, registrom a inventárom nástroja pre pracovné postupy a nahlási čokoľvek, čo existuje na jednom mieste, ale nie na druhom. Príkaz skill:live:verify ide na bežiacej inštalácii ešte ďalej: overí, že obe položky existujú a odkazujú na seba s rovnakým hašom obsahu, že nečinné (dry-run) odoslanie typu úlohy zručnosti je prijaté, že sa zručnosť zobrazuje v zozname a detaile knižnice, že ju možno vyvolať a že audítorská stopa spája publikovanie, odoslanie a samotný beh pomocou identifikátora slug a ID požiadavky.

Z pracovnej stanice sa nahrávanie dostane do znalostnej služby inštalácie, nexus-graphrag, cez presmerovanie portov (port-forward) a v prostredí vyžaduje servisný kľúč nástroja Skills Engine. Načítajte kľúč bez jeho vypísania na obrazovku:

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

Vo vnútri klastra, v úlohe procesného reťazca (pipeline), sa predvolená adresa preloží sama a GRAPHRAG_URL nie je potrebné. Získajte kľúč prostredníctvom vlastného procesu správy tajomstiev vo vašej organizácii. Nikdy nepatrí do repozitára, histórie vášho shellu ani do výstupu príkazu.

Testy, schválenie a uvedenie do prevádzky

Zručnosť sa dostane do knižnice ako návrh a nástroj na tvorbu ju tam podrží, kým neprejdú tri veci.

Kontrola Čo robí
Testovacie prípady Každý prípad musí prejsť predtým, ako môže ísť zručnosť na schválenie. Prípad možno odstrániť iba s uvedením dôvodu, ktorý schvaľovatelia uvidia.
Nečinný beh (dry run) v tieňovom režime Zručnosť sa spustí na minulej práci, kde nikto nevidí odpovede, a jej výsledky sa porovnajú s tým, ako sa v danom čase rozhodol človek.
Slepá kontrola modelom z inej rodiny Hľadá vynechanú kontrolu, vymyslený zdroj a podvrhnutý pokyn, ktorý zručnosť poslúchla, hoci nemala.

Potom nasleduje schválenie. Zručnosť, ktorá pridáva nástroj so zápisom, je pozdržaná, kým ju neschvália dvaja ľudia svojimi prístupovými kľúčmi (passkeys), pričom osoba, ktorá ju navrhla, nemôže byť jedným z nich (PUBLISH_NEEDS_APPROVAL). Následne prejde do prevádzky v tieňovom režime (shadow), potom v kanárikovom režime (canary) pre jednu jednotku za pomenovanými bránami a nakoniec pre všetkých. Ak kanáriková brána nie je splnená, kanárikový beh sa sám zastaví a všetci zostanú na predchádzajúcej verzii; jej predčasné odoslanie všetkým vyžaduje uvedenie dôvodu a druhého schvaľovateľa (CANARY_GATE_NOT_MET).

Vo verzii Community sú k dispozícii nástroj na tvorbu, knižnica, verzie aj testy a vlastník publikuje sám, len čo testy prejdú. Kanárikové nasadenie, schvaľovanie dvoma osobami, synchronizácia zásuvných modulov a zlučovanie duplikátov prichádzajú s verziou Enterprise.

Nová zručnosť · 4 Publikovanie
Nová zručnosť · 4 Publikovanie
Publikovanie ukazuje, prečo je zručnosť pozdržaná, kto musí súhlasiť a ako sa dostane do prevádzky: schválená, v tieňovom režime, v kanárikovom režime za pomenovanými bránami a potom pre všetkých. Navrhovateľ nemôže schváliť vlastnú zmenu a posledná verzia zostáva pripravená na prípadné prepnutie späť.

Kde sa zručnosti objavujú

Tá istá publikovaná zručnosť sa k ľuďom dostane na piatich miestach.

  1. Asistent spáruje požiadavku so zručnosťou podľa jej popisu, spúšťačov a vzorov dopytov a postupuje podľa pokynov zručnosti.
  2. Agenty a pracovné postupy volajú zručnosti ako jednotlivé kroky. Krok pracovného postupu menuje zručnosť; samotný beh zaznamená, ktorú verziu použil.
  3. Tlačidlá AI na obrazovkách spúšťajú každé jednu zručnosť. Správca môže otvoriť časť „O tomto tlačidle“, aby videl, ktorú zručnosť tlačidlo spúšťa, čo číta a kto ju naposledy zmenil, a môže tlačidlo vypnúť bez toho, aby sa dotkol samotnej zručnosti.
  4. Vaše IDE (integrované vývojové prostredie) a Claude Code pristupujú do knižnice cez Workbench a trinásť nástrojov MCP (Model Context Protocol): okrem iného list_skills, get_skill, match_prompt, discover_skills, invoke_skill, record_execution, create_skill, import_skill, get_generation_job a sync_skills_local. Každé volanie beží pod identitou osoby, ktorá ho spustila, v rámci jej zoznamu povolených nástrojov.
  5. Samotná knižnica zručností, kde ľudia prehliadajú, spúšťajú a navrhujú zmeny v zručnostiach a správcovia vidia vlastníka každej zručnosti, používateľov, behy a náklady.

Nech už zručnosť spúšťa čokoľvek, zručnosť nemôže rozšíriť oprávnenia toho, kto ju spúšťa: volá iba nástroje v rámci zoznamu povolených nástrojov spúšťača a číta iba to, čo môže daná osoba otvoriť (SKILL_CANNOT_WIDEN_TOOLS). Beh bez smerovania na model je odmietnutý namiesto toho, aby sa hádalo (SKILLS_ENGINE_BINDING_MISSING); smerovanie vyberá dispečer z vlastného nastavenia modelov organizácie.

O tomto tlačidle
O tomto tlačidle
Časť O tomto tlačidle zobrazuje zručnosť, ktorú tlačidlo AI spúšťa, tri zdroje, ktoré číta, kto ju napísal a skontroloval, a čo zmenila najnovšia verzia. Vypnutie tlačidla ho naraz odstráni odvšadiaľ; samotná zručnosť a každá minulá odpoveď zostávajú zachované.

Praktický príklad: zhrnutie pridelenia kotvísk pre Harrow

Plánovači v Harrow už mali vo svojom zozname povolených nástrojov dva nástroje iba na čítanie z vlastného zásuvného modulu Harrow na plánovanie kotvísk: berth-plan.read vráti plán na daný dátum a vessel-call.read vráti zastávku plavidla s jej oknom príchodu a dĺžkou. Zručnosť nepotrebuje nič iné. Nikdy nezapisuje, takže nikdy nepotrebuje dvoch schvaľovateľov.

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

Súbor skill.yaml vedľa nej dáva knižnici zobrazovaný názov, kategóriu a formulácie, ktoré by sem mal párovací algoritmus smerovať:

# 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 *"

Potom nasledujú príkazy z koreňového adresára repozitára:

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 pridal v nástroji na tvorbu šesť testovacích prípadov: bežný deň, deň s oneskoreným príchodom, ktorý presunul dve zastávky, deň so skutočnou kolíziou, dátum, pre ktorý ešte neexistuje plán, plavidlo príliš dlhé pre svoje kotvisko a požiadavku, ktorá sa snažila prinútiť zručnosť, aby navrhla nové kotvisko (nemala by to urobiť; nemá žiadny nástroj, ktorý zapisuje). Nečinný beh prehral v tieňovom režime dvadsať minulých plánov. Keď prípady prešli, kontrolór na plánovacom oddelení zručnosť schválil a tá prešla do prevádzky pre plánovací tím. Asistent teraz odpovedá na otázku zakaždým v rovnakom tvare a tlačidlo AI pre plánovačov na stránke plánu kotvísk spúšťa tú istú zručnosť.

Časť 2: zručnosti v manifeste

Zručnosť v manifeste je výpočtová jednotka, ktorú publikuje zásuvný modul. Je deklarovaná v skills[] manifestu, validovaná pomocou SDK (súpravy na vývoj softvéru), keď spustíte create-nexus-plugin validate, skompilovaná do tela registra príkazom compileRegistry a synchronizovaná do registra zručností. Nikdy nepíšete SQL pre register ručne, takže riadok, ktorý platforma odosiela, a deskriptor, ktorý ste deklarovali, sa nemôžu rozísť.

Každá zručnosť v manifeste potrebuje id, displayName, description, tier, classification, inputSchema a outputSchema. Deklarujte aj timeoutMs: je to celé číslo od 1 000 do 21 600 000 (jedna sekunda až šesť hodín) a hodnota mimo tohto rozsahu je odmietnutá s TIMEOUT_OUT_OF_BOUNDS. dataResidency je any, eu alebo us, pričom any je predvolená hodnota.

Hodnota id je vo formáte lower_snake a odosielacím kľúčom registra je typ úlohy s menným priestorom <plugin name>.<skill id>, takže dva zásuvné moduly môžu mať zručnosť summarise bez toho, aby došlo ku kolízii. Tu je jedna skrátená zručnosť zo šablóny:

{
  "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
}

Päť úrovní

Úroveň (tier) nie je len štítok. Každá úroveň má svoje vlastné polia a pole, ktoré patrí do inej úrovne, je odmietnuté s FIELD_NOT_FOR_TIER namiesto toho, aby bolo v tichosti zahodené.

Úroveň Vyžaduje Pristupuje k modelu Kto ju spúšťa
host_callback hostCallback: vaša služba (Service), jej port, cesta a oba limity v bajtoch Nie Platforma odošle vstup cez POST vašej vlastnej službe (Service) vo vašom mennom priestore
plugin_queue queueName, zapísané ako <plugin name>.<name> Nie Váš spracovateľ (worker), ktorý si ťahá úlohy z vášho radu (queue)
tool_using systemPrompt a tools[]; úroveň dôvery core alebo verified Áno Platforma, cez AI Provider Router; každé volanie nástroja beží cez exekútor zo zoznamu povolených
llm_only systemPrompt; úroveň dôvery core alebo verified Áno Platforma, jedno volanie cez AI Provider Router
map map.perItemJobType, pomenúvajúce inú zručnosť toho istého manifestu, ktorá nie je mapovaním (map) Iba cez svoj cieľ Platforma spustí cieľ raz pre každú položku a zozbiera výsledky

Žiadna z úrovní využívajúcich model nemenuje poskytovateľa ani model. Smerovač (router) vyberie oboje z vlastného fondu odosielajúcej organizácie. Nástroj v zručnosti tool_using menuje jeden zo šiestich exekútorov: standing_service_call (vaša vlastná služba Service), graphrag, graphrag_query, graphrag_search, h3 alebo web_search. Akýkoľvek iný je odmietnutý s EXECUTOR_NOT_PERMITTED. Tri exekútory znalostného grafu akceptujú iba názvy nástrojov graphrag_query a graphrag_search, pretože exekútor spúšťa tú operáciu, podľa ktorej je nástroj pomenovaný.

V registri existujú dve úrovne, ktoré zásuvný modul nemôže deklarovať: reťazce (chains) a zručnosti, ktoré bežia samostatne, zapisuje výlučne platforma. Synchronizácia, ktorá niektorú z nich menuje, je odmietnutá ako celok.

Ktorú úroveň použiť

  • host_callback, keď je práca funkciou vstupu, ktorú vypočítava váš vlastný kód: skóre, výpočet, vyhľadávanie vo vašej vlastnej schéme. Najjednoduchšie sa testuje a v šablóne je predvolená. Chráňte cestu spätného volania (callback route): cesta v manifeste nie je tajomstvom a táto cesta musí overiť volanie platformy a prevziať organizáciu z neho, nikdy nie z tela požiadavky. Deklarujte ju ako auth: internal a pripojte na ňu requireService (Fastify) alebo serviceMiddleware (Express). Ochranný mechanizmus odmietne token vygenerovaný pre kohokoľvek iného. Odpovedajte rýchlo a zabezpečte, aby bolo druhé doručenie tej istej úlohy neškodné.
  • plugin_queue pre dlhšiu prácu, na ktorú človek čaká a kde životný cyklus riadi váš spracovateľ (worker). Spracovateľ musí pri spustení presunúť beh do stavu running a pri dokončení do koncového stavu; spracovateľ, ktorý iba odošle svoj výsledok, nechá beh navždy zobrazovať stav queued.
  • llm_only, keď úlohu zvládne jedno volanie modelu s pevným systémovým pokynom (prompt) a váš zásuvný modul má úroveň core alebo verified.
  • tool_using, keď model potrebuje volať nástroje v slučke, opäť iba na úrovni core alebo verified.
  • map, keď chcete, aby platforma rozvetvila jednu z vašich ďalších zručností na položky zoznamu.

Moja zručnosť na propagáciu obežnej dráhy v spoločnosti Corrán Orbital je host_callback. Náš zásuvný modul má úroveň community, takže úrovne s modelmi nikdy neboli možnosťou, a ani mi nechýbajú: propagátor, ktorý by v utorok dal inú odpoveď, by bol horší ako zbytočný.

Schválenie pred každým behom

Zručnosť v manifeste, ktorá sa nikdy nesmie spustiť len na základe rozhodnutia stroja, to deklaruje takto:

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

required je vždy true; zručnosť, ktorá nepotrebuje schválenie, tento blok vynecháva. reason je to, čo vidí schvaľovateľ, 1 až 500 znakov po orezaní medzier, pričom akýkoľvek iný tvar je odmietnutý s APPROVAL_INVALID. Odoslanie takejto zručnosti je následne pozdržané: odoslanie odpovie 202 so stavom status: "awaiting_approval" a waitpointId a uvoľní ho iba schválenie menovanou osobou, a to jednorazovo. Dávkové (batch), mapovacie (map) alebo reťazové (chain) odoslanie pozdržanej zručnosti je odmietnuté s SKILL_APPROVAL_NOT_HOLDABLE, pretože rozvetvenie (fan-out) nedokáže pozdržať svoje položky. Zobrazte pozdržanú odpoveď a nechajte schvaľovateľa rozhodnúť; neodosielajte úlohu s tým, že si súhlas vypýtate až potom.

Synchronizácia do registra

Každá synchronizácia je deklaratívna a kontroluje sa ako celok. Zakaždým odošlite úplnú množinu zručností: zručnosť, ktorú vynecháte, sa deaktivuje a jej história behov zostane zachovaná. Jedna chybná zručnosť odmietne celú synchronizáciu s SYNC_CONTRACT_VIOLATION, pričom sa vypíšu všetky porušenia naraz a nič sa nezapíše, takže zásuvný modul sa nikdy neaktualizuje len spolovice. Kapitola 2.22, Behové prostredie zásuvného modulu, sa venuje volaniu synchronizácie a tomu, ako platforma vie, ktorý zásuvný modul volanie vykonáva.

Zručnosti v IDE a Claude Code
Zručnosti v IDE a Claude Code
Časť Zručnosti v IDE a Claude Code ukazuje tie isté kroky validácie, nahrávania a publikovania z vlastného terminálu vývojára, pričom návrh je pozdržaný na schválenie, pretože jeho autorka nemôže schváliť vlastnú zmenu.

Výber medzi týmito dvoma druhmi

Ak úloha znie „povedz toto zakaždým rovnakým spôsobom“, ide o zručnosť nástroja Skills Engine. Ak úloha znie „spusti môj kód a daj mi jeho odpoveď“, ide o zručnosť v manifeste. Väčšina reálnej práce nakoniec využíva oboje: zhrnutie kotvísk v Harrow je zručnosť nástroja Skills Engine, ktorej nástroje pochádzajú zo zásuvného modulu, a samotné nástroje zásuvného modulu sú deklarované v jeho manifeste. Zručnosť nástroja Skills Engine je z týchto dvoch možností lacnejšia na zmenu, čo je dobrý dôvod ponechať formulácie a úsudok v nej a aritmetiku v zásuvnom module.

Náklady sú reálne v oboch prípadoch. Zručnosť nástroja Skills Engine nie je hotová vtedy, keď sa SKILL.md dobre číta; je hotová vtedy, keď prejdú jej testovacie prípady, jej skúšobný beh sa zhoduje s tým, ako sa rozhodli ľudia, a schválil ju niekto iný ako vy. Na zručnosť, ktorá zapisuje, si vyhraďte týždeň, pričom väčšinu z toho zaberie kanárikové nasadenie.