Poradnik · 6.11.2026

AI agent skills: jak uczymy agenta nowych zadań (rozbiór skilla)

Czym są skille agenta AI i jak je pisać? Rozbieram nasz skill do sprawozdań z KRS: 735 linii, 6 skryptów, pułapki i wzór do skopiowania.

Grzegorz Ciupek 10 min czytania 7 źródeł Skomentuj
Okładka: skill agenta AI od środka, 735 linii w naszym skillu do sprawozdań z KRS
Odpowiedź w skrócie · stan na 04.11.2026
  • Skill agenta AI to folder z plikiem SKILL.md: nagłówek z polami name (do 64 znaków) i description (do 1024 znaków), pod nim instrukcja, a obok opcjonalne katalogi scripts/, references/ i assets/. Ten sam format (otwarty standard agentskills.io, sprawdzony 04.11.2026) czytają Claude Code i Hermes Agent.
  • Na starcie agent widzi tylko nazwę i opis każdego skilla, około 100 tokenów na skill według dokumentacji Anthropic. Resztę ładuje, gdy zadanie pasuje do opisu. Dlatego to description, a nie instrukcja, decyduje, czy skill w ogóle się uruchomi.
  • Rozebrałem nasz skill do KRS i e-sprawozdań: 735 linii SKILL.md, opis 668 znaków, 6 skryptów pomocniczych, 10 sekcji głównych i 8 ostrzeżeń (odczyt 04.11.2026). Przykładowy wynik jego pracy: bankobranie.pl w 2024 roku miało 5 531 446 zł przychodu i 3 600 029 zł zysku netto.
  • Słaby punkt: 735 linii to o 235 więcej niż zalecane 500. Nasz skill koszykowy ma 118 linii i 26 plików obok, i to lepszy wzór podziału.
Spis treści · 8 części
  1. 01AI agent skills: co to jest skill agenta i jak agent z niego korzysta?
  2. 02Jak wygląda prawdziwy skill agenta AI? Rozbiór naszego skilla do sprawozdań z KRS
  3. 03Co skill agenta robi w praktyce? Przykład: sprawozdania bankobranie.pl
  4. 04Jak napisać skill agenta AI krok po kroku?
  5. 05Ile powinien mieć skill agenta? Porównanie trzech skilli naszej floty
  6. 06Czego unikać przy pisaniu skilli agenta AI?
  7. 07Najczęstsze pytania
  8. 08Źródła

Ten tekst jest dla kogoś, kto ma już agenta AI (Claude Code, Hermes albo inne narzędzie zgodne ze standardem) i chce go nauczyć pracy, której model sam nie zna: procedury urzędowej, panelu sklepu, własnego API. Pokazuję prawdziwy skill do sprawozdań finansowych spółek z KRS, policzony linijka po linijce.

Jak skille trafiają do 17 instancji Hermesa, opisałem w tekście Hermes: nasz agent AI od środka. Tu schodzę niżej: co jest w jednym skillu i jak go napisać.

AI agent skills: co to jest skill agenta i jak agent z niego korzysta?

Skill agenta AI to zapisana w pliku SKILL.md procedura jednego rodzaju zadania, którą agent ładuje dopiero wtedy, gdy prośba pasuje do opisu skilla. Według specyfikacji agentskills.io i dokumentacji Anthropic (sprawdzone 04.11.2026) wymagane są tylko dwa pola nagłówka: name do 64 znaków i description do 1024 znaków.

Ładowanie ma trzy poziomy. Pierwszy to nazwa i opis, obecne w kontekście zawsze, około 100 tokenów na skill. Drugi to treść SKILL.md, wczytywana po dopasowaniu; dokumentacja zaleca do 5 000 tokenów i 500 linii. Trzeci to pliki z scripts/, references/ i assets/, otwierane, gdy instrukcja każe po nie sięgnąć.

Instrukcja agenta obowiązuje zawsze, skill tylko przy swoim zadaniu. Gdzie leżą pliki, zależy od narzędzia: Claude Code czyta skille osobiste z ~/.claude/skills/ i projektowe z .claude/skills/, a Hermes z ~/.hermes/skills/. Hermes ma też polecenie /learn, które samo składa skill z materiałów; od niego zaczynałem w poradniku agent AI: jak stworzyć pierwszego bez programowania.

