Skille

Skill to wiedza praktyczna zapisana raz i podpięta do wielu agentów: jak obsługuje się zwroty pieniędzy, jaki jest styl firmowy, jakie sprawdzenia musi przejść raport, zanim pójdzie na zewnątrz.

Zastępuje pole z instrukcjami, które rośnie.

Dwadzieścia procedur w jednym prompcie oznacza, że każdy run płaci za wszystkie dwadzieścia, a dwudziesta pierwsza wypycha rozmowę poza okno kontekstu. Skille odwracają tę zależność:

flowchart LR
    A["the agent's capability catalog<br/><i>names + one-line descriptions only</i>"] --> B{is one relevant?}
    B -->|no| Z["no body loaded"]
    B -->|yes| C["load_capability - the body"]
    C --> D{does the body<br/>point at a file?}
    D -->|no| Z2[answer]
    D -->|yes| E["read_skill_resource - one file beside it"]
    E --> Z2

Dwadzieścia skilli kosztuje mniej więcej dwadzieścia opisów zamiast dwudziestu procedur.

Wykrywanie jest tanie, ale nie darmowe

Każdy podpięty skill siedzi w katalogu capability, który model czyta w każdej turze — jako nazwa i jednolinijkowy opis. Podpięcie skilla kosztuje więc tokeny niezależnie od tego, czy model kiedykolwiek go otworzy.

To linijka na skilla zamiast całej treści na skilla i dlatego rachunek się spina. Nie jest to jednak powód, żeby podpinać nieograniczony katalog.

Druga połowa sensu to kto je pisze. Skill jest wierszem w bazie danych, edytowalnym w UI, więc szef wsparcia może poprawić politykę zwrotów we wtorek po południu. Bez deployu, bez pull requesta, bez inżyniera.

Skill, plik kontekstowy czy kolekcja wiedzy?

Skill to procedura, którą model wczytuje, kiedy uzna, że przyszło na nią zadanie. Plik kontekstowy to wiedza stała — krótka, zawsze istotna, wstrzykiwana albo czytana na żądanie. Kolekcja wiedzy to korpus zbyt duży, żeby go przeczytać, dostępny przez wyszukiwanie.

Kształt

---
name: refund-policy
description: When a refund is given without asking, when it needs approval, and how to say no.
category: support
---

# Refunds

Most refund questions are decided by the order date and one exception. Check
those before escalating anything.

Strona **Skills** pokazuje na karcie początek treści każdego skilla — bez front
matter, kilka linii — a za nim po jednym arkuszu na każdy plik, który skill ze
sobą niesie. `GET /api/v1/skills` zwraca ten początek jako `excerpt`; samą treść
wczytuje dopiero otwarcie skilla.

## Decide without asking
...

description to pole, które decyduje, czy skill kiedykolwiek zostanie wczytany

To jedyna część, którą model widzi za darmo. Napisz je jako kiedy po to sięgnąć, a nie jako tytuł.

Skill może nieść zasoby — kolejne pliki obok niego, wczytywane na żądanie. refund-policy ma przy sobie exceptions.md, a treść mówi, kiedy do niego zajrzeć.

To to samo stopniowe odsłanianie, tylko poziom niżej: szczegół potrzebny tylko części rozmów nie musi siedzieć w treści, którą wczytuje każda istotna rozmowa.

category to jedna z dwudziestu sugestii (support, engineering, finance, legal, security, marketing, …) i steruje filtrem na liście skilli. Nie ma wpływu na to, co widzi agent — model wybiera po description, nigdy po kategorii.

Jak agent go czyta

Przez capability skills. Każdy skill, który agent dostaje, staje się osobną capability — wypisaną modelowi z nazwy i opisu, a otwieraną na żądanie:

Jak	Co robi
Katalog capability	Nazwy i jednolinijkowe opisy wszystkiego, co jest podpięte do tego agenta
load_capability	Pełna treść jednego skilla, wciągnięta do rozmowy
read_skill_resource	Jeden plik obok skilla

load_capability jest narzędziem samego frameworka agentowego, a nie czymś, co publikuje ta platforma — spec go więc nie przyznaje i nie zmienia mu nazwy. Może go natomiast bramkować, bo to wywołanie otwiera skilla: tool_approval na nim jest sposobem, w jaki agent pyta człowieka, zanim skill trafi do modelu, a spec, który bramkował dawne load_skill, jest na nie migrowany, zamiast zostać bez bramki. Jako własne narzędzie ta capability wnosi read_skill_resource, i tylko wtedy, gdy przynajmniej jeden z podpiętych skilli wiezie ze sobą plik do odczytania.

Spec podpina skille po id w skill_ids, więc agent widzi te, które dostał, i nic poza tym.

