Co to są Agent Skills? Przewodnik dla początkujących

W skrócie: Agent Skills to lekki, otwarty format, który rozszerza możliwości agenta AI o specjalistyczną wiedzę i powtarzalne procedury. W praktyce to folder z plikiem SKILL.md zawierającym dwa wymagane pola — name i description — oraz instrukcje w Markdownie. Anthropic opublikowało Skills jako otwarty standard 18 grudnia 2025 roku z założeniem przenośności między platformami; w chwili publikacji format obsługują Claude apps, Claude Code i Claude API.

Ostatnia aktualizacja: 11 czerwca 2026.

Czym dokładnie są Agent Skills i jak je rozpoznać?

Jeśli za każdym razem tłumaczysz agentowi AI ten sam kontekst — swoje konwencje, formaty wyjścia, firmowe procedury — od zera w nowej rozmowie, to jest problem, który Agent Skills rozwiązują raz i na trwałe. Agent Skills dają modelowi językowemu gotową procedurę, której się trzyma, zamiast pozostawiać go z samą wiedzą z treningu i improwizacją. Sercem każdej umiejętności jest plik SKILL.md — Markdown z frontmatterem YAML, w którym muszą znaleźć się dwa pola: name (do 64 znaków, małe litery i myślniki) oraz description (do 1024 znaków). Limity pochodzą wprost ze specyfikacji Anthropic (Agent Skills Overview, 2025).

Format jest celowo minimalny. Specyfikacja oferuje jeszcze cztery pola opcjonalne — license, compatibility (do 500 znaków), metadata i eksperymentalne allowed-tools — ale żadnego z nich nie potrzebujesz, żeby skill zadziałał. Wystarczy folder i jeden SKILL.md, by mieć kompletny, przenośny Agent Skill.

Anthropic zaleca, by ciało pliku SKILL.md mieściło się w 500 liniach i ~5000 tokenach. Dłuższe materiały lądują w folderze references/ — agent sięga po nie tylko wtedy, gdy konkretna instrukcja każe mu po nie zajrzeć.

Jak działa progressive disclosure w Agent Skills?

Progressive disclosure to mechanizm stopniowego odkrywania, który zarządza uwagą modelu. Im dłuższy kontekst, tym duże modele językowe (LLM) gorzej radzą sobie z zadaniem — zjawisko opisane jako context rot w raporcie technicznym Chroma Research (Hong, Troynikov, Huber, lipiec 2025). To na ten właśnie problem Skills odpowiadają warstwowym ładowaniem.

Anthropic dzieli ten proces na trzy poziomy ładowania:

1. Odkrywanie (Level 1: metadata) — przy uruchomieniu sesji agent ładuje wyłącznie pola name i description każdego dostępnego skilla, co generuje znikomy narzut kontekstu. To wystarczy, aby wiedział, kiedy sięgnąć po daną umiejętność.
2. Aktywacja (Level 2: instructions, < 5000 tokenów) — gdy polecenie użytkownika pasuje do description, agent wczytuje pełne ciało SKILL.md do kontekstu.
3. Wykonanie (Level 3: resources) — agent doczytuje pliki z scripts/, references/ lub assets/ dopiero wtedy, gdy konkretna instrukcja każe mu po nie sięgnąć.

Dzięki temu w systemie może istnieć kilkadziesiąt skilli, a okno kontekstu nie puchnie od treści, której agent akurat nie potrzebuje.

Czym różnią się Agent Skills od zwykłego promptu?

Zwykły prompt czerpie tylko z ogólnej wiedzy modelu z treningu, więc często kończy się ogólnikami. Samo dopracowanie promptu — od few-shot po chain-of-thought — często to nadrabia; techniki zbieram w przewodniku o prompt engineeringu 2026. Agent Skill podaje gotową procedurę — i wnosi to, co Google opisuje w patencie „Contextual estimation of link information gain" jako information gain (US20200349181A1, Carbune, Gonnet, Anders, 2020).

Gdy prosisz agenta AI o pomoc bez kontekstu, w odpowiedzi dostajesz generyczne porady. Skill przekazuje mu to, czego nie wymyśli sam: konwencje projektu, niestandardowe formaty wyjścia, autorskie sposoby rozwiązywania problemów.