Skill a serwer MCP

Skill to wiedza: kolejność kroków, pułapki, gotowe polecenia. Serwer MCP to dostęp: narzędzie, którym agent faktycznie coś wywołuje. Dobry skill często mówi agentowi, którego narzędzia MCP użyć i w jakiej kolejności. Różnicę rozpisałem w tekście MCP server: co to jest.

Jak wygląda prawdziwy skill agenta AI? Rozbiór naszego skilla do sprawozdań z KRS

Prawdziwy skill agenta AI, którego używamy do spraw rejestrowych, nazywa się dokumenty-rejestrowe-krs i 04.11.2026 miał 735 linii w SKILL.md, opis długości 668 znaków oraz 6 skryptów w katalogu scripts/. Pracuje u nas w Claude Code; format jest zgodny ze standardem, więc ten sam folder przeczyta Hermes.

735linii SKILL.md (zalecane poniżej 500)
668znaków opisu z limitu 1024
6skryptów pomocniczych, razem 404 linie
8ostrzeżeń oznaczonych w treści
Anatomia skilla dokumenty-rejestrowe-krs, stan na 04.11.2026 (odczyt plików)
ParametrWartośćCo z tego wynika
Pola nagłówka2Tylko name i description, bez pól opcjonalnych
Długość opisu668 znaków / 90 słów65% limitu; opis wylicza 9 sytuacji, w których skill ma się uruchomić
Linie SKILL.md73547% ponad zalecane 500 linii
Rozmiar SKILL.md36,7 KB, 4 517 słów treściPolskie słowo to zwykle więcej niż jeden token, więc zalecane 5 000 tokenów jest przekroczone
Sekcje10 głównych, 27 podsekcjiKolejność: 1, 2, 2A, 3, 3A, 3B, 4, 5, 3C, 3D
Bloki kodu do skopiowania17Gotowe zapytania curl i fragmenty Pythona
Skrypty4 w Pythonie, 2 w powłoceAudyt zaległości, odczyt e-SF, pobranie akt, porządek nazw plików, składanie pism do PDF i DOCX
Zakazy w sekcji „Czego nie robić”6Każdy zaczyna się od „Nie” i ma uzasadnienie
Historia według dat plików25.08–21.09.2026Skill rósł przez dopisywanie przez blisko 4 tygodnie

Nagłówek: nazwa i opis, które decydują o uruchomieniu

Szkielet folderu i początek pliku wyglądają tak (opis skrócony):

dokumenty-rejestrowe-krs/
├── SKILL.md            # 735 linii
└── scripts/            # 4 × .py, 2 × .sh

---
name: dokumenty-rejestrowe-krs
description: Pobieranie danych i dokumentów spółek z KRS, z Repozytorium
  Dokumentów Finansowych (RDF) i z akt rejestrowych (RAR) … Użyj, gdy trzeba
  sprawdzić stan rejestrowy spółki, ustalić które sprawozdania złożono,
  a których brakuje, pobrać sprawozdanie finansowe …, odczytać plik e-SF …
---

Opis ma dwie części, jak zaleca dokumentacja: co skill robi i kiedy go użyć. Druga to słowa, które padają w moich prośbach: „sprawozdanie”, „uchwała”, „e-SF”, „zarząd”, „zawieszenie”. Agent porównuje prośbę z opisem, nie z treścią, więc słowa spoza opisu praktycznie nie istnieją.

Kroki: najpierw to, co działa najprościej

Treść zaczyna się od rozróżnienia, które oszczędza najwięcej czasu: dane rejestrowe idą przez otwarte API KRS zwykłym curl, a pliki sprawozdań leżą w RDF za ochroną przed botami i wymagają przeglądarki. Dalej są procedury dla obu systemów, terminy (sporządzenie do 31.03, zatwierdzenie do 30.06, złożenie w ciągu 15 dni) i odczyt XML skryptem czytaj-esf.py, który odcina podpis elektroniczny, czyli większość pliku.

Pułapki: najcenniejsza część skilla

Osiem miejsc oznaczonych ostrzeżeniem opisuje pułapki objawem, a nie ogólnikiem. Przykład: pobranie dokumentu z akt rejestrowych z przekierowaniami zwraca 3 869 bajtów HTML zamiast PDF-a, więc skill każe rozpoznawać błąd po rozmiarze pliku. Inny: w bilansie e-SF KwotaA to rok bieżący, a KwotaB poprzedni. Pomyłka odwraca porównanie rok do roku.

