Claude Code Skills – jak nauczyć agenta własnych umiejętności

Wydajesz agentowi polecenie: „przygotuj tygodniowy raport dla klienta". Claude Code stara się, jak umie: oddaje poprawny, generyczny dokument. Sekcje wymyślone, ton nie Twój, klient od razu pozna szablon. Potem dodajesz jeden folder z jednym plikiem i piszesz to samo polecenie. Tym razem podajesz listę zadań z tygodnia, resztę robi procedura – i raport wygląda jak od Ciebie: właściwe sekcje, właściwa kolejność, firmowy ton. Ten plik to skill.

Skill to folder z jednym plikiem SKILL.md – spisaną procedurą, którą agent wczytuje tylko wtedy, gdy jest potrzebna. Metryczka na górze pliku mówi, kiedy jej użyć. Reszta mówi, jak wykonać robotę. Dzięki temu możesz dać agentowi dziesiątki firmowych umiejętności bez zapychania mu pamięci.

I najlepsze: pierwszy skill zbudujesz dziś, w 10 minut, bez linijki kodu. Kompletny plik do skopiowania masz niżej.

Czym jest skill – wersja oficjalna i wersja ludzka

Dokumentacja Anthropic opisuje to tak: Skills rozszerzają to, co Claude potrafi zrobić. Tworzysz plik SKILL.md z instrukcjami, a Claude dodaje go do swojego zestawu umiejętności.

Wersja ludzka: skill to zakładka w segregatorze procedur. Wyobraź sobie, że zatrudniasz zdolnego pracownika. Zna się na wszystkim po trochu, ale nie zna Twojej firmy. Co robisz pierwszego dnia? Dajesz mu segregator: „tak piszemy raporty", „tak wyceniamy projekty", „tak odpowiadamy klientom". Claude Code to ten pracownik. Skille to segregator.

Każdy skill ma dwie części, obie w jednym pliku:

• Metryczka (frontmatter YAML) – kilka linijek między znakami --- na górze pliku: nazwa i opis. Opis odpowiada na jedno pytanie: kiedy tego użyć.
• Instrukcja (markdown) – reszta pliku, zwykły tekst: jak krok po kroku wykonać zadanie, w jakim formacie oddać wynik, czego unikać.

I dwa sposoby wywołania. Samoczynnie: agent czyta opisy wszystkich skilli i sam sięga po właściwy, gdy Twoje polecenie pasuje. Ręcznie: wpisujesz /raport-tygodniowy i skill startuje od razu, bez zgadywania.

Dlaczego to sprytne: agent czyta instrukcję dopiero, gdy jej potrzebuje

Agent ma ograniczoną pamięć roboczą – kontekst. Wszystko, co do niej trafia, zajmuje miejsce. Gdyby na starcie czytał w całości trzydzieści firmowych procedur, na Twoją właściwą robotę zostałoby niewiele.

Skille rozwiązują to mechanizmem, który Anthropic nazywa progressive disclosure – stopniowym odsłanianiem. Na starcie sesji agent widzi tylko metryczki: nazwę i opis każdego skilla, około 100 tokenów na sztukę. Token to jednostka, w której model liczy tekst; 100 tokenów to kilka zdań. Pełną treść wczytuje dopiero wtedy, gdy skill jest potrzebny. Dokumentacja podkreśla tę różnicę wprost: w przeciwieństwie do zawartości CLAUDE.md treść skilla ładuje się dopiero przy użyciu.

Wróćmy do segregatora. Pracownik nie recytuje z pamięci wszystkich procedur przy każdym zadaniu. Pamięta spis treści: co jest w której zakładce. Po właściwą sięga, gdy przychodzi konkretna robota. Dokładnie tak działa agent ze skillami – i dlatego możesz mieć ich dziesiątki niemal bez kosztu. Prawie – jedna pułapka z limitem opisów czeka na Ciebie w dalszej części tekstu.

Slash command i skill to dziś to samo

Jeśli uczyłeś się Claude Code ze starszych poradników, pamiętasz pewnie „custom commands" – własne komendy z ukośnikiem. Ta wiedza właśnie się zestarzała, i to na plus. W 2026 Anthropic scalił oba mechanizmy w jeden. Dokumentacja ujmuje to jednym zdaniem: własne komendy zostały scalone ze skillami – i plik komendy, i skill tworzą tę samą komendę /deploy i działają tak samo.

Co z tego wynika w praktyce:

• Każdy skill automatycznie jest komendą. Folder raport-tygodniowy daje komendę /raport-tygodniowy. Nazwa katalogu = nazwa komendy.
• Nie wybierasz już między „komendą" a „skillem". To był sztuczny wybór; teraz piszesz jeden plik.
• Starsze poradniki o komendach wciąż w większości mają sens – opisują ten sam mechanizm pod dawną nazwą.

W polskim internecie prawie nikt jeszcze o tym scaleniu nie pisze, stąd zamieszanie na grupach i w tutorialach. Zapamiętaj jedno zdanie: slash command i skill to od 2026 jeden byt.

Zbuduj pierwszy skill w 10 minut

Budujemy skill ze sceny otwierającej: tygodniowy raport dla klienta. Potrzebujesz zainstalowanego Claude Code (jeśli go nie masz – instrukcja instalacji prowadzi za rękę) i dowolnego edytora tekstu. Notatnik wystarczy.

Krok 1 (2 minuty): załóż folder.

mkdir -p ~/.claude/skills/raport-tygodniowy

Pracujesz na Windows? W PowerShell zamiast mkdir -p ~/... wpisz mkdir "$env:USERPROFILE\.claude\skills\raport-tygodniowy". Nie chcesz dotykać terminala? Poproś samego agenta: „załóż mi folder raport-tygodniowy w ~/.claude/skills". Dwie zasady nazywania, obie z dokumentacji: małe litery, cyfry i myślniki, maksymalnie 64 znaki; w nazwie nie mogą wystąpić słowa „anthropic" ani „claude".

Krok 2 (6 minut): napisz SKILL.md.

W folderze tworzysz jeden plik: SKILL.md. Oto kompletny, działający wzorzec – skopiuj i podmień szczegóły na swoje:

---
name: raport-tygodniowy
description: Przygotowuje cotygodniowy raport dla klienta w formacie firmy. Użyj, gdy pojawia się prośba o raport tygodniowy, podsumowanie tygodnia, status prac dla klienta albo update projektu.
---

# Raport tygodniowy dla klienta

## Zanim zaczniesz
1. Zapytaj, którego klienta i którego tygodnia dotyczy raport.
2. Poproś o listę zadań z tego tygodnia albo o plik, z którego masz ją wziąć.

## Struktura raportu (zawsze w tej kolejności)
1. **Podsumowanie** – maksymalnie 3 zdania, w tym jeden wynik z liczbą.
2. **Zrobione w tym tygodniu** – lista punktów; każdy opisuje efekt,
   nie czynność („czas obsługi spadł z 3 dni do 1", nie „pracowaliśmy nad obsługą").
3. **W toku** – co trwa i konkretna data, kiedy będzie gotowe.
4. **Potrzebujemy od Was** – czego brakuje ze strony klienta, z terminem.
5. **Plan na przyszły tydzień** – maksymalnie 5 punktów.

## Przykład sekcji „Podsumowanie" (utrzymuj ten ton)
> Skróciliśmy czas potwierdzania zamówień z 4 godzin do 5 minut.
> Integracja z magazynem w toku – zakończenie 14.03. Do startu
> testów potrzebujemy jeszcze dostępów do skrzynki biura.

## Zasady
- Ton: rzeczowy i prosty, zero korporacyjnej nowomowy.
- Każdy punkt ma konkret: liczbę, datę albo nazwę pliku.
- Długość: maksymalnie jedna strona A4.
- Zapisz wynik jako raport-RRRR-MM-DD.md w folderze klienta
  (podmień ścieżkę na swoją).

Najwięcej uwagi poświęć polu description. Dokumentacja zaleca je wypełniać i daje limit 1024 znaków – ale liczy się co innego niż długość. Opis ma zawierać słowa, których Ty naturalnie użyjesz w poleceniu. Mówisz „update dla klienta"? Wpisz „update". Mówisz „status projektu"? Wpisz „status projektu". Agent dopasowuje Twoje polecenie do opisów skilli – jeśli opis mówi innym językiem niż Ty, skill przeleży w folderze nieużywany.

Krok 3 (2 minuty): przetestuj.

Otwórz Claude Code i wpisz /raport-tygodniowy. Komendy nie ma na liście? Zrestartuj sesję – Claude Code wczytuje skille przy starcie. Jeśli dalej jej nie widzisz, uruchom claude --debug i sprawdź w logach, czy skill w ogóle się ładuje. Gdy komenda jest na miejscu, skill wystartuje i zapyta o klienta i tydzień – dokładnie tak, jak każe sekcja „Zanim zaczniesz". Potem test właściwy: napisz naturalnie „przygotuj raport tygodniowy dla klienta X" i sprawdź, czy agent sam sięgnął po skill.

