Czym w rzeczywistości jest umiejętność agenta?

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, natomiast instrukcje odczytuje tylko wtedy, gdy żądanie użytkownika pasuje do tego opisu. Prawie 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.sh

Opis jest elementem, który jest często 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 argument, który sprawia, że zrozumienie tego formatu jest istotne; dotyczy on kontekstu, a nie funkcji. Ładowanie odbywa się etapami, co specyfikacja określa mianem stopniowego ujawniania (progressive disclosure).

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 sierpniu 2026 roku). Instalacja tuzina umiejętności zużywa mniej więcej tyle kontekstu, co jeden długi akapit.

Gdy żądanie pasuje do opisu, agent odczytuje treść tego jednego SKILL.md. Specyfikacja zaleca utrzymywanie treści poniżej 5000 tokenów, a pliku poniżej 500 linii. Pliki w references/ oraz scripts/ w tym momencie nadal nic nie kosztują. Plik referencyjny ładuje się 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.

Teraz porównaj to 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łacisz nawet za pytanie o aktualną godzinę. Tuzin umiejętności kosztuje około 1200 tokenów w stanie spoczynku i rozszerza się tylko na potrzeby tego jednego zadania, które ich wymaga. To cały sens stosowania umiejętności i powód, dla którego mała biblioteka przewyższa długi prompt.

Jedno zastrzeżenie często zaskakuje użytkowników. Gdy umiejętność zostanie załadowana, jej treść pozostaje w kontekście przez resztę sesji, więc długi SKILL.md stanowi koszt powtarzalny, a nie jednorazowy. Przenoszenie szczegółów do references/ nie jest kwestią porządku. 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, to element, który model może uruchomić. Środowisko uruchomieniowe przesyła modelowi schemat: nazwę, opis oraz strukturę argumentów. Model generuje wywołanie, kod użytkownika je wykonuje, a wynik wraca w postaci komunikatu. Narzędzia wykonują operacje.

Umiejętność nie wykonuje samodzielnie żadnych działań. Agent odczytuje ją, a następnie działa, wykorzystując posiadane już narzędzia. Model nie może przekazywać argumentów do umiejętności w taki sam sposób, jak robi to w przypadku narzędzi. Umiejętność pozwala natomiast wskazać modelowi, których narzędzi użyć, w jakiej kolejności oraz co należy sprawdzić po ich użyciu.

W skrócie: narzędzie zapewnia agentowi nową zdolność, a umiejętność nadaje mu zdolność oceny posiadanych już umiejętności. 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 ograniczać się wyłącznie do oceny, a mimo to być najczęściej wykorzystywanym elementem, co pokazuje Ponytail, który wymusza na agencie programistycznym wprowadzanie najmniejszych możliwych zmian, które działają: nie dodaje ona żadnych nowych możliwości, a jedynie zmienia sposób, w jaki agent korzysta z tych, które już posiada.

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, danych uwierzytelniających 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 ten sam sposób. Każde narzędzie udostępniane przez serwer MCP posiada nazwę, opis oraz schemat argumentów; domyślnie znajdują się one w żądaniu przez całą sesję, niezależnie od tego, czy są używane. Niektórzy klienci zaczęli pobierać schematy narzędzi na żądanie, jednak ich ładowanie z wyprzedzeniem pozostaje standardem. Umiejętność w stanie spoczynku to jedna linia tekstu.

Oba rozwiązania wzajemnie się uzupełniają, a najskuteczniejsze konfiguracje wykorzystują oba jednocześnie. Serwer MCP zapewnia dostęp. Umiejętność definiuje procedurę: które z tych narzędzi wywołać w rzeczywistym przepływie pracy zespołu, w jakiej kolejności oraz jak wygląda poprawny wynik. W przypadku samodzielnego hostowania, uruchamianie serwerów MCP na VPS opisuje ten aspekt zagadnienia.

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. AGENTS.md, CLAUDE.md oraz prompt systemowy są zawsze aktywne. Umiejętność jest ładowana na żądanie.

Test sprowadza się do jednego pytania: 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 ładowanie przy każdej operacji jest pożądane. Lista kontrolna wydania, którą wykonuje się dwa razy w miesiącu, nie dotyczy każdego zadania, więc należy do umiejętności. Gdy sekcja pliku zawsze aktywnego rozrasta się do postaci numerowanej procedury, jest to sygnał do jej przeniesienia.

Te pliki mają własne konwencje, które warto stosować poprawnie. Zobacz co należy do AGENTS.md, a co do pliku dla człowieka oraz design.md wyjaśniający strukturę bazy kodu, aby poznać dwa standardy, z których korzystamy.

