Wersja 1.0.0-alpha.1najnowsza
Rozdział 2.20
Umiejętności (Skills)
Jak napisać, przetestować i opublikować umiejętność silnika Skills Engine, gdzie się ona pojawia po wdrożeniu oraz czym różnią się umiejętności zdefiniowane w manifeście wtyczki. Zawiera praktyczny przykład podsumowania przydziału miejsc postojowych dla Harrow Port Authority.
Ta strona została przetłumaczona przez AI z angielskiego oryginału. W razie jakichkolwiek niejasności wersją wiążącą jest strona w języku angielskim. Przeczytaj tę stronę po angielsku

Tomás Reilly, inżynier platformy w Harrow Port Authority, zapytał mnie w zeszłym miesiącu, dlaczego jego planiści nabrzeży za każdym razem otrzymywali inną odpowiedź, gdy pytali asystenta: „kto jutro stoi przy którym nabrzeżu i co uległo zmianie?”. Odpowiedź brzmiała: nikt nie przekazał asystentowi, jak powinna wyglądać dobra odpowiedź. Umiejętność w Skills Engine rozwiązała ten problem w jedno popołudnie: planiści otrzymują teraz za każdym razem takie samo trzyczęściowe podsumowanie, zawierające na początku tabelę nabrzeży, poniżej zmiany od ostatniego planu, a na końcu kolizje. W tym rozdziale szczegółowo omawiamy tę umiejętność od początku do końca, a następnie przechodzimy do drugiego rodzaju umiejętności – tej znajdującej się w manifeście wtyczki.
Dwa rodzaje umiejętności
Nexus używa słowa „umiejętność” (skill) w odniesieniu do dwóch różnych rzeczy, które buduje się w odmienny sposób.
| Umiejętność Skills Engine | Umiejętność manifestu | |
|---|---|---|
| Czym to jest | Pakiet SKILL.md w bibliotece umiejętności |
Typowany wiersz w tablicy skills[] wtyczki |
| Kto ją tworzy | Każda osoba z odpowiednimi uprawnieniami, w kreatorze lub we własnym edytorze | Deweloper, wewnątrz wtyczki |
| Co zawiera | Instrukcje, narzędzia, które może wywoływać, opcjonalne pliki i skrypty | Schemat wejściowy i wyjściowy, warstwę (tier) oraz pola wymagane przez tę warstwę |
| Jak trafia na platformę | Po walidacji, przesłaniu i opublikowaniu w Skills Engine | Po skompilowaniu z manifestu i zsynchronizowaniu z rejestrem umiejętności |
| Co ją uruchamia | Asystent, agenci, przepływy pracy, przyciski AI (sztucznej inteligencji), Claude Code | Dyspozytor UNO (silnika przepływów pracy) |
| Typowe zastosowanie | „Za każdym razem podsumowuj plan nabrzeży w ten sam sposób” | „Uruchom nasz propagator orbity dla tego przelotu” |
W dalszej części rozdziału oba pojęcia są wyraźnie rozgraniczone. Jeśli w akapicie użyto samego słowa „umiejętność”, oznacza to umiejętność w Skills Engine.
Część 1: umiejętności silnika Skills Engine
Czym jest umiejętność
Umiejętność to folder. Jego plik SKILL.md określa, do czego służy dana umiejętność i jak wykonać zadanie; obok niego znajdują się wszelkie pliki potrzebne do realizacji zadania oraz uruchamiane skrypty. Silnik ładuje umiejętność w trzech warstwach: nazwa i opis są ładowane zawsze, instrukcje – gdy zadanie wymaga użycia danej umiejętności, a pliki – tylko wtedy, gdy są potrzebne w konkretnym kroku. Właśnie dlatego instalacja może przechowywać dwieście umiejętności, nie generując niemal żadnych kosztów do momentu użycia jednej z nich.
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
Nazwa katalogu musi być identyczna z identyfikatorem (slug) umiejętności. Rozbieżność powoduje wyświetlenie ostrzeżenia walidacji, które warto naprawić, ponieważ na podstawie identyfikatora biblioteka dopasowuje przesyłany pakiet do istniejącej umiejętności.
Metadane frontmatter w pliku SKILL.md
Sekcja frontmatter to kod YAML umieszczony pomiędzy dwiema liniami --- na początku pliku. Format ten wymaga trzech pól. Sama walidacja blokuje proces tylko w kilku przypadkach: braku nazwy lub opisu oraz sytuacji, gdy identyfikator (slug) lub typ zadania są już zajęte. Wszystkie inne nieprawidłowości są zgłaszane jako ostrzeżenia.
| Pole | Typ | Wymagane | Co zawiera |
|---|---|---|---|
name |
ciąg znaków (string) | tak | Unikalny identyfikator w formacie kebab-case |
description |
ciąg znaków (string) | tak | Opis działania umiejętności, maksymalnie 500 znaków. Korzystają z niego biblioteka oraz mechanizm dopasowujący, należy więc napisać go z myślą o użytkowniku decydującym, czy to właściwa umiejętność |
allowed-tools |
ciąg znaków lub lista | tak | Narzędzia, które umiejętność może wywoływać. Może ona jedynie zawęzić listę dozwolonych narzędzi (allow-list) podmiotu, który ją uruchamia |
triggers |
lista | nie | Polecenia ukośnika (slash commands), które wywołują umiejętność bezpośrednio |
capabilities |
lista | nie | Ustrukturyzowane możliwości (capabilities), z których każda zawiera name, description oraz opcjonalnie input_schema, output_schema i examples |
version |
ciąg znaków (string) | nie | Wersja semantyczna; 1.0.0 w przypadku pominięcia |
visibility |
ciąg znaków (string) | nie | private, team lub public |
status |
ciąg znaków (string) | nie | draft, testing lub published |
Instrukcje nie powinny przekraczać około 5 000 tokenów. Należy pisać konkretnie i podawać przykłady. Każda umiejętność powinna dobrze wykonywać jedno zadanie; jeśli pojawia się konieczność napisania „a także”, prawdopodobnie należy utworzyć dwie osobne umiejętności.
skill.yaml
Plik skill.yaml przechowuje dane niezbędne dla silnika do wyszukiwania oraz obsługi biblioteki, dzięki czemu plik SKILL.md pozostaje czytelny. Pola odczytywane przez silnik obejmują: name, display_name, description, version, status, visibility, triggers, aliases, category, tags, allowed_tools oraz capabilities. Możliwość (capability) może zawierać pole query_patterns, czyli sformułowania, które mechanizm dopasowujący powinien do niej kierować. Dostępne są również wskazówki dotyczące budżetowania samego silnika: complexity, estimated_tokens oraz required_services.
scripts/
Wszystkie elementy znajdujące się w katalogu scripts/ są dołączane w niezmienionej postaci do umiejętności jako jej komponenty. Skrypt jest uruchamiany w środowisku izolowanym (sandbox) i nigdy nie jest wczytywany do kontekstu modelu. Należy go używać, gdy dany krok wymaga obliczeń arytmetycznych lub parsowania, których model nie powinien wykonywać samodzielnie.
Widoczność i status
Widoczność określa, kto może znaleźć umiejętność: private oznacza tylko Państwa, team – Państwa zespół, a public – wszystkich członków organizacji obsługiwanej przez bibliotekę. W konsoli ten sam wybór jest widoczny jako „Only me” (Tylko ja), nazwa zespołu, np. „Customs desk” (Dział celny), lub cała organizacja. Umiejętność można również udostępnić w pakiecie domenowym po przejściu procesu weryfikacji właściwego dla tego pakietu.
Status określa etap cyklu życia, na którym znajduje się umiejętność.
| Status | Znaczenie |
|---|---|
draft |
Praca w toku; niewidoczna w wyszukiwaniu |
testing |
W trakcie walidacji, z ograniczonym dostępem |
published |
Dostępna do ogólnego użytku |
deprecated |
Zastąpiona; w trakcie wycofywania |
Raz opublikowana wersja nigdy nie ulega zmianie. W konsoli oznaczenia „live”, „canary” oraz „shadow” są etykietami przypisanymi do wersji, a powrót do wcześniejszej wersji polega na przeniesieniu etykiety. Uruchomienia będące w toku kończą działanie na wersji, na której zostały rozpoczęte.
SKILL.md, znajdujące się obok niego pliki wraz z informacją o momencie ich ładowania oraz narzędzia, które umiejętność może wywoływać. Umiejętność sprawdzająca nie otrzymuje dostępu do żadnych narzędzi wykonujących zapis, a sama umiejętność może jedynie zawęzić listę dozwolonych narzędzi podmiotu uruchamiającego.Od folderu do gotowej umiejętności
Pięć skryptów npm w repozytorium Skills Engine przenosi umiejętność z Państwa edytora do biblioteki i potwierdza jej dotarcie na miejsce.
| Polecenie | Co robi |
|---|---|
npm run skill:validate skills/<slug> |
Sprawdza składnię pakietu (linting). Publikacja wymaga braku błędów |
npm run skill:upload skills/<slug> |
Waliduje i publikuje w jednym kroku; operacja idempotentna |
npm run skill:upload skills/<slug> --dry-run |
Waliduje i wyświetla plan bez zapisywania jakichkolwiek zmian |
npm run skill:publish -- --dry-run skills/<slug> |
Niskopoziomowa publikacja stojąca za procesem przesyłania, ten sam potok |
npm run skill:reconcile |
Porównuje umiejętności w Państwa repozytorium z zawartością biblioteki i rejestru umiejętności |
npm run skill:live:verify |
Kompleksowo sprawdza opublikowaną umiejętność na działającej instalacji |
Publikacja zapisuje dwa wpisy i oba są istotne. Pierwszy to sama umiejętność wraz z treścią SKILL.md, możliwościami, komponentami i rekordem jakości; korzystają z niego biblioteka, wyszukiwanie oraz dopasowywanie. Drugi to wpis w rejestrze, względem którego silnik przepływów pracy rozwiązuje dyspozycje (dispatch). Umiejętność, która trafiła wyłącznie do rejestru, będzie działać, ale pozostanie niewidoczna w bibliotece do momentu jej przesłania.
Publikacja jest operacją idempotentną. Niezmieniona umiejętność nie wywołuje żadnej akcji (no-op), a istniejąca umiejętność jest dopasowywana na podstawie identyfikatora (slug) i aktualizowana w miejscu, bez ponownego tworzenia. Przesłanie tych samych bajtów, które składają się na już opublikowaną wersję, zwraca tę wersję z kodem CONTENT_HASH_ALREADY_PUBLISHED, zamiast tworzyć duplikat.
Polecenie skill:reconcile porównuje umiejętności z Państwa repozytorium z biblioteką, rejestrem oraz inwentarzem silnika przepływów pracy, zgłaszając wszystko, co istnieje w jednym miejscu, a brakuje go w innym. Polecenie skill:live:verify idzie o krok dalej na działającej instalacji: sprawdza, czy oba wpisy istnieją i wskazują na siebie nawzajem z tym samym skrótem zawartości (content hash), czy próbna dyspozycja (dry-run) typu zadania umiejętności zostaje zaakceptowana, czy umiejętność jest widoczna na liście i w szczegółach biblioteki, czy można ją wywołać oraz czy ścieżka audytu łączy publikację, dyspozycję i uruchomienie za pomocą identyfikatora (slug) oraz identyfikatora żądania.
Ze stacji roboczej przesyłanie trafia do usługi wiedzy danej instalacji, nexus-graphrag, za pośrednictwem przekierowania portów (port-forward) i wymaga obecności klucza usługi Skills Engine w zmiennych środowiskowych. Należy załadować klucz bez wyświetlania go na ekranie:
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-summaryWewnątrz klastra, w zadaniu potoku (pipeline job), domyślny adres jest rozwiązywany automatycznie i ustawienie GRAPHRAG_URL nie jest potrzebne. Klucz należy pobrać zgodnie z procesem zarządzania sekretami obowiązującym w Państwa organizacji. Nigdy nie powinien on trafić do repozytorium, historii powłoki ani danych wyjściowych polecenia.
Testy, zatwierdzanie i wdrożenie produkcyjne
Umiejętność trafia do biblioteki jako wersja robocza, a kreator zatrzymuje ją na tym etapie do momentu pomyślnego przejścia trzech kroków.
| Sprawdzany element | Co robi |
|---|---|
| Przypadki testowe | Każdy przypadek musi zakończyć się powodzeniem, zanim umiejętność zostanie przekazana do zatwierdzenia. Przypadek testowy można usunąć wyłącznie po podaniu przyczyny, która jest widoczna dla osób zatwierdzających. |
| Próbne uruchomienie w trybie shadow | Umiejętność jest uruchamiana na danych historycznych, gdzie nikt nie widzi odpowiedzi, a jej wyniki są porównywane z decyzjami podjętymi wówczas przez człowieka. |
| Ślepa recenzja wykonywana przez model z innej rodziny | Szuka ona pominiętych sprawdzeń, zmyślonych źródeł oraz ukrytych instrukcji (planted instructions), za którymi umiejętność podążyła, choć nie powinna. |
Następnie odbywa się zatwierdzanie. Umiejętność dodająca narzędzie wykonujące zapis jest wstrzymywana do czasu zatwierdzenia jej przez dwie osoby za pomocą kluczy dostępu (passkeys), przy czym osoba zgłaszająca nie może być jedną z nich (PUBLISH_NEEDS_APPROVAL). Następnie umiejętność jest wdrażana w trybie shadow, potem w trybie canary dla jednej jednostki za nazwanymi bramkami, a ostatecznie dla wszystkich. Jeśli bramka canary nie zostanie spełniona, wdrożenie canary zatrzymuje się automatycznie, a wszyscy użytkownicy pozostają na poprzedniej wersji; wcześniejsze udostępnienie umiejętności wszystkim wymaga podania przyczyny oraz zgody drugiej osoby zatwierdzającej (CANARY_GATE_NOT_MET).
W edycji Community dostępne są kreator, biblioteka, wersje oraz testy, a właściciel publikuje umiejętność samodzielnie po pomyślnym przejściu testów. Tryb canary, zatwierdzanie przez dwie osoby, synchronizacja wtyczek oraz scalanie duplikatów są dostępne w edycji Enterprise.
Gdzie pojawiają się umiejętności
Ta sama opublikowana umiejętność trafia do użytkowników w pięciu miejscach.
- Asystent dopasowuje żądanie do umiejętności na podstawie jej opisu, wyzwalaczy i wzorców zapytań, a następnie postępuje zgodnie z instrukcjami tej umiejętności.
- Agenci i przepływy pracy wywołują umiejętności jako kolejne kroki. Krok przepływu pracy wskazuje nazwę umiejętności, a uruchomienie rejestruje użytą wersję.
- Przyciski AI na ekranach uruchamiają po jednej umiejętności każdy. Administrator może otworzyć sekcję „About this button” (Informacje o tym przycisku), aby sprawdzić, jaką umiejętność uruchamia dany przycisk, jakie dane odczytuje i kto ostatnio wprowadził w niej zmiany, a także aby wyłączyć przycisk bez modyfikowania samej umiejętności.
- Państwa środowisko IDE (zintegrowane środowisko programistyczne) oraz Claude Code łączą się z biblioteką za pośrednictwem usługi Workbench oraz trzynastu narzędzi MCP (Model Context Protocol), wśród których znajdują się m.in.:
list_skills,get_skill,match_prompt,discover_skills,invoke_skill,record_execution,create_skill,import_skill,get_generation_joborazsync_skills_local. Każde wywołanie jest uruchamiane w kontekście osoby, która je zainicjowała, w ramach jej listy dozwolonych narzędzi. - Sama biblioteka umiejętności, w której użytkownicy przeglądają, uruchamiają i sugerują zmiany w umiejętnościach, a administratorzy widzą właściciela każdej umiejętności, jej użytkowników, uruchomienia oraz koszty.
Niezależnie od tego, co uruchamia umiejętność, nie może ona rozszerzyć uprawnień podmiotu uruchamiającego: wywołuje wyłącznie narzędzia znajdujące się na liście dozwolonych dla tego podmiotu i odczytuje tylko te dane, które dana osoba ma prawo otworzyć (SKILL_CANNOT_WIDEN_TOOLS). Uruchomienie bez określonej trasy modelu zostaje odrzucone, zamiast polegać na domysłach (SKILLS_ENGINE_BINDING_MISSING); trasę wybiera dyspozytor na podstawie konfiguracji modeli w danej organizacji.
Praktyczny przykład: podsumowanie przydziału nabrzeży dla Harrow
Planiści w Harrow mieli już na swojej liście dozwolonych narzędzi dwa narzędzia tylko do odczytu, pochodzące z własnej wtyczki do planowania nabrzeży Harrow: berth-plan.read zwraca plan dla danej daty, a vessel-call.read zwraca zawinięcie statku wraz z oknem przybycia i długością jednostki. Umiejętność nie potrzebuje niczego więcej. Nigdy nie wykonuje zapisu, dlatego nie wymaga zatwierdzenia przez dwie osoby.
---
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.Znajdujący się obok plik skill.yaml przekazuje bibliotece nazwę wyświetlaną, kategorię oraz sformułowania, które mechanizm dopasowujący powinien tutaj kierować:
# 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 *"Następnie polecenia uruchamiane z głównego katalogu repozytorium:
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 dodał w kreatorze sześć przypadków testowych: zwykły dzień, dzień z opóźnionym przybyciem, które przesunęło dwa zawinięcia, dzień z rzeczywistą kolizją, datę bez utworzonego jeszcze planu, statek zbyt długi dla przypisanego nabrzeża oraz żądanie próbujące skłonić umiejętność do zaproponowania nowego nabrzeża (czego nie powinna robić, ponieważ nie ma narzędzia do zapisu). Próbne uruchomienie odtworzyło w trybie shadow dwadzieścia historycznych planów. Gdy przypadki testowe zakończyły się powodzeniem, recenzent z działu planowania zatwierdził umiejętność, po czym została ona wdrożona dla zespołu planistów. Asystent odpowiada teraz na pytanie za każdym razem w tej samej formie, a przycisk AI dostępny dla planistów na stronie planu nabrzeży uruchamia tę samą umiejętność.
Część 2: umiejętności zdefiniowane w manifeście
Umiejętność manifestu to jednostka obliczeniowa publikowana przez wtyczkę. Jest ona deklarowana w sekcji skills[] manifestu, walidowana przez pakiet SDK (software development kit) podczas uruchamiania create-nexus-plugin validate, kompilowana do treści rejestru przez compileRegistry i synchronizowana z rejestrem umiejętności. Nigdy nie piszą Państwo zapytań SQL rejestru ręcznie, dzięki czemu wiersz dysponowany przez platformę oraz zadeklarowany deskryptor nie mogą się rozminąć.
Każda umiejętność manifestu wymaga pól id, displayName, description, tier, classification, inputSchema oraz outputSchema. Należy zadeklarować również timeoutMs: jest to liczba całkowita z przedziału od 1 000 do 21 600 000 (od jednej sekundy do sześciu godzin), a wartość spoza tego zakresu zostaje odrzucona z kodem TIMEOUT_OUT_OF_BOUNDS. Pole dataResidency przyjmuje wartość any, eu lub us, przy czym domyślną wartością jest any.
Wartość id jest zapisywana w formacie lower_snake, a kluczem dyspozycji w rejestrze jest umieszczony w przestrzeni nazw typ zadania <plugin name>.<skill id>, dzięki czemu dwie wtyczki mogą mieć umiejętność summarise bez powodowania konfliktu. Poniżej przedstawiono skróconą wersję pojedynczej umiejętności z szablonu:
{
"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
}Pięć warstw
Warstwa (tier) to nie tylko etykieta. Każda warstwa ma własne pola, a pole należące do innej warstwy zostaje odrzucone z kodem FIELD_NOT_FOR_TIER, zamiast zostać po cichu pominięte.
| Poziom | Wymaga | Łączy się z modelem | Kto ją uruchamia |
|---|---|---|---|
host_callback |
hostCallback: Państwa usługa Service, jej port, ścieżka oraz oba limity bajtów |
Nie | Platforma wysyła dane wejściowe metodą POST do Państwa własnej usługi Service, wewnątrz Państwa przestrzeni nazw |
plugin_queue |
queueName, zapisywane jako <plugin name>.<name> |
Nie | Państwa proces roboczy (worker), pobierający zadania z Państwa kolejki |
tool_using |
systemPrompt oraz tools[]; poziom zaufania core lub verified |
Tak | Platforma, za pośrednictwem routera dostawców AI (AI Provider Router); każde wywołanie narzędzia przechodzi przez wykonawcę (executor) z listy dozwolonych |
llm_only |
systemPrompt; poziom zaufania core lub verified |
Tak | Platforma, jedno wywołanie za pośrednictwem routera dostawców AI |
map |
map.perItemJobType, wskazujące inną umiejętność z tego samego manifestu, która nie jest mapą |
Tylko za pośrednictwem swojego celu | Platforma uruchamia cel raz dla każdego elementu i zbiera wyniki |
Żadna z warstw modelowych nie wskazuje dostawcy ani modelu. Router wybiera oba te elementy z własnej puli organizacji zlecającej dyspozycję. Narzędzie w umiejętności tool_using wskazuje jednego z sześciu wykonawców: standing_service_call (Państwa własna usługa Service), graphrag, graphrag_query, graphrag_search, h3 lub web_search. Każdy inny zostaje odrzucony z kodem EXECUTOR_NOT_PERMITTED. Trzej wykonawcy grafu wiedzy akceptują wyłącznie nazwy narzędzi graphrag_query oraz graphrag_search, ponieważ wykonawca uruchamia operację odpowiadającą nazwie narzędzia.
W rejestrze istnieją dwie warstwy, których wtyczka nie może zadeklarować: łańcuchy (chains) oraz umiejętności uruchamiające się samodzielnie są zapisywane wyłącznie przez platformę. Synchronizacja wskazująca którąkolwiek z nich zostaje w całości odrzucona.
Którą warstwę wybrać
host_callback– gdy praca jest funkcją danych wejściowych obliczaną przez Państwa własny kod: ocena punktowa, kalkulacja, wyszukiwanie we własnym schemacie. Jest najprostsza do przetestowania i stanowi wartość domyślną w szablonie. Należy zabezpieczyć trasę wywołania zwrotnego (callback): ścieżka w manifeście nie jest sekretem, dlatego trasa musi weryfikować wywołanie z platformy i pobierać z niego organizację, nigdy z treści żądania (body). Należy zadeklarować ją jakoauth: internali zamontować na niejrequireService(Fastify) lubserviceMiddleware(Express). Mechanizm zabezpieczający odrzuca token wygenerowany dla kogokolwiek innego. Należy odpowiadać szybko i zadbać o to, aby powtórne dostarczenie tego samego zadania było nieszkodliwe.plugin_queue– w przypadku dłuższych zadań, na których wynik oczekuje użytkownik, gdzie Państwa proces roboczy (worker) zarządza cyklem życia. Proces roboczy musi zmienić status uruchomienia narunningw momencie rozpoczęcia oraz na status końcowy po zakończeniu pracy; proces roboczy, który jedynie przesyła wynik, pozostawia uruchomienie ze statusemqueuedna zawsze.llm_only– gdy zadanie realizuje pojedyncze wywołanie modelu ze stałym promptem systemowym, a Państwa wtyczka ma poziomcorelubverified.tool_using– gdy model musi wywoływać narzędzia w pętli, również wyłącznie na poziomiecorelubverified.map– gdy chcą Państwo, aby platforma rozproszyła wykonanie jednej z pozostałych Państwa umiejętności na elementy listy (fan-out).
Moja umiejętność propagacji orbity w Corrán Orbital to host_callback. Nasza wtyczka ma poziom community, więc warstwy modelowe nigdy nie wchodziły w grę, i wcale mi ich nie brakuje: propagator, który we wtorek dawałby inną odpowiedź, byłby gorszy niż bezużyteczny.
Zatwierdzanie przed każdym uruchomieniem
Umiejętność manifestu, która nigdy nie może zostać uruchomiona wyłącznie na podstawie decyzji maszyny, deklaruje to w następujący sposób:
"approval": { "required": true, "reason": "Re-planning a pass needs the flight dynamics lead." }Pole required ma zawsze wartość true; umiejętność niewymagająca zatwierdzenia pomija ten blok. Pole reason to treść widoczna dla osoby zatwierdzającej, licząca od 1 do 500 znaków po przycięciu białych znaków, a każdy inny format zostaje odrzucony z kodem APPROVAL_INVALID. Dyspozycja takiej umiejętności zostaje wówczas wstrzymana: zwraca ona odpowiedź 202 ze statusem status: "awaiting_approval" oraz identyfikatorem waitpointId, a zwalnia ją – jednorazowo – wyłącznie zatwierdzenie przez wskazaną osobę. Dyspozycja wsadowa (batch), mapująca (map) lub łańcuchowa (chain) wstrzymanej umiejętności zostaje odrzucona z kodem SKILL_APPROVAL_NOT_HOLDABLE, ponieważ operacja rozproszenia (fan-out) nie może wstrzymywać poszczególnych elementów. Należy wyrenderować wstrzymaną odpowiedź i pozwolić osobie zatwierdzającej podjąć decyzję; nie należy wysyłać dyspozycji, a dopiero potem pytać o zgodę.
Synchronizacja z rejestrem
Każda synchronizacja jest deklaratywna i weryfikowana jako całość. Za każdym razem należy przesyłać pełny zestaw umiejętności: pominięta umiejętność zostaje wyłączona, a historia jej uruchomień zostaje zachowana. Jedna błędna umiejętność powoduje odrzucenie całej synchronizacji z kodem SYNC_CONTRACT_VIOLATION, zwracając wspólną listę wszystkich naruszeń i nie zapisując żadnych danych, dzięki czemu wtyczka nigdy nie zostaje zaktualizowana tylko częściowo. Rozdział 2.22, Środowisko uruchomieniowe wtyczek, omawia wywołanie synchronizacji oraz sposób, w jaki platforma rozpoznaje, która wtyczka wykonuje wywołanie.
Wybór między dwoma rodzajami
Jeśli zadanie polega na tym, aby „za każdym razem sformułować to w ten sam sposób”, jest to umiejętność w Skills Engine. Jeśli zadanie brzmi „uruchom mój kod i zwróć jego wynik”, jest to umiejętność manifestu. Większość rzeczywistych zastosowań łączy oba te podejścia: podsumowanie nabrzeży w Harrow to umiejętność w Skills Engine, której narzędzia pochodzą z wtyczki, a same narzędzia wtyczki są zadeklarowane w jej manifeście. Umiejętność w Skills Engine jest tańsza w modyfikacji, co stanowi dobry powód, aby zachować w niej warstwę językową i ocenę sytuacji, a obliczenia arytmetyczne pozostawić we wtyczce.
Koszt jest jednak realny w obu przypadkach. Umiejętność w Skills Engine nie jest gotowa w momencie, gdy plik SKILL.md dobrze się czyta; jest gotowa wtedy, gdy jej przypadki testowe kończą się powodzeniem, próbne uruchomienie zgadza się z historycznymi decyzjami ludzi, a ktoś inny niż Państwo ją zatwierdził. Na umiejętność wykonującą zapis należy zaplanować tydzień, z czego większość czasu zajmie etap canary.



