Czym są umiejętności agenta i jak działają?
Umiejętność agenta to folder z plikiem SKILL.md ładowanym tylko na żądanie. Dowiedz się, dlaczego to podejście przewyższa jeden wielki prompt i czym różni się od standardu MCP.
Czym w rzeczywistości jest umiejętność agenta
Umiejętność agenta to folder na dysku zawierający plik o nazwie SKILL.md. Plik ten przechowuje nazwę, krótki opis oraz instrukcje zapisane w formacie plain markdown. Agent wczytuje opis podczas uruchamiania, a instrukcje odczytuje tylko wtedy, gdy żądanie użytkownika pasuje do tego opisu lub gdy umiejętność zostanie wywołana z nazwy. Niemal wszystkie pozostałe aspekty działania umiejętności wynikają z tych dwóch zdań.
Folder może zawierać więcej niż jeden plik. Specyfikacja Agent Skills definiuje trzy opcjonalne katalogi: scripts/ na kod wykonywany przez agenta, references/ na dokumenty odczytywane w razie potrzeby oraz assets/ na szablony i dane. Żaden z nich nie jest wymagany. Folder zawierający wyłącznie plik SKILL.md stanowi kompletną umiejętność.
restore-drill/
SKILL.md
references/retention-policy.md
scripts/verify_snapshot.shOpis jest elementem, który bywa niedoceniany. Jest to jedyny tekst, który agent widzi przed podjęciem decyzji o otwarciu umiejętności, dlatego musi on precyzyjnie określać, co umiejętność robi i kiedy należy jej użyć, przy użyciu słów, które faktycznie wpisałby użytkownik.
Dlaczego umiejętność prawie nic nie kosztuje, dopóki nie zostanie użyta
To jest argument, który sprawia, że warto zrozumieć ten format; dotyczy on kontekstu, a nie funkcji. Ładowanie odbywa się etapami, co specyfikacja określa mianem progresywnego ujawniania.
Podczas uruchamiania agent wczytuje name oraz description każdej zainstalowanej umiejętności i nic więcej. Specyfikacja Agent Skills określa to na około 100 tokenów na umiejętność (według wytycznych opublikowanych w październiku 2026). Zainstalowanie tuzina umiejętności zużywa kontekst odpowiadający mniej więcej jednemu długiemu akapitowi.
Gdy żądanie pasuje do opisu, agent odczytuje treść tego jednego SKILL.md. Specyfikacja zaleca, aby treść nie przekraczała 5000 tokenów, a plik 500 linii. Pliki w references/ oraz scripts/ w tym momencie nadal nic nie kosztują. Plik referencyjny jest ładowany tylko wtedy, gdy instrukcje skierują do niego agenta. Dołączony skrypt działa inaczej: agent uruchamia go przez shell, więc kod źródłowy skryptu nigdy nie trafia do okna kontekstu, a jedynie jego wynik.
Należy to porównać z rozwiązaniem, po które ludzie sięgają w pierwszej kolejności, czyli jednym ogromnym promptem. Każda linia w systemowym prompcie lub pliku z instrukcjami działającymi w trybie ciągłym jest opłacana przy każdym żądaniu, w każdej sesji, niezależnie od tego, czy zadanie tego wymaga, czy nie, i konkuruje o uwagę z właściwym pytaniem. Dziesięć tysięcy tokenów stałych instrukcji to rachunek, który płaci się nawet za pytanie o aktualną godzinę. Tuzin umiejętności kosztuje około 1200 tokenów przed aktywacją, ale wczytane instrukcje mogą pozostać w kontekście dla późniejszych zadań w tej samej konwersacji. To jest główny argument przemawiający za umiejętnościami i powód, dla którego mała biblioteka przewyższa długi prompt.
Jedno zastrzeżenie często zaskakuje użytkowników. W Claude Code, gdy umiejętność zostanie wczytana, jej treść pozostaje w konwersacji podczas kolejnych tur, więc długi SKILL.md stanowi koszt powtarzalny, a nie jednorazowy. Kompresja może przyciąć lub usunąć wczytaną zawartość umiejętności. Przenoszenie szczegółów do references/ nie jest kwestią porządku. Jest to mechanizm działający zgodnie z założeniami.
Umiejętność agenta nie jest wywołaniem narzędzia
Narzędzie, nazywane również wywołaniem funkcji, jest elementem, który model może uruchomić. Środowisko uruchomieniowe przesyła modelowi schemat: nazwę, opis oraz strukturę argumentów. Model generuje wywołanie, kod je wykonuje, a wynik wraca jako wiadomość. Narzędzia wykonują operacje. Obie strony tej wymiany należą do środowiska uruchomieniowego, programu obsługującego pętlę wokół modelu, który podczas startu odczytuje opisy umiejętności i decyduje, kiedy je udostępnić.
Umiejętność sama w sobie niczego nie wykonuje. Agent odczytuje ją, a następnie działa przy użyciu narzędzi, które już posiada. Claude Code przyjmuje argumenty podczas wywołania umiejętności i wstawia je do instrukcji poprzez symbole zastępcze, takie jak $ARGUMENTS. Umiejętność może wskazać modelowi, których narzędzi użyć, w jakiej kolejności oraz co sprawdzić po ich użyciu. Przekazanie zadania drugiemu agentowi jest najprostszym przykładem: jedna sesja Claude Code może wysyłać wiadomości do drugiej, a umiejętność jest miejscem, w którym definiuje się, kiedy warto to zrobić i co należy przesłać.
W skrócie: narzędzie nadaje agentowi nową zdolność, a umiejętność głównie dostarcza mu osądu dotyczącego zdolności, które już posiada. Jeśli umiejętność dodaje nową zdolność, robi to poprzez dołączony skrypt, który agent uruchamia w powłoce, którą już dysponuje. Jeśli dany krok musi za każdym razem generować dokładny, zweryfikowany wynik, należy użyć narzędzia lub skryptu. Jeśli dany krok wymaga konsekwentnego stosowania tego samego sposobu myślenia, należy użyć umiejętności. Umiejętność może składać się wyłącznie z osądu i nadal być najczęściej używanym elementem, co pokazuje Ponytail, który wymusza na agencie programistycznym wprowadzanie najmniejszych działających zmian: nie dodaje on nowych możliwości, a jedynie zmienia sposób, w jaki agent korzysta z już posiadanych. Ten osąd może działać również w drugą stronę, a umiejętność unlazy, która przeszukuje drzewo głębokości (Depth Tree), aby powstrzymać agenta przed przedwczesnym uznaniem zadania za wykonane, jest tym samym mechanizmem ukierunkowanym na dokładność, a nie na powściągliwość.
Umiejętność agenta nie jest serwerem MCP
MCP (model context protocol) to protokół służący do łączenia agenta z systemem zewnętrznym. Serwer MCP to proces, który działa, obsługuje ten protokół i udostępnia agentowi narzędzia. Zazwyczaj wymaga on konfiguracji, poświadczeń oraz lokalnego polecenia lub punktu końcowego w sieci. Umiejętność (skill) to folder zawierający plik w formacie markdown. Nie ma tu żadnego procesu, portu ani protokołu.
Koszt kontekstu różni się w analogiczny sposób. Każde narzędzie udostępniane przez serwer MCP posiada nazwę, opis oraz schemat argumentów. W kliencie, który wczytuje je z wyprzedzeniem, dane te znajdują się w żądaniu przez całą sesję, niezależnie od tego, czy są używane. Claude Code domyślnie nie działa już w ten sposób: od października 2026 roku wyszukiwanie narzędzi jest włączone automatycznie, więc na początku sesji ładowane są tylko nazwy narzędzi i instrukcje serwera, a pełne definicje docierają dopiero wtedy, gdy Claude ich poszukuje. Umiejętność w stanie spoczynku to jedna linia tekstu.
Oba rozwiązania się uzupełniają, a najskuteczniejsze konfiguracje wykorzystują oba jednocześnie. Serwer MCP zapewnia dostęp. Umiejętność określa procedurę: które z tych narzędzi wywołać w rzeczywistym przepływie pracy zespołu, w jakiej kolejności i jak powinien wyglądać poprawny rezultat. Jeśli hostujesz własne rozwiązania, uruchamianie serwerów MCP na VPS opisuje ten aspekt.
Umiejętność agenta nie jest promptem systemowym ani plikiem AGENTS.md
Oba te elementy to instrukcje w formacie markdown, więc takie nieporozumienie jest zrozumiałe. Różnica polega na momencie ich ładowania. Prompt systemowy oraz instrukcje projektu ładowane przy starcie są aktywne zawsze; zagnieżdżone pliki AGENTS.md oraz CLAUDE.md ładują się, gdy agent pracuje w ich katalogach. Umiejętność jest wywoływana na żądanie. Style wyjściowe w Claude Code znajdują się na drugim końcu spektrum zawsze aktywnych elementów, ponieważ wybór jednego z nich modyfikuje sam prompt systemowy, dzięki czemu kształtuje on każdą odpowiedź w sesji, w tym te, których nie dotyczy żadna umiejętność.
Testem jest jedno pytanie: czy zignorowanie tego akapitu byłoby błędem w zadaniu, które nie ma z nim nic wspólnego? Styl redakcyjny, polecenie budowania oraz zasada nazewnictwa gałęzi dotyczą każdego zadania, więc należą do pliku zawsze aktywnego, gdzie ich każdorazowe ładowanie jest zamierzone. Lista kontrolna wydania, którą wykonujesz dwa razy w miesiącu, nie dotyczy każdego zadania, więc należy do umiejętności. Gdy sekcja pliku zawsze aktywnego rozrośnie się do postaci numerowanej procedury, jest to sygnał, aby ją przenieść.
Te pliki mają własne konwencje, które warto poprawnie wdrożyć. Zobacz co należy umieścić w AGENTS.md, a co w pliku użytkownika oraz plik design.md wyjaśniający strukturę bazy kodu, aby poznać dwa stosowane przez nas rozwiązania.
Czym jest minimalna umiejętność
W Claude Code umiejętności osobiste znajdują się w ~/.claude/skills/<name>/SKILL.md i dotyczą wszystkich projektów na danej maszynie, ale nie obejmują Cowork ani sesji w chmurze. Umiejętności projektowe znajdują się w .claude/skills/<name>/SKILL.md i są zatwierdzane w git, dzięki czemu zespół również z nich korzysta; wątki w chmurze w projekcie Claude nie wczytują ich. GitHub Copilot oraz VS Code odczytują umiejętności projektowe z .github/skills/ i .agents/skills/, a także z .claude/skills/. Plik wewnątrz jest tym samym plikiem.
mkdir -p ~/.claude/skills/restore-drill---
name: restore-drill
description: Run a restic restore drill and report what was recovered. Use when the user asks to test backups, verify a restore, or check that a snapshot is readable.
---
# Restore drill
1. Run `restic snapshots` and pick the newest snapshot for the host in question.
2. Restore it into a scratch directory under `/tmp`, never over live data.
3. Compare the restored file count and total size against the snapshot summary.
4. Report the snapshot ID and anything that failed to restore.
If `restic snapshots` reports that it cannot open the config file, stop and report the full error instead of guessing the cause.To jest kompletna umiejętność. Nazwa katalogu staje się poleceniem, które wpisujesz, więc w tym przypadku jest to /restore-drill. W Claude Code menu /skills wyświetla listę zainstalowanych elementów, co jest najszybszym sposobem na potwierdzenie, że plik został wykryty. Jeśli brakuje go w tym menu, najpierw sprawdź nazwy: plik musi nazywać się SKILL.md, a specyfikacja Agent Skills wymaga, aby nazwa składała się z małych liter, cyfr i pojedynczych myślników, zgodnie z nazwą katalogu. Ta sama procedura zapisana jako instrukcja, którą agent może uruchomić ponownie, stanowi naturalne uzupełnienie zaplanowanych kopii zapasowych restic na VPS, gdzie proces tworzenia kopii zapasowej nie jest tożsamy z procesem jej przywracania.
Kiedy umiejętność powinna być skryptem
Każde zadanie, które zawsze posiada jedną poprawną odpowiedź, powinno być realizowane za pomocą skryptu. Umiejętność należy wówczas ograniczyć do kilku wierszy instrukcji określających, kiedy uruchomić skrypt i jak zinterpretować jego wynik. Istnieją dwa powody takiego podejścia, oba o charakterze praktycznym.
Po pierwsze, kod źródłowy skryptu nie zajmuje miejsca w oknie kontekstowym. Parser o długości 300 wierszy generuje jedynie wynik, podczas gdy ta sama logika zapisana w formie instrukcji markdown za każdym razem obciąża kontekst swoją pełną długością.
Po drugie, skrypt zapewnia powtarzalność wyników. Model poproszony o ponowne wyprowadzenie tej samej reguły parsowania logów przy każdym uruchomieniu może w gorszy dzień wygenerować nieco inny wynik, a błąd zostanie zauważony dopiero w momencie rozbieżności danych.
Dlatego należy rozdzielić pracę według jej charakteru. Zadanie typu „przeanalizuj plik CSV i wypisz każdy wiersz, w którym suma nie zgadza się z pozycjami” powinno być skryptem. Zadanie typu „przejrzyj wiersze wypisane przez skrypt i wyjaśnij, które z nich wyglądają na błąd wprowadzania danych” jest instrukcją umiejętności. Utrzymywanie oceny w markdownie, a determinizmu w kodzie, to ta sama dyscyplina, co tworzenie pętli, którą agent może uruchomić bez nadzoru.
Dlaczego moja umiejętność nigdy się nie uruchamia?
Ponieważ jej description określa, co umiejętność robi, ale nie wskazuje, kiedy należy jej użyć. Ta jedna linijka to jedyny element, do którego agent może dopasować żądanie użytkownika. Opis „pomaga w pracy z bazą danych” nie pasuje do niczego konkretnego. Opis „uruchamia migrację schematu w bazie danych staging. Użyj, gdy użytkownik prosi o migrację tabeli, dodanie kolumny lub zmianę schematu” zawiera słowa, które faktycznie wpisuje użytkownik, więc wyzwalacz zadziała.
Odwrotnym błędem jest umiejętność, która uruchamia się bez przerwy. Opis typu „użyj do wszelkich zmian w kodzie w tym repozytorium” pasuje do wszystkiego, więc treść ładuje się przy każdym zadaniu i pozostaje w konwersacji przez kolejne tury. Należy zawęzić opis do konkretnego przypadku użycia. W Claude Code można również ustawić disable-model-invocation: true w sekcji frontmatter, co wyłącza automatyczne ładowanie i sprawia, że umiejętność jest dostępna tylko po wpisaniu jej nazwy.
Trzecim błędem jest umiejętność, która powiela narzędzie. Instrukcje nakazujące agentowi curl API, które jest już udostępnione przez serwer MCP, lub przeszukiwanie plików za pomocą grep, gdy środowisko posiada narzędzie wyszukiwania, prowadzą do wolniejszego działania i dwóch zestawów sprzecznych instrukcji. Należy usunąć duplikat i opisać zamiast tego intencję.
Nie należy zgadywać, który z tych trzech problemów występuje. Należy uruchomić to samo polecenie dwukrotnie w nowej sesji: raz z włączoną umiejętnością, a raz z wyłączoną, a następnie porównać odpowiedzi. Nowa sesja jest kluczowa, ponieważ sesja, w której tworzono umiejętność, zawiera już wszystkie informacje z jej opisu, co maskuje braki w zapisanej wersji. Wtyczka skill-creator od Anthropic automatyzuje to porównanie wewnątrz Claude Code, w tym generuje polecenia, które powinny i nie powinny wyzwalać umiejętności, oraz mierzy skuteczność każdego z nich. Jeśli umiejętność się ładuje, a agent nadal nie wykonuje poleceń, problem nie leży w opisie i należy sprawdzić przyczyny, dla których agent ignoruje przeczytane instrukcje.
Czy jest to format jednego dostawcy, czy standard?
Firma Anthropic opublikowała ten format pod koniec 2025 roku, a następnie udostępniła go jako otwarty standard hostowany w serwisie agentskills.io. 22 października 2026 roku Anthropic ogłosiło przekazanie Agent Skills na rzecz Agentic AI Foundation działającej w ramach Linux Foundation. Według stanu na październik 2026 roku specyfikacja ta definiuje wymagane pola name i description, opcjonalne pola license, compatibility, metadata i allowed-tools, trzy opcjonalne katalogi oraz zachowanie ładowania etapowego. Dostarczany jest również referencyjny walidator, dzięki czemu skills-ref validate ./my-skill sprawdza folder pod kątem zgodności ze specyfikacją przed jego udostępnieniem.
Lista klientów stanowi rzeczywisty wyznacznik. Ten sam folder jest odczytywany między innymi przez Claude Code, Cursor, OpenAI Codex, Gemini CLI, GitHub Copilot, VS Code, Goose, OpenHands oraz opencode. Microsoft publikuje własne umiejętności w tym formacie pod adresem github.com/microsoft/skills i dostarcza narzędzie desktopowe o nazwie Skill Recorder. Narzędzie to monitoruje wykonanie zadania, rekonstruuje je jako intencję wraz z uporządkowanymi krokami i zapisuje wynik w postaci umiejętności. Fakt, że dostawca tworzy rejestrator, którego format wyjściowy należy do specyfikacji innego podmiotu, jest wyraźnym sygnałem, że format przestał być funkcją jednego produktu.
Od czego zacząć
Nie planuj biblioteki. Poczekaj, aż złapiesz się na tym, że wklejasz te same instrukcje do czatu po raz trzeci, a następnie przenieś ten tekst do SKILL.md i usuń wklejkę. Powtarzalność, którą już odczułeś, jest jedynym wiarygodnym wyzwalaczem umiejętności wartej zachowania. Procedura wyszukiwania jest dobrym pierwszym krokiem, a umiejętność wyszukiwania wspierana przez własną instancję SearXNG pokazuje jej kształt.
Dwa nawyki utrzymują bibliotekę w dobrym stanie. Przeczytaj każdą umiejętność, której sam nie napisałeś, zanim ją zainstalujesz, wliczając w to skrypty, ponieważ umiejętność to instrukcje, które wykona Twój agent, oraz kod, który może uruchomić: traktuj to jak instalację oprogramowania od nieznajomego. Trzymaj również poświadczenia poza folderem, ponieważ umiejętność to plik tekstowy, który jest zatwierdzany i udostępniany. Trzymanie sekretów z dala od agentów opisuje, gdzie powinny znajdować się te wartości, a mapa drogowa nauki agentów na ten rok porządkuje umiejętności w kontekście reszty konfiguracji.
FAQ
Jaka jest różnica między umiejętnością agenta a serwerem MCP?
Serwer MCP (Model Context Protocol) to działający proces, który udostępnia narzędzia agentowi za pośrednictwem protokołu. Wymaga on konfiguracji i danych uwierzytelniających, a jego pełne definicje narzędzi zajmują kontekst przez całą sesję, chyba że klient je odroczy, co Claude Code robi obecnie domyślnie. Umiejętność agenta to folder zawierający plik SKILL.md, niewymagający procesu ani protokołu. Kosztuje ona około 100 tokenów, dopóki agent nie zdecyduje się jej odczytać. Użyj serwera MCP, aby zapewnić agentowi dostęp do systemu. Użyj umiejętności, aby przekazać agentowi procedurę poprawnego korzystania z tego dostępu. Wiele konfiguracji wykorzystuje oba te rozwiązania.
Czy umiejętności agenta działają tylko z Claude Code?
Nie. Firma Anthropic opracowała ten format, a następnie udostępniła go jako otwarty standard na stronie agentskills.io. Ten sam folder jest odczytywany przez Cursor, OpenAI Codex, Gemini CLI, GitHub Copilot, VS Code, Goose, OpenHands oraz inne klienty. Różnice polegają na tym, gdzie dany klient szuka plików oraz które dodatkowe pola frontmatter rozumie. Claude Code odczytuje ~/.claude/skills/ oraz .claude/skills/, podczas gdy GitHub Copilot i VS Code odczytują .github/skills/, .claude/skills/ lub .agents/skills/ w repozytorium. Sam plik SKILL.md pozostaje niezmieniony przy przenoszeniu między nimi.
Ile umiejętności można zainstalować, zanim wpłynie to na wydajność?
Ograniczeniem jest budżet startowy, a nie liczba plików. Każda zainstalowana umiejętność wnosi swoją nazwę i opis, co zgodnie z opublikowanymi wytycznymi specyfikacji zajmuje około 100 tokenów. Trzydzieści umiejętności kosztuje więc około 3000 tokenów, zanim którakolwiek z nich zostanie użyta. Jako pierwsze pogarsza się dopasowanie, a nie szybkość: wiele umiejętności z nakładającymi się opisami utrudnia modelowi wybór właściwej. Należy tworzyć opisy, które się nie pokrywają, i usuwać nieużywane umiejętności.
Czy ta instrukcja powinna znaleźć się w umiejętności czy w AGENTS.md?
Zadaj sobie pytanie, czy dotyczy ona każdego zadania w repozytorium. Polecenia budowania, styl dokumentacji i zasady nazewnictwa dotyczą wszystkich zadań, więc powinny znajdować się w pliku zawsze aktywnym, gdzie ich każdorazowe ładowanie jest zamierzone. Procedura wykonywana sporadycznie, taka jak lista kontrolna wydania lub ćwiczenie przywracania danych, powinna być umiejętnością. Kosztuje ona wtedy tylko tyle, co jej jedno-wierszowy opis przed aktywacją. Po załadowaniu w Claude Code jej instrukcje pozostają w konwersacji przez kolejne tury, nawet w przypadku niezwiązanych zadań. Sekcja pliku AGENTS.md, która rozrosła się do postaci numerowanych kroków, jest zazwyczaj umiejętnością czekającą na przeniesienie.