Jak wygląda struktura folderu z Agent Skill?

Pod spodem każdy skill to po prostu folder. Minimalna, działająca wersja składa się z jednego pliku SKILL.md, a nazwa folderu musi pokrywać się z polem name we frontmatterze. Pełna struktura wygląda tak:

• SKILL.md — jedyny wymagany plik. Frontmatter YAML + instrukcje w Markdownie. Pełną specyfikację formatu publikuje Anthropic w dokumentacji Claude API.
• scripts/ — opcjonalny folder z kodem wykonywalnym (Python, Bash, JavaScript). Agent uruchamia te skrypty, gdy instrukcja każe mu po nie sięgnąć.
• references/ — opcjonalny folder z dodatkową dokumentacją. Agent doczytuje pliki na żądanie.
• assets/ — opcjonalny folder na szablony dokumentów, grafiki, dane wzorcowe.

Specyfikacja dopuszcza dodatkowe pliki i podfoldery, ale dobre skille trzymają referencje „jeden poziom głęboko". Głębsze zagnieżdżenia utrudniają agentowi nawigację.

Jak napisać dobry opis (description), żeby skill trafnie się aktywował?

Skill pomaga tylko wtedy, gdy się aktywuje. Agent decyduje o tym wyłącznie na podstawie pola description — to ono mówi mu, czy wczytać pełny SKILL.md. Niedoprecyzowany opis sprawia, że skill nie włącza się tam, gdzie powinien; zbyt szeroki — odwrotnie, triggeruje się tam, gdzie nie ma sensu.

Według dokumentacji Anthropic (Agent Skills Overview oraz skill-creator, źródła 1 i 4) opis działa najlepiej, gdy spełnia cztery warunki:

• Tryb rozkazujący. „Używaj tego skilla, gdy…" zamiast „Ten skill robi…". Agent decyduje o działaniu, więc opis powinien mu mówić, kiedy działać.
• Skup się na intencji użytkownika, nie na mechanizmie. Opisz, co użytkownik próbuje osiągnąć — nie wnętrze skilla.
• Bądź konkretny i „nachalny". Wymieniaj kontekst, w którym skill ma się włączyć, nawet jeśli użytkownik nie nazywa wprost domeny („nawet jeśli nie wspomni o CSV").
• Limit 1024 znaków. Opisy mają tendencję do puchnięcia podczas iteracji — pilnuj długości.

Doświadczeni autorzy idą krok dalej: testują działanie opisu na zestawie około 20 realistycznych zapytań — połowa „powinno włączyć", połowa „nie powinno" — i liczą trigger rate przy trzech uruchomieniach każdego. Pętlę da się też zautomatyzować — Anthropic publikuje w tym celu referencyjny skill-creator w repozytorium anthropics/skills. Jak rozpisać samo pole description, instrukcje, których agent się trzyma, i sekcję Gotchas — oraz jak zmierzyć trafność aktywacji — rozwija osobny przewodnik jak napisać dobry plik SKILL.md.

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ł →

Dlaczego sekcja typowych błędów (Gotchas) jest tak skuteczna?

Anthropic w dokumentacji dobrych praktyk osobno omawia typowe błędy (Common Pitfalls). To jedna z najskuteczniejszych części dobrego SKILL.md — w społeczności użytkowników utrwalił się dla niej termin Gotchas. To konkretne wskazówki korygujące pomyłki, których agent nie uniknie, działając wyłącznie na podstawie wiedzy z treningu.

Dobrze pokazuje to przykład z bazą danych: jeśli tabela users używa soft-delete, każde zapytanie musi zawierać WHERE deleted_at IS NULL — inaczej wyniki obejmą dezaktywowane konta. To nie jest ogólnik w stylu „obsługuj błędy poprawnie" — to korekta założenia, którego agent nie miałby skąd znać.

Najmocniejsze w tym wzorcu jest sprzężenie zwrotne. Kiedykolwiek agent popełnia nowy błąd, który musisz poprawić, dopisujesz korektę do Gotchas. Następnym razem ta sama pomyłka się nie powtórzy. Z każdą korektą skill staje się trwalszym aktywem — raz zapisany błąd nie wraca, a Ty odzyskujesz kontrolę nad powtarzalną pomyłką.