Nie wyszło idealnie? Normalne. Skill to plik tekstowy: otwierasz, poprawiasz zdanie, testujesz jeszcze raz. Zrób → zmierz → popraw. Po dwóch, trzech rundach procedura siedzi.

Gdzie żyją skille

Skill z tutorialu trafił do katalogu osobistego. To jedno z czterech miejsc:

Praktyczna ścieżka jest prosta. Zaczynasz w katalogu osobistym, bo tam eksperymentujesz bez konsekwencji. Gdy skill okrzepnie i ma z niego korzystać zespół, przenosisz folder do projektu – od tej chwili każdy współpracownik dostaje tę samą procedurę razem z plikami projektu. Tak firmowa wiedza przestaje mieszkać w głowach i zaczyna mieszkać w plikach.

Skill, CLAUDE.md, subagent, MCP – co jest do czego

Wokół Claude Code krąży kilka pojęć, które łatwo pomylić. Jedno wymaga słowa wstępu: dopisek context: fork w metryczce zamienia skill w coś na kształt subagenta – dostaje zadanie, robi je na boku i wraca z wynikiem, a dokumentacja zaznacza, że taki skill nie ma dostępu do historii Twojej rozmowy. Teraz jedna tabela porządkująca:

Najkrótsze rozróżnienie, jakie znam: CLAUDE.md mówi agentowi, kim jest. Skill mówi, jak wykonać robotę. MCP daje mu czym. Do CLAUDE.md trafia to, co ma obowiązywać zawsze: nazwa firmy, zasady językowe, granice. Do skilli – procedury konkretnych zadań.

Jeżeli te klocki układają Ci się dopiero teraz – cały ekosystem rozbieram od zera w przewodniku po Claude Code dla nieprogramistów.

Trzy pomysły na skille dla Twojej firmy

Nie musisz mieć działu IT, żeby to miało sens. Trzy nisko wiszące owoce – każdy do zbudowania w jeden wieczór:

1. Raport tygodniowy dla klienta. Masz go wyżej w całości. W opisie: „raport tygodniowy", „podsumowanie tygodnia", „status dla klienta". W treści: sekcje raportu w stałej kolejności, zasada „efekt, nie czynność", limit jednej strony.

2. Oferta według firmowego szablonu. W opisie: „oferta", „wycena", „propozycja współpracy". W treści: sekcje szablonu, widełki cenowe i zasady rabatów, lista rzeczy, których nigdy nie obiecujemy, plus dwie dobre oferty jako wzór do naśladowania.

3. Posty społecznościowe w tonie marki. W opisie: „post na LinkedIn", „wpis na Facebooka", „zapowiedź wydarzenia". W treści: ton i długość per kanał, struktura (hak, konkret, wezwanie), słowa zakazane, trzy przykłady postów, które zadziałały.

Wzorzec wszędzie ten sam: opis mówi „kiedy", treść mówi „jak", a przykłady robią połowę roboty. U nas w StormIT agent ma skille między innymi od artykułów blogowych, kampanii reklamowych i grafik – nasz skill blogowy pilnuje m.in. reguły półpauz, struktury FAQ i tego, żeby każda liczba w tekście miała źródło. Ten artykuł powstał w systemie, który sam na skillach stoi.

Pięć pułapek na start

Wszystkie opisane w dokumentacji i wszystkie do ominięcia w minutę – jeśli wiesz, że istnieją:

1. Skill się nie odpala. Najczęstsza przyczyna: opis bez słów, których naturalnie używasz. Agent dopasowuje polecenie do opisu – dopisz do description frazy z życia („update", „podsumowanie dla szefa"), nie definicje z encyklopedii.
2. Zepsute metadane. Literówka w YAML – brak ---, złe wcięcie – sprawia, że skill ładuje się bez metryczki i nie działa, jak powinien. Diagnoza: uruchom claude --debug i poszukaj błędów przy wczytywaniu skilla.
3. Za dużo skilli naraz. Limity są dwa. Opis pojedynczego skilla jest w listingu przycinany do 1536 znaków, a na opisy wszystkich skilli razem agent ma budżet około 1% okna kontekstu modelu – gdy się przepełni, opisy najrzadziej używanych skilli wypadają pierwsze. Diagnoza: komenda /doctor. Lek: krótsze opisy.
4. Załadowany skill zostaje w kontekście do końca sesji. Za długi skill to balast na resztę rozmowy. Trzymaj plik poniżej 500 linii i pilnuj, żeby w środku była procedura, nie encyklopedia.
5. Bezpieczeństwo. Skill to instrukcje, które agent wykonuje. Dokumentacja ostrzega wprost: złośliwy skill może skłonić Claude'a do uruchamiania narzędzi albo wykonywania kodu. Instaluj skille tylko z zaufanych źródeł, a przed instalacją przeczytaj SKILL.md – to zwykły tekst, przeczytasz go w minutę. Kontrolę nad narzędziami też masz w metryczce: pole allowed-tools z góry zatwierdza skillowi tylko te narzędzia, którym ufasz (np. sam odczyt plików), a disallowed-tools całkiem odbiera mu te, których ma nie dotykać.