Prosto ze skilla. Każda karta na stronie Skille ma Dodaj do agenta: wybierasz agenta, a skill trafia do jego szkicu razem z włączoną capability Skille, gotowy do opublikowania w Builderze. Karta mówi też, którzy agenci używają skilla - albo że jeszcze żaden. Pliki kontekstu i bazy wiedzy mają to samo.

Nazwa skilla to id, pod którym model go ładuje, więc ma formę, w jakiej modele piszą id: małe litery i cyfry połączone pojedynczymi myślnikami, na przykład refund-policy. Nazwa ze spacjami lub wielkimi literami jest odrzucana przy tworzeniu skilla. Nazwę, którą model musiałby odtworzyć dokładnie, jak Refund policy, ładował jako refund-policy, a dwie błędne próby kończą turę (#1911).

Skill nie może nazywać się tak jak capability. Każdy jest zapisany pod własną nazwą w tej samej przestrzeni co knowledge, planning i reszta, więc skill o nazwie planning na agencie, który ma też capability planning, to duplikat, który framework odrzuca przed pierwszym tokenem. Utworzenie takiego jest odrzucane, tak samo jak publikacja agenta podpiętego do skilla o takiej nazwie.

Włączenie capability bez podpiętych skilli nie ma sensu — albo daj agentowi skille, albo zostaw capability wyłączoną.

W workspace skill to także pliki

Agent, który ma jednocześnie skille i workspace, dostaje każdy skill zapisany również w nim:

/workspace/skills/<name>/SKILL.md      the body, with its name and description
/workspace/skills/<name>/<resource>    each resource, beside it

To właśnie sprawia, że skrypt w skillu jest do czegokolwiek. Skill, którego zasobem jest reconcile.py, był wcześniej podawany modelowi jako tekst, który mógł zacytować, ale nie uruchomić, podczas gdy ten sam agent miał execute w odległości jednego wywołania narzędzia. Na dysku — działa.

Nie ma run_skill_script

Własne execute sandboksa niesie już reguły uprawnień workspace'u i limity operatora. Drugi sposób uruchamiania rzeczy byłby drugim zestawem reguł do pomylenia.

Agent może zaproponować zmianę; wprowadza ją człowiek

Te pliki są zapisywalne, a to, co agent zapisze, nie zostaje zastosowane.

Skill to instrukcje, którymi w każdym runie kieruje się każdy podpięty do niego agent. Agent, który mógłby go edytować bezpośrednio, mógłby przepisać to, co robi inny agent, wewnątrz rozmowy, której nikt nie przegląda, a kolejny czytelnik nie miałby jak odróżnić przemyślanego ulepszenia od zahalucynowanego.

Dlatego zapis staje się propozycją i pojawia się nad listą na stronie Skills każdemu, kto ma skills:edit:

• Apply przepisuje skilla i podbija jego wersję, która dociera do każdego podpiętego agenta przy jego następnym runie.
• Discard zachowuje zapis. Agent proponujący w kółko tę samą zmianę mówi komuś coś o skillu, a usunięty wiersz czyni to niewidocznym.

Decyzja o propozycji jest ostateczna

Zastosowanie dwa razy podbiłoby wersję wobec treści już zapisanej, a odrzucenie czegoś zastosowanego mówiłoby czytelnikowi, że nigdy nie weszło.

Propozycja niesie całą treść, a nie diff, więc recenzent kilka tygodni później porównuje dwie kompletne wersje, zamiast nakładać łatkę w miejscu, do którego nigdy nie była przeznaczona.

Dwie rzeczy zostają odrzucone, zamiast być zgadywane: katalog utworzony przez agenta bez SKILL.md w środku oraz taki, któremu agent zepsuł frontmatter. A usunięty zasób celowo nie jest zmianą, bo plik, którego model nigdy nie dotknął, i taki, który zamierzał usunąć, zostawiają po sobie ten sam brak.

Trzy tury jednej rozmowy dopracowujące ten sam skill zostawiają jedną propozycję, nie trzy. Recenzent zapytany trzy razy o to samo dostał więcej pracy, a nie więcej informacji. Propozycje z workspace mają te same limity metadanych co zapisane skille: nazwa od 1 do 64 znaków i opis do 500 znaków. Zmiana poza limitem jest pomijana z ostrzeżeniem; oryginalne pliki pozostają bez zmian. Zapis propozycji używa savepointu, więc odrzucona propozycja nie wycofa tury ani nie zablokuje zapisania jej statusu i kosztu.

Jak skille trafiają do organizacji

Napisz go. Skills → New, w UI. To zwykła droga.

Te dołączone już tam są. Repozytorium dostarcza cztery: trzy przykłady z rozwiązaniem — refund-policy, code-review i incident-report — oraz artifact-pages, który uczy agenta budować stronę dla capability Aplikacje. Każda organizacja zaczyna z nimi. Utworzenie organizacji kopiuje całą dostarczoną bibliotekę jako zwykłe skille, należące do właściciela (owner) organizacji i widoczne dla organizacji.

Strona skilli pokazuje jedną listę, z odznaką built-in przy wszystkim, czego nazwa pasuje do dostarczonej biblioteki. Tych czterech się nie wybiera — one po prostu przychodzą, raz, przy tworzeniu organizacji.

I od tej chwili są wasze. Zaseedowany skill to zwykły wiersz: można go edytować, wyłączyć albo usunąć. Nic nie przywraca usuniętego.

To jest zmiana. Lista wcześniej sama się uzupełniała — dokopiowywała każdą dołączoną nazwę, której organizacja nie miała, przy każdym otwarciu strony — więc usunięty built-in wracał przy następnej wizycie, a wyłączenie było jedynym sposobem na jego wycofanie. Oznaczało to też stronę, która zapisuje wiersze w trakcie czytania. Galeria jest miejscem, w którym wybiera się skill, a komenda seed poniżej jest sposobem, w jaki deployment rozsyła nowy dołączony skill świadomie.

Organizacja utworzona przed nowym dołączonym skillem nie dostanie go sama

Uruchom dla niej seed-skills albo zainstaluj skill z galerii. Obie drogi są świadome i o to chodzi: nic nie pojawia się przy wczytaniu strony.

Komenda seed robi to samo z terminala, na potrzeby skryptowanych instalacji:

uv run agenticos cmd seed-skills                    # every organization
uv run agenticos cmd seed-skills --org <org-id>     # one
uv run agenticos cmd seed-skills --dry-run          # say what would happen, do nothing
uv run agenticos cmd seed-skills --replace          # also overwrite copies edited here

Instaluje to, czego brakuje, i odświeża to, czego nikt nie edytował. Każda kopia zapamiętuje, z której wersji dołączonego skilla została zapisana, więc gdy wydanie ulepsza dołączony skill, nieruszana kopia w organizacji jest zastępowana nową — razem z plikami, z podbitą wersją i wpisem audytu skill.refreshed.

Kopia edytowana na miejscu zostaje dokładnie taka, jaka jest, więc edytowana polityka zwrotów przeżywa ponowny seed; --replace to jedyny sposób, żeby wziąć dołączoną wersję zamiast takich edycji, a wpis audytu to odnotowuje. Kopia zrobiona, zanim wersje były zapisywane, i różna od dołączonej też jest zgłaszana i zostawiana, bo nic nie powie, czy ktoś ją edytował.

Komenda wypisuje, co zrobiła z każdym skillem, a --dry-run wypisuje ten sam plan bez zapisywania.

e2e/seed.setup.ts tworzy jednego również przez UI i to na nim opiera swoje asercje zestaw E2E.

Galeria — siedemdziesiąt kolejnych i żaden nie przychodzi nieproszony

Skills → Skill gallery otwiera katalog gotowych skilli pogrupowanych według branż: ochrona zdrowia, finanse i ubezpieczenia, e-commerce i print on demand, zespoły software'owe, sektor publiczny i usługi komunalne, usługi prawne i profesjonalne, produkcja i logistyka. Po dziesięć w każdej.

Wybierz branżę, a potem zainstaluj jeden skill albo całą półkę. Od tej chwili to zwykły skill, który organizacja posiada i edytuje, dokładnie jak dołączony.

Galeria działa na zaproszenie i na tym polega cała różnica

Dołączona czwórka mieszka w app/core/catalog/skills/ i jest kopiowana automatycznie do każdej organizacji. Galeria mieszka w app/core/catalog/skill_gallery/ i nie jest kopiowana do żadnej — czyta ją ten sam parser, z drugiego katalogu, i nigdy nie jest seedowana.

Siedemdziesiąt branżowych skilli w pierwszym katalogu byłoby siedemdziesięcioma wierszami, o które nikt nie prosił, w każdym tenancie, przy następnym deployu.

Instalacja półki, z której masz już jeden skill, instaluje resztę i zostawia tamten w spokoju: istniejąca nazwa jest pomijana, a nie nadpisywana, a odpowiedź na żądanie mówi, co zainstalowano, co pominięto i jakiego klucza ten deployment nie dostarcza.

Dodanie do galerii wygląda tak samo jak dodanie dołączonego skilla — katalog z SKILL.md, pod branżą, do której należy — z jedną dodatkową regułą: jego nazwa nie może kolidować z dołączonym skillem ani z innym skillem z galerii, i jest nazwą jego katalogu. Instalacja dopasowuje po nazwie, więc kolizja oznaczałaby ciche pomijanie na zawsze. Test czyta całą siedemdziesiątkę i wywala się na każdym z tych błędów.

Seed tworzy kopie

Zaseedowany skill to zwykły skill należący do organizacji, edytowalny od chwili, w której organizacja istnieje. To kopia, nie link.

To celowe. Sens skilla polega na tym, że szef wsparcia może poprawić politykę zwrotów bez deployu, a żywy link do kopii z repozytorium odebrałby dokładnie to — organizacja czytałaby plik, który może zmienić tylko inżynier.

Edycja i usunięcie są ostateczne w zwykły sposób. Wyłączanie nadal istnieje dla skilla, który organizacja chce zachować, ale nie uruchamiać — respektuje je każdy agent — przestało jednak być jedynym sposobem na pozbycie się built-ina.

Dlaczego biblioteka jest dołączona, a nie pobierana

Dodanie skilla do dostarczanej biblioteki albo do galerii to deploy.

Alternatywa — import z URL-a gita — kosztuje ruch wychodzący z backendu, parser wycelowany w czyjeś repozytorium i obietnicę dotyczącą treści, której nikt tutaj nie przeczytał. Każdy katalog w app/core/catalog/skills/ i app/core/catalog/skill_gallery/ jest tą samą małą obietnicą, którą składa katalog MCP: ktoś na to spojrzał.

Skille czy wiedza?

Odpowiadają na różne pytania, a różnica ma znaczenie, kiedy agent dostanie nie to, co trzeba.

	Skille	Wiedza
Zawiera	Procedurę — jak to robimy	Dokumenty — co wiemy
Pisane przez	Człowieka, świadomie	Wciągane hurtowo
Pobierane przez	Model wybierający nazwę	Wyszukiwanie semantyczne po chunkach
Cytuje	Nic; jest instrukcją	Fragment i jego źródło
Skala	Dziesiątki	Tysiące dokumentów

Co jest czym

„Zwroty powyżej 500 £ wymagają zgody menedżera” to skill. Podpisana umowa, która tak stanowi, to wiedza.

Agent obsługujący zwroty zwykle chce obu naraz, a te dwie capabilities składają się w całość — skills na procedurę, knowledge na dowód.

Dostęp

Skille są zasobami w zakresie organizacji, rządzonymi tak jak agenty i kolekcje: widoczność plus granty na poszczególnych wierszach na wierzchu roli. Zobacz Uprawnienia.

Podpięcie skilla wypożycza go

Każdy run agenta czyta treść i pliki, niezależnie od tego, kto go uruchomił — więc publikacja wymaga, żeby to publikujący miał skills:view na tym wierszu.

To sprawdzenie idzie przez resolve_access, więc grant się liczy: członek, z którym udostępniono jeden skill, może go podpiąć bez awansu roli.

Skill, do którego nie sięga, zostaje odrzucony jako Skill not found: <id>, sformułowane identycznie jak dla id, które nie istnieje. Skille podpina się po UUID z API i z ręcznie edytowanego draftu, a nie tylko wybiera z listy w Builderze, a odrzucenie brzmiące inaczej mapowałoby prywatne skille organizacji, zgadywanie po zgadywaniu.

To samo sprawdzenie działa na skill_ids specjalisty inline i jest raportowane wraz z nazwą specjalisty.

W czasie runa nic nie jest sprawdzane ponownie. Skille z zamrożonego speca są rozwiązywane wewnątrz organizacji runa i wręczane agentowi — zgodnie z regułą, którą kolekcje i delegaci już stosują, że referencja jest sprawdzana raz, przy publikacji.

Alternatywa jest gorsza na dwa konkretne sposoby:

• Każdy kontekst bez podmiotu — klucz API, osadzony widget, wiadomość z kanału — zostaje z założenia odrzucony przez resolve_access, więc sprawdzanie przy każdym uruchomieniu zdarłoby każdy skill dokładnie z tych powierzchni.
• Tam, gdzie podmiot jest, jedna opublikowana wersja dawałaby członkowi — którego rola sięga wyłącznie udostępnionych skilli — chudsze instrukcje niż daje budującemu, a różnica nie byłaby widoczna nigdzie.

Skill usunięty albo wyłączony po publikacji jest pomijany z ostrzeżeniem, zamiast wywracać run. Agent jest mniej zdolny, nie zepsuty.

Podsumowanie

• Skill to procedura, napisana przez człowieka i wczytywana tylko wtedy, gdy model uzna jego description za istotny — wykrywanie kosztuje linijkę na skilla, a treść nie kosztuje nic, dopóki nie zostanie otwarta.
• W workspace'ie skill to także pliki i to właśnie czyni jego skrypty uruchamialnymi.
• Agent proponuje zmianę; człowiek ją stosuje, raz, a decyzja jest ostateczna.
• Podpięcie skilla wypożycza go, więc publikujący musi móc go zobaczyć — a w czasie runa nic nie jest sprawdzane ponownie.
• Galeria to siedemdziesiąt gotowych skilli według branż, instalowanych na życzenie — w odróżnieniu od dołączonej trójki, która przychodzi sama.