Kiedy używać Agent Skills, a kiedy zostać przy zwykłym prompcie?

Skill ma sens wtedy, gdy procedura się powtarza, a Ty chcesz, by za każdym razem wykonała się tak samo — z tą samą precyzją. Trzy sygnały dobrze identyfikują takie sytuacje:

1. Powtarzalność. Wykonujesz to samo zadanie częściej niż dwa razy w tygodniu, a wynik powinien być spójny.
2. Kontekst, którego model nie zna. Twoje konwencje nazewnicze, niestandardowe formaty wyjścia, sekwencje wywołań API specyficzne dla Twojej firmy.
3. Konsekwencja błędów. Pomyłka w tym zadaniu kosztuje czas lub pieniądze — warto zainwestować w precyzyjne instrukcje raz, zamiast poprawiać model w każdej rozmowie.

Jednorazowe pytanie, eksploracja problemu albo zadanie, z którym model i tak sobie poradzi — to słabi kandydaci na skill. Jeśli agent dobrze radzi sobie bez Twoich instrukcji, skill nic nie wnosi, a kontekst i tak zajmuje.

Jak zacząć: minimalny SKILL.md krok po kroku?

Pierwszy skill da się postawić w kilka minut. Sekwencja działa identycznie w Claude Code, Claude apps i każdym innym kompatybilnym kliencie:

1. Utwórz folder o nazwie zgodnej z planowanym name — same małe litery, cyfry i myślniki (np. roll-dice).
2. W środku folderu utwórz plik SKILL.md.
3. Na górze pliku umieść frontmatter YAML z polami name i description. Opis sformułuj w trybie rozkazującym: „Używaj, gdy…".
4. Pod frontmatterem napisz instrukcje w Markdownie — krok po kroku, z konkretnymi przykładami wejścia i wyjścia.
5. Umieść folder w katalogu, który dany klient przeszukuje w poszukiwaniu skilli (np. .claude/skills/ w Claude Code; w pozostałych klientach — w lokalizacji wskazanej w ich dokumentacji).
6. Uruchom prompt pasujący do description i sprawdź, czy skill się aktywował.

Przykład SKILL.md

---
name: social-media-copywriter
description: Przekształcaj długie artykuły w krótkie posty na LinkedIn i Facebooka. Używaj, gdy użytkownik prosi o promocję treści w mediach społecznościowych, nawet jeśli nie nazwie wprost "post" lub "social media".
---

# Social Media Copywriter

Ten skill przekształca długie artykuły w krótkie, angażujące wpisy do mediów społecznościowych.

## Jak używać tej umiejętności
1. Poproś użytkownika o link do artykułu lub wklejenie tekstu.
2. Wyodrębnij z tekstu 3 najważniejsze wnioski (Key Takeaways).
3. Przygotuj dwie wersje posta: na LinkedIn (ton profesjonalny) oraz na Facebooka (ton swobodny z emoji).

## Zasady formatowania
- **LinkedIn:** Listy punktowane, maksymalnie 3–5 hashtagów na końcu.
- **Facebook:** Na końcu pytanie angażujące społeczność.

## Gotchas
- Nie zmyślaj faktów, których nie ma w tekście źródłowym.
- Jeśli tekst źródłowy ma mniej niż 200 słów, najpierw poproś o uzupełnienie.
- Link do artykułu zawsze umieszczaj w ostatniej linii posta.

Kluczowe wnioski

• Agent Skills to folder z plikiem SKILL.md (Markdown + frontmatter YAML), publikowany od grudnia 2025 jako otwarty format.
• Dwa wymagane pola: name (≤ 64 znaki) i description (≤ 1024 znaki). Cztery opcjonalne: license, compatibility, metadata, allowed-tools.
• Progressive disclosure ładuje skill w trzech poziomach (metadane → instrukcje → zasoby), zmniejszając wpływ context rot opisanego przez Chroma Research (2025).
• Najmocniejszym fragmentem dobrego skilla jest sekcja Gotchas — konkretne korekty założeń, które agent miałby błędnie.
• Trafność aktywacji opiera się prawie w całości na polu description: tryb rozkazujący, fokus na intencję użytkownika, jawne wymienianie kontekstów.