I jeszcze jedna rzecz, która zaskakuje prawie każdego: skille nie synchronizują się między Claude Code, claude.ai i API. Skill zbudowany na komputerze nie pojawi się sam w przeglądarce. Każde środowisko ma dziś swój osobny komplet.

Od konsumenta do projektanta

Wróć na chwilę do sceny z początku: to samo polecenie, dwa zupełnie różne wyniki. Cała różnica to jeden plik tekstowy, napisany w 10 minut.

To jest moment, który zmienia sposób korzystania z AI. Większość ludzi jest konsumentami: biorą model taki, jaki jest, i przy każdej rozmowie od nowa tłumaczą mu swoją robotę. Ty właśnie przeszedłeś na drugą stronę – projektujesz umiejętności. Raz spisana procedura pracuje potem w każdej sesji i u każdego, komu ją dasz. Agent przestaje robić rzeczy „ogólnie", a zaczyna robić je po Twojemu.

W takim razie – od czego zaczniesz? Jeśli od raportu: wzorzec masz wyżej, wystarczy podmienić szczegóły. Dobry skill to w gruncie rzeczy dobrze napisana instrukcja, więc jeśli chcesz podszlifować samo pisanie poleceń – zajrzyj do tekstu o pisaniu promptów. Jeśli wolisz budować cały system agentów z prowadzeniem, krok po kroku – robimy to na żywo w Masterclass Claude Code. A co sobotę rozbieram jeden konkretny przypadek z własnego podwórka w newsletterze.

FAQ – najczęstsze pytania o Claude Code Skills

Co to jest skill w Claude Code?

Skill to folder z plikiem SKILL.md: na górze metryczka (nazwa i opis, kiedy go użyć), niżej instrukcja krok po kroku. Agent wczytuje pełną treść tylko wtedy, gdy skill jest potrzebny. Wywołasz go na dwa sposoby: agent sięga po niego sam, gdy polecenie pasuje do opisu, albo Ty ręcznie – komendą /nazwa-skilla.

Czym skill różni się od CLAUDE.md?

CLAUDE.md to stała pamięć: jego treść siedzi w kontekście zawsze, od startu każdej sesji. Skill to umiejętność na żądanie: na starcie agent widzi tylko jego opis (około 100 tokenów), a całość czyta dopiero przy użyciu. Zasada praktyczna: do CLAUDE.md trafia to, co ma obowiązywać zawsze, do skilli – procedury konkretnych zadań.

Czy skill to to samo co slash command?

Dziś tak. W 2026 Anthropic scalił własne komendy ze skillami w jeden mechanizm – oba tworzą taką samą komendę z ukośnikiem i działają tak samo. Każdy skill wywołasz przez /nazwa-folderu. Starsze poradniki o „custom commands" opisują ten sam byt pod dawną nazwą.

Gdzie znajdę gotowe skille?

Oficjalne repozytorium github.com/anthropics/skills zbiera skille demonstracyjne i edukacyjne – dobre do nauki wzorców. Powstał też otwarty standard agentskills.io. Ale najcenniejszych skilli nie znajdziesz nigdzie w sieci: to Twoje firmowe procedury, które sam spiszesz.

Czy skille są bezpieczne?

Skill to instrukcje, które agent wykonuje – dokumentacja Anthropic ostrzega, że złośliwy skill może skłonić agenta do uruchamiania narzędzi lub wykonywania kodu. Zasady: instaluj tylko z zaufanych źródeł, przed instalacją przeczytaj SKILL.md (to zwykły tekst), a własne skille trzymaj w repozytorium, gdzie widać każdą zmianę.