Co skill agenta robi w praktyce? Przykład: sprawozdania bankobranie.pl

W praktyce skill do KRS zamienia pytanie „ile zarabia ta firma?” w powtarzalną procedurę: API KRS pokazuje, które sprawozdania złożono, RDF daje plik e-SF, a skrypt wyciąga z niego kwoty. Tak ustaliliśmy, że DAJMI Dawid Jakś S.K.A. (KRS 0000946509), wydawca bankobranie.pl, miała w 2024 roku 5 531 446 zł przychodu.

Pierwszy krok skilla powtórzyłem 04.11.2026 jednym zapytaniem do API KRS. Odpis aktualny (stan z 26.02.2026) wymienia 4 złożone sprawozdania roczne: za 2022 rok (złożone 16.02.2023), za 2023 (21.03.2024), za 2024 (18.02.2025) i za 2025 (25.02.2026). Dział 6 jest pusty: bez zawieszenia i likwidacji. Wszystko bez przeglądarki.

DAJMI Dawid Jakś S.K.A. (bankobranie.pl) według e-sprawozdań z RDF; wyliczenia własne, stan na 04.11.2026
Pozycja20232024Zmiana
Przychód3 305 197 zł5 531 446 zł+2 226 249 zł (+67,4%)
Zysk netto2 044 221 zł3 600 029 zł+1 555 808 zł (+76,1%)
Zysk netto jako % przychodu61,8%65,1%+3,3 pkt proc.

Wyliczenie: 3 600 029 zł dzielone przez 5 531 446 zł daje 0,651, czyli z każdej złotówki przychodu w 2024 roku zostało 65 groszy zysku netto. Sprawozdanie za 2025 rok jest w rejestrze, ale jego kwot jeszcze nie odczytałem, więc ich nie podaję.

U nas

Liczby bankobranie.pl z tej tabeli są w naszym rejestrze faktów i wracają w serii o tym, ile zarabia polski internet. Skill sprawia, że kolejną spółkę sprawdzam tą samą drogą, a nie od szukania, gdzie w odpowiedzi API jest dział 3.

Jak napisać skill agenta AI krok po kroku?

Skill agenta AI piszesz w ośmiu krokach: wybór zadania, które zrobiłeś już ręcznie, opis z sytuacjami uruchomienia, kroki z gotowymi poleceniami, pułapki z objawami, skrypty dla części powtarzalnych, podział na pliki powyżej 500 linii, zakazy i test w nowej sesji. Tak dziś zbudowałbym skill do KRS od zera (04.11.2026).

  1. Wybierz zadanie, które już zrobiłeś z agentem. Skill napisany przed pierwszym przejściem zadania to zgadywanie; skill po nim to protokół tego, co zadziałało.
  2. Napisz opis: co robi i kiedy go użyć. Pierwsze zdanie mówi, co skill robi, w trzeciej osobie albo bezosobowo. Drugie zaczyna się od „Użyj, gdy…” i wylicza sytuacje słowami, których naprawdę używasz w prośbach. Zmieść się w 1024 znakach; nasze opisy mają od 572 do 889 znaków.
  3. Ułóż kroki w kolejności wykonywania. Każdy z poleceniem do skopiowania, nie z opisem polecenia. Skill do KRS ma 17 bloków kodu.
  4. Dopisz pułapki z objawem. Nie „uważaj na błędy pobierania”, tylko „plik ma dokładnie 3 869 bajtów, to strona, nie dokument”. Agent rozpozna objaw, ogólnika nie.
  5. Przenieś do skryptów to, co musi wyjść zawsze tak samo. Odczyt XML, terminy, nazwy plików. Do kontekstu trafia tylko wynik skryptu.
  6. Podziel skill, zanim przekroczy 500 linii. W SKILL.md zostaw kroki i tabelę „co otworzyć, gdy…”, a szczegóły przenieś do references/. Tego w skillu do KRS nie zrobiliśmy i to jego największa wada.
  7. Napisz sekcję „Czego nie robić”. Krótkie zakazy z powodem, np. nie przepisuj kwot ze zrzutu ekranu, nie publikuj pobranych dokumentów, bo zawierają dane osobowe.
  8. Przetestuj w nowej sesji, bez nazwy skilla w prośbie. Napisz tak, jak naprawdę piszesz: „sprawdź, czy ta spółka złożyła sprawozdania”. Jeśli agent nie sięgnie po skill sam, poprawiasz opis, nie treść.