Jak wygląda minimalna umiejętność

W Claude Code umiejętności osobiste znajdują się w ~/.claude/skills/<name>/SKILL.md i dotyczą wszystkich projektów. Umiejętności projektowe znajdują się w .claude/skills/<name>/SKILL.md i są zatwierdzane w git, dzięki czemu posiada je każda osoba oraz każdy agent pracujący w danym repozytorium. GitHub Copilot oraz VS Code odczytują umiejętności obszaru roboczego z .github/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` prints `Fatal: unable to open config file`, the repository path or the password is wrong. Stop and report that instead of guessing.

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, nazwa jest nieprawidłowa: plik musi nazywać się SKILL.md, a nazwa katalogu musi składać się z małych liter, cyfr i pojedynczych myślników. Ta sama procedura zapisana jako instrukcja, którą agent może uruchomić ponownie, stanowi naturalne uzupełnienie zaplanowanych kopii zapasowych restic na VPS, gdzie uruchomienie kopii zapasowej nie jest tożsame z jej przywracaniem.

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 na bazie stagingowej. 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ść umiejętności jest ładowana przy każdym zadaniu i pozostaje w kontekście przez resztę sesji. 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 dubluje narzędzie. Instrukcje nakazujące agentowi użycie curl API, które jest już udostępniane przez serwer MCP, lub przeszukiwanie plików za pomocą grep, gdy środowisko posiada własne narzędzie wyszukiwania, prowadzą do wolniejszego działania i wprowadzają dwa zestawy sprzecznych instrukcji. Należy usunąć duplikat i zamiast tego opisać intencję.

Nie należy zgadywać, który z tych trzech problemów występuje. Należy uruchomić ten sam prompt 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 jej założenia, co maskuje braki w zapisanej dokumentacji. Wtyczka skill-creator od Anthropic automatyzuje to porównanie wewnątrz Claude Code, w tym generuje prompty, które powinny i nie powinny wyzwalać umiejętności, oraz mierzy skuteczność każdego z nich.

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 witrynie agentskills.io. Według stanu na sierpień 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. Zawiera ona 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. Firma 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. Rejestruje ono wykonanie zadania, rekonstruuje je jako intencję wraz z uporządkowanymi krokami i zapisuje wynik w postaci umiejętności. Fakt, że dostawca buduje 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 (agent skill) 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 definicje narzędzi zazwyczaj zajmują miejsce w kontekście przez całą sesję, niezależnie od tego, czy są używane. Umiejętność agenta to folder zawierający plik SKILL.md, niewymagający osobnego procesu ani protokołu. Kosztuje ona około 100 tokenów, dopóki agent nie zdecyduje się jej odczytać. Serwera MCP należy używać, aby zapewnić agentowi dostęp do systemu. Umiejętności należy używać, aby przekazać agentowi procedurę poprawnego korzystania z tego dostępu. W wielu konfiguracjach stosuje się oba rozwiązania jednocześnie.

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 jakie dodatkowe pola frontmatter obsługuje. Claude Code odczytuje ~/.claude/skills/ oraz .claude/skills/, podczas gdy GitHub Copilot i VS Code odczytują .github/skills/ w repozytorium. Sam plik SKILL.md pozostaje między nimi niezmieniony.

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ść dodaje swoją nazwę i opis, co zgodnie z wytycznymi specyfikacji zajmuje około 100 tokenów. Trzydzieści umiejętności kosztuje więc około 3 000 tokenów, zanim jeszcze którakolwiek z nich zostanie użyta. Pierwszym problemem nie jest szybkość, lecz dopasowanie: 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ą, oraz usuwać nieużywane umiejętności.

Czy ta instrukcja powinna znaleźć się w umiejętności, czy w AGENTS.md?

Należy zadać sobie pytanie, czy dotyczy ona każdego zadania w repozytorium. Polecenia budowania, styl kodu i zasady nazewnictwa dotyczą wszystkich zadań, więc powinny znajdować się w pliku zawsze aktywnym, gdzie ich każdorazowe ładowanie jest uzasadnione. Procedura wykonywana sporadycznie, taka jak lista kontrolna wydania (release checklist) lub ćwiczenie przywracania danych, powinna być umiejętnością, aby nie generować kosztów przy zadaniach, które jej nie wymagają. Sekcja pliku AGENTS.md, która rozrosła się do postaci numerowanych kroków, zazwyczaj jest umiejętnością czekającą na wydzielenie.