Jak napisać dobry plik SKILL.md, który działa

W skrócie: Dobry plik SKILL.md stoi na czterech rzeczach: opisie (description), który trafnie się aktywuje, instrukcjach skalibrowanych do specyfiki zadania, sekcji Gotchas z konkretnymi korektami błędów oraz iteracji na realnych zadaniach. Sam format jest minimalny — folder z jednym plikiem SKILL.md — ale o tym, czy skill faktycznie pomaga, decyduje to, jak napiszesz jego opis i instrukcje. Ten przewodnik poprowadzi Ciebie przez proces budowania i testowania skills.md krok po kroku, w oparciu o specyfikację Agent Skills i dokumentację dobrych praktyk firmy Anthropic.

Napisałeś skill, a agent lub chatbot i tak robi po swojemu — albo w ogóle go nie używa. To moment, w którym kontrola nad AI wymyka się z rąk: prosisz o jedno, dostajesz co innego. Prawie nigdy nie wynika to z tego, że Twoje instrukcje są złe — tylko z tego, że skill nie aktywuje się we właściwym momencie albo jego instrukcje są tak ogólne, że model je ignoruje. Dobry SKILL.md jest narzędziem, którym odbierasz ster: agent robi to, o co prosisz, i robi to za każdym razem tak samo. Jeśli dopiero zaczynasz i nie wiesz, czym są Agent Skills, zacznij od przewodnika dla początkujących — ten tekst pomija podstawy i skupia się na rzemiośle: jak napisać SKILL.md, który włącza się trafnie i którego agent się trzyma.

Co musi zawierać poprawny plik SKILL.md?

Poprawny SKILL.md to plik Markdown z frontmatterem YAML, w którym muszą znaleźć się dwa pola — name i description — reszta jest opcjonalna. Tyle wystarczy, by skill zadziałał, ale zanim zaczniesz pisać treść, warto znać twarde reguły formatu, bo to na nich najczęściej wykładają się początkujący

Według specyfikacji Agent Skills (źródło 1) frontmatter dopuszcza sześć pól:

Do tego dochodzą reguły, które dokumentacja Anthropic („The Complete Guide to Building Skills for Claude") nazywa krytycznymi, bo ich złamanie blokuje wgranie skilla:

• Plik musi nazywać się dokładnie SKILL.md — wielkość liter ma znaczenie. skill.md, Skill.md czy SKILL.MD nie zostaną rozpoznane.
• Folder w kebab-case — notion-project-setup, nie Notion Project Setup ani notion_project_setup. Nazwa folderu musi być identyczna z polem name.
• Żadnego pliku README.md w środku skilla — cała dokumentacja idzie do SKILL.md lub do folderu references/. (Repozytorium na GitHubie może mieć osobny README dla ludzi — to inna warstwa.)
• Żadnych nawiasów < i > we frontmatterze — to ograniczenie bezpieczeństwa. Frontmatter trafia do promptu systemowego modelu, więc złośliwa zawartość mogłaby wstrzyknąć instrukcje. Z tego samego powodu nazwy z przedrostkiem „claude" lub „anthropic" są zarezerwowane.

Resztę pliku — całe ciało po frontmatterze — agent wczytuje dopiero po aktywacji skilla. Specyfikacja zaleca utrzymać je poniżej 500 linii i około 5000 tokenów; dłuższe materiały trzymaj w references/ i odsyłaj do nich z SKILL.md.

Jak napisać description, który włącza skill?

Pole description niesie cały ciężar aktywacji — i jest jedyną dźwignią, jaką masz nad tym, czy agent w ogóle sięgnie po skill. To na jego podstawie — i tylko jego — agent decyduje, czy wczytać pełny SKILL.md. Dokumentacja optymalizacji opisów ujmuje to wprost: jeśli opis nie mówi, kiedy skill jest przydatny, agent nie będzie wiedział, że ma po niego sięgnąć. Niedoprecyzowany opis nie włączy skilla tam, gdzie powinien; zbyt szeroki — włączy go tam, gdzie to nie ma sensu.

Dobry opis spełnia cztery warunki:

1. Tryb rozkazujący. „Używaj tego skilla, gdy…" zamiast „Ten skill robi…". Agent podejmuje decyzję o działaniu, więc opis ma mu mówić, kiedy działać.
2. Skup się na intencji użytkownika, nie na mechanizmie. Opisuj, co użytkownik próbuje osiągnąć, a nie wewnętrzną budowę skilla — agent dopasowuje opis do tego, o co go poproszono.
3. Bądź „nachalny". Wymieniaj konteksty, w których skill ma się włączyć, w tym te, gdzie użytkownik nie nazywa domeny wprost: „nawet jeśli nie wspomni o CSV".
4. Pilnuj limitu 1024 znaków. Opisy puchną podczas iteracji — krótki, ale konkretny wygrywa z rozwlekłym.

Różnicę widać na jednym przykładzie. Zamiast description: Process CSV files. napisz: „Analizuj pliki CSV i dane tabelaryczne — licz statystyki, dodawaj kolumny pochodne, twórz wykresy, czyść dane. Używaj, gdy użytkownik ma plik CSV, TSV lub Excel i chce go zbadać, przekształcić albo zwizualizować, nawet jeśli nie powie wprost »CSV« ani »analiza«." Druga wersja jest jednocześnie bardziej konkretna co do tego, co skill robi, i szersza co do tego, kiedy się stosuje.

Jest jeszcze jeden niuans, o którym łatwo zapomnieć: agent zwykle sięga po skill tylko przy zadaniach wymagających wiedzy lub możliwości spoza tego, co zrobi sam. Proste „przeczytaj ten PDF" może nie aktywować skilla do PDF-ów, nawet jeśli opis pasuje idealnie — bo model poradzi sobie podstawowym narzędziem. Opis robi różnicę przy zadaniach z nieznanym API, własną procedurą albo nietypowym formatem.

Jak sprawdzić, czy opis trafnie się aktywuje?

Skill, który nie włącza się na właściwe zapytania jest tak naprawdę nieprzydatny — dlatego trafność opisu warto zmierzyć, a nie zgadywać. Dokumentacja optymalizacji opisów podaje powtarzalną metodę opartą na zestawie zapytań testowych:

1. Zbierz około 20 realistycznych zapytań — 8–10 takich, które powinny aktywować skill, i 8–10, które nie powinny. Każde oznacz etykietą „powinno włączyć" / „nie powinno".
2. Postaw na przypadki z pogranicza. Najcenniejsze negatywne przykłady to zapytania, które dzielą ze skillem słowa kluczowe, ale wymagają czego innego — np. dla skilla do analizy CSV mocnym kontrprzykładem jest „napisz skrypt, który wczyta CSV i wrzuci wiersze do Postgresa" (to ETL do bazy, nie analiza). Słabym — „jaka jest pogoda", bo nie testuje niczego.
3. Uruchom każde zapytanie 3 razy. Zachowanie modelu jest niedeterministyczne, więc licz trigger rate — odsetek uruchomień, w których skill się włączył. Zapytanie „powinno" zalicza się, gdy trigger rate przekracza 0,5; „nie powinno" — gdy spada poniżej.
4. Podziel zestaw na treningowy (~60%) i walidacyjny (~40%). Na treningowym poprawiasz opis, walidacyjny zachowujesz na sprawdzenie, czy zmiany generalizują. To zabezpiecza przed przeuczeniem opisu pod konkretne sformułowania.
5. Iteruj — zwykle wystarcza około 5 rund. Jeśli zapytania „powinno" nie włączają skilla, opis jest za wąski (poszerz). Jeśli „nie powinno" włączają — za szeroki (dodaj, czego skill nie robi). Unikaj wklejania dokładnych słów z nieudanych zapytań; to przeuczenie. Wybierz najlepszą wersję po wyniku na zbiorze walidacyjnym, a nie po tym, która była ostatnia.

Tę pętlę można odpalić ręcznie albo zautomatyzować — Anthropic publikuje w tym celu referencyjny skill skill-creator (źródło 7), który dzieli zestaw, liczy trigger rate równolegle i proponuje poprawki opisu. Szybki sposób na diagnozę bez całego zestawu: zapytaj agenta wprost „kiedy użyłbyś skilla X?". Odpowie, cytując opis — od razu zobaczysz, czego w nim brakuje.

Jak pisać instrukcje, których agent się trzyma?

Skill aktywuje się dzięki opisowi, ale działa dzięki ciału SKILL.md. Gdy skill się włącza, jego pełna treść trafia do okna kontekstu razem z historią rozmowy i innymi aktywnymi skillami — każdy token rywalizuje o uwagę modelu. Dlatego dobre instrukcje to nie „więcej", tylko „celniej". Panowanie nad agentem nie polega na ściskaniu każdego zdania — polega na tym, by wiedzieć, gdzie trzymać ster krótko, a gdzie go popuścić.

Najpierw jednak zadbaj o to, skąd bierzesz treść. Dokumentacja dobrych praktyk ostrzega przed częstym błędem: poproszeniem modelu, by wygenerował skill od zera, bez wiedzy dziedzinowej — wychodzą z tego ogólniki w stylu „obsługuj błędy poprawnie" zamiast Twoich konkretnych konwencji i przypadków brzegowych. Najskuteczniejsi autorzy wyciągają skill z realnego zadania: wykonują je raz z agentem, nanosząc po drodze poprawki, a potem wydobywają z tego powtarzalny wzorzec. Pilnuj też zakresu — dobry skill obejmuje jedną spójną jednostkę pracy, która komponuje się z innymi: zbyt wąski wymusza ładowanie kilku skilli naraz, zbyt szeroki trudno trafnie aktywować.

Gdy treść i zakres są na miejscu, doprecyzuj sposób jej podania. Dokumentacja dobrych praktyk dla autorów skilli opiera się na czterech zasadach:

• Dodawaj to, czego model nie wie — pomijaj to, co już umie. Nie tłumacz, czym jest PDF ani jak działa HTTP. Skup się na tym, czego agent nie wymyśli sam: konwencjach projektu, nietypowych przypadkach brzegowych, konkretnych API i narzędziach. Przy każdym fragmencie zadaj sobie pytanie: „czy agent zrobiłby to źle bez tej instrukcji?". Jeśli nie — wytnij.
• Dopasuj szczegółowość do specyfiki zadania. Tam, gdzie wiele dróg jest poprawnych, daj agentowi swobodę i wyjaśnij dlaczego (rozumiejąc cel, lepiej decyduje w kontekście). Tam, gdzie operacja jest nieodwracalna albo musi przebiec w konkretnej kolejności — bądź rygorystyczny: „Uruchom dokładnie tę sekwencję. Nie dodawaj flag.".
• Lepiej domyślne, nie menu opcji. Zamiast „możesz użyć pypdf, pdfplumber, PyMuPDF albo pdf2image", napisz: „Używaj pdfplumber. Do skanów z OCR — pdf2image z pytesseract.". Jeden domyślny wybór z furtką działa lepiej niż lista równorzędnych opcji.
• Ucz metody, nie konkretnej odpowiedzi. Skill ma uczyć, jak podejść do klasy problemów, nie co wyprodukować w jednym przypadku. Zamiast „połącz tabelę orders z customers i zsumuj kolumnę amount dla regionu EMEA" napisz procedurę: odczytaj schemat, łącz po kluczu obcym, nałóż filtry z zapytania użytkownika, zagreguj i sformatuj. Taka instrukcja zadziała dla każdego zapytania analitycznego.

Konsekwencją tych zasad jest umiar w szczegółach. Nadmiernie wyczerpujący skill potrafi zaszkodzić — agent ma kłopot z wyłuskaniem tego, co istotne, i podąża ścieżkami narzuconymi przez instrukcje, które do bieżącego zadania nie pasują. Zwięzła, krokowa wskazówka z jednym działającym przykładem zwykle bije obszerną dokumentację.

Bezpłatne narzędzie

Sprawdź w 3 minuty, czy Twój pomysł na AI da się wdrożyć

Opisz pomysł, odpowiedz na kilka pytań i zobacz ocenę: macierz wykonalność × impakt, plan MVP i rekomendację — bez zakładania konta.

Sprawdź swój pomysł →

Wzorce skutecznego SKILL.md: Gotchas, szablony, walidacja

Poza ogólnymi zasadami dokumentacja dobrych praktyk wymienia kilka wzorców, które wielokrotnie sprawdziły się w realnych skillach. Nie każdy skill potrzebuje wszystkich — bierz te, które pasują do zadania.

• Gotchas. Najczęściej najcenniejszy fragment skilla: lista faktów specyficznych dla środowiska, które przeczą rozsądnym założeniom. To nie ogólnik „obsługuj błędy poprawnie", tylko konkret: „tabela users używa miękkiego usuwania — każde zapytanie musi zawierać WHERE deleted_at IS NULL, inaczej wyniki obejmą dezaktywowane konta" albo „to samo ID nazywa się user_id w bazie, uid w usłudze autoryzacji i accountId w API rozliczeń". Trzymaj Gotchas w SKILL.md, gdzie agent przeczyta je, zanim trafi na problem. Najmocniejsze jest sprzężenie zwrotne: ilekroć agent popełni błąd, który musisz poprawić, dopisz korektę do Gotchas — następnym razem ta sama pomyłka się nie powtórzy. Każda taka korekta odbiera agentowi jeden sposób na wymknięcie się spod kontroli; raz zapisany błąd nie wraca.
• Szablony formatu wyjścia. Gdy potrzebujesz konkretnej struktury odpowiedzi, daj wzór zamiast opisywać go prozą — modele dobrze dopasowują się do konkretnych struktur. Krótkie szablony mogą leżeć w SKILL.md, dłuższe w assets/, doczytywane na żądanie.
• Checklisty kroków. Jawna lista „do odhaczenia" pomaga agentowi nie pominąć etapu, zwłaszcza gdy kroki mają zależności albo bramki walidacyjne.
• Pętle walidacji i plan-validate-execute. Każ agentowi sprawdzić własną pracę, zanim ruszy dalej: wykonaj, uruchom walidator (skrypt, checklistę albo porównanie z plikiem referencyjnym), popraw błędy, powtórz aż przejdzie. Przy operacjach wsadowych lub nieodwracalnych dołóż krok pośredni — agent tworzy plan w ustrukturyzowanym formacie, waliduje go względem źródła prawdy, i dopiero wtedy wykonuje.

Czasem najlepszą instrukcją nie jest tekst, tylko kod. Jeśli przy testach widzisz, że agent w kółko wymyśla od nowa tę samą logikę — buduje ten sam wykres, parsuje ten sam format — to sygnał, by wynieść ją do folderu scripts/. Kod jest deterministyczny, język interpretacji nie. Skrypty dla agenta projektuj inaczej niż dla człowieka: bez pytań interaktywnych (agent działa w powłoce nieinteraktywnej i zawiśnie na pytaniu o dane wejściowe), z opisem w --help, z wyjściem w formacie strukturalnym (JSON, CSV) na stdout i diagnostyką na stderr, idempotentne i z czytelnymi komunikatami błędów, które mówią, co poszło nie tak i co zrobić dalej.

Jak zmierzyć, czy skill faktycznie pomaga?

Trafna aktywacja to dopiero połowa sukcesu — drugie pytanie brzmi, czy skill daje lepszy wynik niż jego brak. Dokumentacja ewaluacji skilli opisuje prosty schemat: każde zadanie testowe uruchom dwa razy — raz ze skillem, raz bez niego (albo z poprzednią wersją). To daje punkt odniesienia.

Dla każdego przypadku spisz wyniki — sprawdzalne zdania o tym, co wynik ma zawierać: „plik wyjściowy to poprawny JSON", „wykres ma podpisane obie osie", „raport zawiera co najmniej 3 rekomendacje". Unikaj asercji nieostrych („wynik jest dobry") i nadmiernie sztywnych („dokładnie ta fraza"). Następnie oceń każdy wynik jako PASS/FAIL — z dowodem cytującym wynik, nie z samą opinią.

Sercem pomiaru jest delta między wersją ze skillem a bez niego. Zestawiasz nie tylko trafność (pass rate), ale i koszt — zużyte tokeny i czas. Skill, który dodaje kilkanaście sekund, ale podnosi pass rate o kilkadziesiąt punktów, zwykle się opłaca; skill, który podwaja zużycie tokenów dla dwóch punktów poprawy — niekoniecznie. Na koniec dołóż przegląd przez człowieka: wyniki łapią tylko to, co przewidziałeś, a recenzent wychwyci wynik formalnie poprawny, ale mijający się z sensem. Pomiar zamienia „chyba pomaga" w „widać, że pomaga" — to różnica między wrażeniem a panowaniem nad jakością.

Pomocne są też orientacyjne cele, które dokumentacja Anthropic traktuje jako punkty odniesienia, nie sztywne progi: skill aktywuje się na około 90% trafnych zapytań, kończy zadanie w mniejszej liczbie wywołań narzędzi niż bez niego, bez nieudanych wywołań i bez konieczności poprawiania go przez użytkownika w trakcie. Testować można na trzech poziomach rygoru: ręcznie w aplikacji (szybka iteracja), skryptowo (powtarzalna walidacja przy zmianach) i programatycznie (zestawy ewaluacyjne uruchamiane systematycznie).

Najczęstsze błędy przy budowaniu SKILL.md i jak je naprawić

Większość problemów z autorskimi skillami sprowadza się do kilku powtarzalnych objawów — a każdy z nich to inny sposób, w jaki skill wymyka się spod kontroli. Poniższa tabela zbiera je razem z przyczyną i poprawką — według sekcji troubleshooting z obu źródeł.

Warto pamiętać o jednym rozgraniczeniu: jeśli skill się włącza, ale wywołania narzędzi zawodzą, problem często leży poza skillem — w połączeniu z serwerem MCP, nie w instrukcjach. Szybki test: poproś agenta o tę samą operację bez skilla. Jeśli nadal się nie udaje, naprawiaj połączenie, nie SKILL.md.

Kluczowe wnioski

• Poprawny SKILL.md to plik o tej dokładnej nazwie (wielkość liter ma znaczenie), w folderze w kebab-case zgodnym z polem name, z dwoma wymaganymi polami frontmattera: name (≤ 64 znaki) i description (≤ 1024 znaki).
• O aktywacji decyduje wyłącznie description — pisz go w trybie rozkazującym, z fokusem na intencję użytkownika i jawnym wymienianiem kontekstów.
• Trafność aktywacji się mierzy: ~20 zapytań testowych z przypadkami z pogranicza, 3 uruchomienia, trigger rate, podział train/validation, około 5 iteracji.
• Instrukcje kalibruj do specyfiki zadania — swoboda tam, gdzie wiele dróg jest dobrych; rygor przy operacjach nieodwracalnych. Dawaj domyślne, nie menu; ucz metody, nie odpowiedzi.
• Najmocniejsze wzorce to Gotchas (korekty po realnych błędach), szablony wyjścia, checklisty i pętle walidacji; logikę powtarzalną wynoś do scripts/. Wartość skilla potwierdzaj deltą względem wersji bez niego.

Najczęściej zadawane pytania

Dlaczego mój skill się nie aktywuje?

Prawie zawsze winny jest opis, nie instrukcje. Agent decyduje o aktywacji wyłącznie na podstawie pola description. Jeśli jest zbyt ogólny („Pomaga z projektami") albo nie zawiera kontekstów, w których skill ma zadziałać, model nie wie, że ma po niego sięgnąć. Przepisz opis w trybie rozkazującym, dodaj konkretne wyzwalacze i sprawdź diagnozę: zapytaj agenta „kiedy użyłbyś skilla X?" — odpowie, cytując opis, więc od razu zobaczysz lukę. Pamiętaj też, że proste zadania, z którymi model radzi sobie sam, mogą nie aktywować żadnego skilla — i to jest poprawne zachowanie.

Jak długi powinien być plik SKILL.md?

Specyfikacja zaleca utrzymać ciało SKILL.md poniżej 500 linii i około 5000 tokenów. To ma być rdzeń instrukcji, których agent potrzebuje przy każdym uruchomieniu. Gdy materiału jest więcej, przenieś szczegóły do plików w references/ i odsyłaj do nich z SKILL.md — z informacją, kiedy je doczytać („przeczytaj references/api-errors.md, jeśli API zwróci kod inny niż 200"). Dzięki temu kontekst ładuje się na żądanie, a nie z góry.

Czy skill trzeba testować skryptem, czy wystarczy ręcznie?

Zależy od stawki. Skill używany przez jedną osobę można testować ręcznie — uruchamiasz zapytania i obserwujesz zachowanie. Skill wdrażany dla zespołu albo wielu użytkowników zasługuje na testy skryptowe (powtarzalna walidacja przy każdej zmianie) lub programatyczne (zestawy ewaluacyjne uruchamiane systematycznie). Do samej trafności aktywacji policz trigger rate na ~20 zapytaniach; do jakości wyniku — porównaj wynik ze skillem i bez niego na zestawie asercji.

Co zrobić, gdy agent wgrywa skill, ale nie trzyma się instrukcji?

Najczęstsze przyczyny to instrukcje zbyt rozwlekłe, zakopane w środku pliku albo wieloznaczne. Skróć je, przenieś najważniejsze punkty na górę pod nagłówkiem typu ## Ważne i zamień ogólniki na konkrety („zanim wywołasz create_project, sprawdź, że nazwa jest niepusta"). Pomaga też wyjaśnienie dlaczego — model trzyma się instrukcji pewniej, gdy rozumie ich cel. Jeśli to operacja krytyczna, rozważ przeniesienie sprawdzenia do skryptu w scripts/: kod jest deterministyczny, interpretacja języka nie.

Źródła

1. Agent Skills — Specyfikacja formatu (agentskills.io) — pełna specyfikacja SKILL.md: pola frontmattera i ich ograniczenia, reguły nazewnictwa, progressive disclosure, limit 500 linii / 5000 tokenów — https://agentskills.io/specification
2. Agent Skills — „Best practices for skill creators" (agentskills.io) — kalibracja kontroli (szczegółowość vs kruchość, domyślne zamiast menu, procedury zamiast deklaracji), wzorce Gotchas / szablony / checklisty / pętle walidacji — https://agentskills.io/skill-creation/best-practices
3. Agent Skills — „Optimizing skill descriptions" (agentskills.io) — jak działa aktywacja, zasady pisania opisu, zestaw zapytań testowych, trigger rate, podział train/validation, pętla optymalizacji — https://agentskills.io/skill-creation/optimizing-descriptions
4. Agent Skills — „Evaluating skill output quality" (agentskills.io) — porównanie ze skillem i bez niego, asercje, ocena PASS/FAIL, delta pass rate vs koszt, przegląd przez człowieka — https://agentskills.io/skill-creation/evaluating-skills
5. Agent Skills — „Using scripts in skills" (agentskills.io) — kiedy wynieść logikę do scripts/ i jak projektować skrypty pod użycie agentowe (bez pytań interaktywnych, --help, output strukturalny, idempotencja) — https://agentskills.io/skill-creation/using-scripts
6. Anthropic — „The Complete Guide to Building Skills for Claude" — fundamenty, kategorie zastosowań, kryteria sukcesu, krytyczne reguły nazewnictwa i bezpieczeństwa, sekcja troubleshooting, lista kontrolna — https://www.anthropic.com/index/skills
7. Anthropic — skill-creator (repozytorium anthropics/skills) — referencyjny skill, który automatyzuje pętlę optymalizacji opisu i ewaluację — https://github.com/anthropics/skills/tree/main/skills/skill-creator