Ile powinien mieć skill agenta? Porównanie trzech skilli naszej floty

Skill agenta powinien mieć w SKILL.md tyle, ile trzeba do przejścia zadania, a resztę w plikach pomocniczych. Nasze trzy skille z 04.11.2026 pokazują dwie drogi: skill do KRS trzyma wszystko w jednym pliku (735 linii), a skille koszykowy i sklepowy mają 118 i 135 linii plus odpowiednio 26 i 4 pliki obok.

Skill sklepy-gapli dotyczy platformy sklepów, którą współtworzę.

Trzy skille naszej floty, stan na 04.11.2026 (odczyt plików)
SkillLinie SKILL.mdOpis (znaki)Sekcje głównePliki obokWzór do skopiowania
dokumenty-rejestrowe-krs735668106 skryptówPułapki opisane objawem
koszyk-wzorcowy118889621 zasobów, 3 opisy, 2 skryptyTabela „Czytaj wybiórczo”
sklepy-gapli13557283 opisy, 1 skrypt (554 linie razem)Bramka przed operacją nieodwracalną

Skill koszykowy ma najkrótszą treść i najwięcej plików, bo jego sedno to gotowy kod motywów sklepu. SKILL.md kończy tabela: budujesz koszyk, otwórz plik wdrożenia; coś się psuje, otwórz plik pułapek; audyt, uruchom skrypt. Agent czyta tylko to, czego robota wymaga.

Skill sklepowy uczy bramki: wylicza cztery operacje nieodwracalne (publikacja i kończenie ofert, usuwanie produktów, zmiana zestawów) i przed każdą każe zrobić próbę na sucho, pokazać liczby i czekać na zgodę. Jeśli nie prowadzisz sklepu na platformie GAPLI, sam skill nic Ci nie da, bo opisuje jej API. Weź z niego tylko wzór bramki, bo działa przy każdym narzędziu, które może coś skasować albo opublikować.

Czego unikać przy pisaniu skilli agenta AI?

Przy pisaniu skilli agenta AI najczęstsze błędy to sekrety wpisane do pliku, nazwy narzędzi z jednego środowiska, opis zbyt ogólny, żeby się uruchomił, i skill rosnący bez porządkowania. Trzy ostatnie widać w naszych skillach z 04.11.2026.

Uwaga

Nie wpisuj do skilla kluczy, haseł ani tokenów. Skill to plik tekstowy, który się kopiuje i synchronizuje, a w Hermesie agent może go według dokumentacji sam zmieniać. Nasz skill sklepowy mówi, skąd wziąć klucz, ale klucza w nim nie ma.

Drugi błąd to przywiązanie do jednego narzędzia. Skill do KRS w części o RDF wymienia z nazwy narzędzia przeglądarki z Claude Code, więc w innym agencie ten krok nie zadziała. Lepiej opisać, czego krok wymaga, a nazwę narzędzia podać jako przykład.

Trzeci to porządek. Skill do KRS rósł przez dopisywanie: sekcje 3C i 3D, o pismach do sądu i liczeniu terminów, trafiły na koniec pliku, za „Czego nie robić”. Agent je znajdzie, człowiek poprawiający skill już niekoniecznie. Raz na kilka tygodni warto go przeczytać od góry i poukładać. Więcej o tym, jak agenci pracują na co dzień, piszę w dziale AI i automatyzacja, a od czego zacząć, wyjaśnia tekst agent AI: co to jest.

Najczęstsze pytania

Czym jest skill agenta AI?

To folder z plikiem SKILL.md, w którym zapisana jest procedura jednego rodzaju zadania: nazwa, opis, kiedy go użyć, kroki i pułapki. Agent zna na starcie tylko nazwę i opis, a całą treść wczytuje, gdy prośba do niego pasuje. Format opisuje otwarty standard agentskills.io.

Ile może mieć opis skilla?