Najczęściej zadawane pytania

Czy muszę umieć programować, aby tworzyć Agent Skills?

Nie. Minimalna forma skilla to plik Markdown z dwoma polami YAML — name i description — oraz instrukcjami w języku naturalnym. Bardziej zaawansowani autorzy potrafią bundlować skrypty w scripts/ (Python, Bash, JavaScript), ale większość codziennych skilli kończy się na samym tekście.

Czy Agent Skills działają poza Claude Code?

Tak. Anthropic opublikowało Skills jako otwarty standard 18 grudnia 2025 roku, a we wpisie blogowym z 22 stycznia 2026 porównuje ich rolę do MCP — protokołu, który firma ustandaryzowała wcześniej. W chwili publikacji format obsługują Claude apps, Claude Code, Claude API oraz partnerskie skille z katalogu Anthropic; inni dostawcy mogą dodać wsparcie.

Z czego składa się minimalny Skill?

Z jednego folderu i jednego pliku. Folder ma nazwę zgodną z polem name (małe litery, cyfry, myślniki, do 64 znaków). W środku leży plik SKILL.md z frontmatterem YAML zawierającym name i description (do 1024 znaków). Ciało pliku to dowolny Markdown — Anthropic zaleca utrzymywać je poniżej 500 linii, a dłuższe materiały trzymać w references/.

Jak udostępnić skill zespołowi?

Skille to zwykłe pliki, więc dystrybuujesz je jak każdy inny kod: commit do repozytorium Git, paczka w wewnętrznym rejestrze, folder na firmowym dysku. Anthropic od grudnia 2025 dorzuca też zarządzanie skillami na poziomie organizacji oraz katalog partnerskich skilli. Raz zdefiniowany wspólny skill — np. styl raportów albo procedura code review — oszczędza zespołowi tłumaczenia tego samego za każdym razem w nowej rozmowie z asystentem AI.

Jak sprawdzić, czy mój opis (description) działa wystarczająco trafnie?

Skill, który nie triggeruje się na właściwe prompty, praktycznie nie istnieje. Anthropic zaleca prosty test: zbierz około 20 realistycznych zapytań (8–10 powinno aktywować skill, 8–10 nie powinno), uruchom każde trzy razy i policz trigger rate. Celuj w to, by skill włączał się na zapytaniach „powinno", a milczał na „nie powinno". Optymalizuj opis na zbiorze treningowym, a walidacyjny zachowaj do końcowej weryfikacji — w ten sposób nie nadpiszesz go do konkretnych fraz.

Źródła

1. Anthropic — Agent Skills overview (Claude API Docs) — oficjalna specyfikacja formatu SKILL.md, pól wymaganych (name, description), limitów znakowych oraz progressive disclosure z trzema poziomami ładowania — https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
2. Anthropic — „Introducing Agent Skills" (16.10.2025, aktualizacja 18.12.2025) — ogłoszenie Skills, publikacja jako otwartego standardu i directory partnerskich skilli — https://www.anthropic.com/index/skills
3. Anthropic — „Building Agents with Skills" (Claude blog, 22.01.2026) — wizja Skills jako otwartego standardu portable między platformami, analogia do MCP — https://claude.com/blog/building-agents-with-skills-equipping-agents-for-specialized-work
4. Anthropic — skill-creator (repo anthropics/skills) — referencyjny skill do tworzenia własnych skilli i automatyzacji optymalizacji opisu — https://github.com/anthropics/skills/tree/main/skills/skill-creator
5. Chroma Research — Hong, Troynikov, Huber, „Context Rot: How Increasing Input Tokens Impacts LLM Performance" (lipiec 2025) — empiryczne uzasadnienie progressive disclosure jako odpowiedzi na spadek skuteczności LLM przy długim kontekście — https://research.trychroma.com/context-rot
6. Google Patents — Carbune, Gonnet, Anders, „Contextual estimation of link information gain" (US20200349181A1, 2020; granted jako US11354342B2 w 2022) — patent definiujący information gain score jako miarę nowości treści, ramę dla wartości skilli z autorską wiedzą — https://patents.google.com/patent/US20200349181A1/en