Pole description może mieć do 1024 znaków, a nazwa do 64 znaków, małymi literami, cyframi i myślnikami (specyfikacja agentskills.io, sprawdzona 04.11.2026). Nasze opisy mają od 572 do 889 znaków. Ważniejsze od długości jest to, żeby opis zawierał słowa, których używasz w prośbach.

Czy skill napisany dla Claude Code zadziała w Hermesie?

Co do formatu tak: oba narzędzia czytają SKILL.md w standardzie agentskills.io. Nie zadziałają kroki, które wymieniają narzędzia dostępne tylko w jednym środowisku, na przykład konkretne narzędzie przeglądarki. Dlatego takie kroki warto opisywać przez to, czego wymagają, a nie przez nazwę narzędzia.

Jak długi powinien być SKILL.md?

Dokumentacja Anthropic i specyfikacja agentskills.io zalecają poniżej 500 linii i około 5 000 tokenów treści; szczegóły przenosi się do katalogu references. Nasz skill do KRS ma 735 linii i to jego znana wada. Skill koszykowy ma 118 linii, a resztę w 26 plikach obok.

Źródła

  1. Agent Skills, Specification: format SKILL.md, pola nagłówka, progressive disclosure (sprawdzone 04.11.2026): agentskills.io
  2. Anthropic, Agent Skills: Overview, poziomy ładowania i koszt w tokenach (sprawdzone 04.11.2026): docs.claude.com
  3. Anthropic, Skill authoring best practices, limit 500 linii i zasady pisania opisu (sprawdzone 04.11.2026): docs.claude.com
  4. Anthropic, Claude Code: Extend Claude with skills, katalogi skilli (sprawdzone 04.11.2026): code.claude.com
  5. Nous Research, Hermes Agent: Skills System, katalog ~/.hermes/skills i polecenie /learn (sprawdzone 04.11.2026): hermes-agent.nousresearch.com
  6. Ministerstwo Sprawiedliwości, API KRS, odpis aktualny KRS 0000946509, stan z 26.02.2026 (pobrane 04.11.2026): api-krs.ms.gov.pl
  7. Ministerstwo Sprawiedliwości, Repozytorium Dokumentów Finansowych, e-sprawozdania DAJMI Dawid Jakś S.K.A. za 2023 i 2024 rok: rdf-przegladarka.ms.gov.pl

Stan na 04.11.2026. Parametry trzech skilli (linie, długość opisu, sekcje, pliki pomocnicze) policzyłem w naszych plikach 04.11.2026. Listę złożonych sprawozdań DAJMI Dawid Jakś S.K.A. sprawdziłem tego dnia w API KRS, a kwoty za 2023 i 2024 rok pochodzą z e-sprawozdań z RDF. Format skilli i zalecenia sprawdziłem 04.11.2026 w specyfikacji agentskills.io oraz w dokumentacji Anthropic i Hermes Agent.

Czytaj dalej

Dyskusja

Komentarze i pytania

Masz pytanie do tekstu albo własne liczby, którymi chcesz się podzielić? Napisz — odpowiadam pod komentarzami, a odpowiedź zostaje tu dla kolejnych osób.

    Jeszcze nikt nie skomentował. Masz pytanie albo własne doświadczenie? Bądź pierwszy — Twoje pytanie pomoże też innym.

    Dodaj komentarz

    Bez linków polecających. Nie publikujemy kodów ani linków polecających i afiliacyjnych — takie komentarze czekają na moderatora, a link usuwamy. Zasady dyskusji

    Dlaczego?

    Pod tekstami o afiliacji każdy chciałby wkleić swój link, a pytania utonęłyby w ogłoszeniach. Nie chcemy też wybierać, czyj link jest „lepszy”. Do tego regulaminy wielu programów partnerskich i sieci afiliacyjnych zabraniają publikowania linków w cudzych komentarzach — za złamanie zasad sieć może zablokować konto razem z prowizjami.

    Zgłoś komentarz

    Powód

    Newsletter Raport Imperium

    Imperium budowane na Twoich oczach

    Za darmo · raz w tygodniu · wypis jednym kliknięciem

    Co Cię interesuje?

    Raz w tygodniu. Zapis potwierdzasz linkiem z maila, wypisujesz się jednym kliknięciem.