TL;DR
- Claude Code skills to skrypty SKILL.md w folderze .claude/skills/, które Claude wywołuje na żądanie lub automatycznie po spełnieniu warunku.
- Skill może mieć maksymalnie kilkaset linii Markdown: opis celu, kroki do wykonania, przykłady wejścia i wyjścia.
- Budowanie skilla ma sens gdy ten sam wieloetapowy workflow powtarza się 3+ razy dziennie lub tygodniowo.
- Skill to nie MCP: MCP daje Claude'owi dostęp do zewnętrznego narzędzia, skill daje mu gotowy playbook postępowania.
- Czas budowy prostego skilla: 30-60 minut. Czas zwrotu: pierwsze użycie.
Czym są Claude Code skills?
Claude Code skills to wielokrotnie używalne instrukcje sterujące zachowaniem Claude Code w konkretnym, powtarzalnym zadaniu. Skill mieszka w pliku SKILL.md wewnątrz folderu .claude/skills/ projektu. Kiedy użytkownik wpisuje /nazwa-skilla w terminalu Claude Code, Claude wczytuje ten plik i traktuje go jako swoje instrukcje operacyjne na czas tego zadania.
Mechanizm jest prosty. oficjalna dokumentacja opisuje go jako zestaw instrukcji w języku naturalnym z osadzonymi poleceniami bash, plikami referencyjnymi i regułami decyzji. Nie ma tutaj kodu w tradycyjnym sensie. SKILL.md to plik Markdown, który Claude czyta i interpretuje przed każdym krokiem.
Różnica od zwykłego prompta: skill jest trwały, wersjonowany w repozytorium, dostępny dla całego zespołu i może mieć własną wewnętrzną logikę decyzji (jeśli X to zrób Y, jeśli Z to BLOCKED). Prompt jednorazowy żyje w kontekście rozmowy. Skill żyje w projekcie.
Typowe zastosowania:
- Codzienne procesy: daily standup raporty, aktualizacje statusów, synchronizacja danych
- Workflow deweloperski: deploy, rollback, tworzenie PR z checklistą, lint i format przed commitem
- Content workflow: pisanie postów według ustalonych reguł, audyt treści, publikacja do CMS
- Onboarding: skill który przeprowadza nowego developera przez setup środowiska krok po kroku
Jak napisać własny Claude Code skill?
Własny Claude Code skill piszesz w trzech krokach: cel, kroki, guardrails.
Krok 1: Zdefiniuj cel w jednym zdaniu
Pierwsze zdanie SKILL.md odpowiada na pytanie "co ten skill robi i kiedy jest wywoływany?" Przykład: "Use this skill when deploying to production. Runs pre-deploy checks, creates a release branch and opens a PR with a checklist." Claude używa tego zdania do decyzji czy skill pasuje do sytuacji.
Krok 2: Napisz kroki jako lista
Każdy krok to zdanie w trybie rozkazującym z ewentualnym warunkiem. Styl: "Run npm run lint. If exit code > 0: STOP and report failures. Do not proceed." Nie pisz "spróbuj uruchomić lint i sprawdź czy jest ok". Pisz precyzyjnie co Claude ma zrobić, z jakim narzędziem, i co zrobić gdy coś pójdzie nie tak.
Krok 3: Dodaj guardrails i przykłady
Sekcja "What NOT to do" to lista rzeczy których skill nigdy nie powinien robić: nie kasuj plików produkcyjnych, nie pushuj bezpośrednio na main, nie pomijaj testów przy flagach ASAP. Sekcja "Example output" pokazuje jak powinien wyglądać poprawny rezultat. Claude porównuje swój wynik z przykładem zanim uzna zadanie za skończone.
Struktura pliku:
# Nazwa skilla (jednoliniowy cel)
**Trigger:** /nazwa-skilla [opcjonalne argumenty]
**Steps:**
1. Krok pierwszy
2. Krok drugi (if X: BLOCKED)
...
**What NOT to do:**
- Lista zakazów
**Example output:**
[Przykład poprawnego wyniku]
Plik trafia do .claude/skills/nazwa-skilla.md. Claude Code automatycznie go odkrywa.
Przykład: skill do codziennego raportowania postępu
W jednym z naszych projektów (system zarządzania zadaniami dla klientów) mieliśmy powtarzający się workflow: sprawdź co zostało zrobione wcześniej, pobierz nowe zadania z API, wykonaj je sekwencyjnie, zaloguj wyniki do dokumentu. Robiłem to ręcznie każdy raz: kilkanaście kroków, copy-paste, sprawdzanie statusów. Po trzecim razie zbudowałem skill.
Uproszczona wersja SKILL.md tego skilla:
# Daily task runner (automated daily run for project task queue)
**Trigger:** /daily-run
**Context:**
- API base URL: read from .env
- My user ID: defined in .env CLAUDE_USER_ID
- Task list endpoint: /api/tasks?assignee=$CLAUDE_USER_ID&status=todo
**Steps:**
1. Get today's date: `date -Iseconds`
2. Fetch todo tasks: `curl -H "X-API-Key: $API_KEY" "$BASE_URL/api/tasks?assignee=$MY_ID&status=todo&limit=50"`
3. If 0 tasks: log "No tasks today" to daily-log document. DONE.
4. Sort tasks by priority (urgent > high > normal).
5. For each task:
a. Read task description fully.
b. If description has no CEL or KROKI section: BLOCKED - add comment "Niejasny opis" and skip.
c. Execute the steps from description.
d. Post a completion comment: POST /api/tasks/{id}/updates with result.
e. Mark done: PUT /api/tasks/{id} body: {"status": "done"}.
f. Verify status change with GET /api/tasks/{id}.
g. Sleep 0.5 between writes to avoid race conditions.
6. Update daily log document with done/blocked summary.
**What NOT to do:**
- Never execute multiple writes in parallel.
- Never delete tasks belonging to other users.
- Never mark a task done without posting a completion comment first.
**BLOCKED condition:** If a step requires access to a tool not available in this session:
post BLOCKED comment with exact tool name, do not attempt to workaround.
Budowa tego skilla zajęła 45 minut. Działa codziennie od kilku miesięcy. Co ważniejsze niż czas który zaoszczędził: błędy w wykonaniu zadań są teraz widoczne w logach jako komentarze w systemie, a nie ukryte w ręcznym procesie gdzie nikt nie wie co poszło nie tak.
Kluczowy detal tego skilla: sekcja "What NOT to do" zabrania równoległych zapisów. To nie jest oczywistość dla Claude'a bez tej instrukcji. Przy pierwszej wersji skilla (bez tej reguły) Claude próbował wykonywać dwa zadania jednocześnie i trafiał na race condition z API. Jedna linia w SKILL.md rozwiązała problem trwale.
Czy Claude Code skills różnią się od MCP?
Claude Code skills i MCP servers to dwie różne warstwy rozszerzania możliwości Claude Code, które często się mylą.
MCP (Model Context Protocol) daje Claude'owi dostęp do zewnętrznego narzędzia lub systemu. MCP server to serwis, który Claude może wywołać: serwer Githuba, baza danych, narzędzie do scraping, API zewnętrzne. MCP rozszerza co Claude może robić. Konfiguracja jest techniczna: JSON, serwer, transport layer.
Skills dają Claude'owi gotowy playbook jak ma postępować w konkretnej sytuacji. Skill nie daje nowych narzędzi, używa tych które już są dostępne (bash, pliki, MCP servers które są skonfigurowane). Skill jest prosty w tworzeniu: plik Markdown.
Kiedy co wybrać:
- Chcesz żeby Claude miał dostęp do nowego zewnętrznego systemu: MCP
- Chcesz żeby Claude wykonywał znany wieloetapowy workflow według stałych reguł: skill
- Chcesz połączyć obie warstwy: skill który w krokach używa skonfigurowanego MCP
W praktyce: MCP budujemy raz dla projektu, skills budujemy na bieżąco dla każdego powtarzającego się procesu. Skill do daily reportu korzysta z MCP dla bazy i MCP dla Githuba. Sam skill to tylko instrukcje.
Analogia która pomaga: MCP to jak zainstalowanie nowego programu na komputerze (daje nowe możliwości). Skill to jak napisanie instrukcji stanowiskowej dla pracownika korzystającego z zainstalowanych programów (mówi jak ich używać w konkretnym procesie). Oba są potrzebne, ale robią różne rzeczy. Zamiana jednego z drugim nie zadziała.
Kiedy warto budować własne Claude Code skills?
Claude Code skills warto budować gdy ten sam wieloetapowy workflow powtarza się regularnie i błędy w nim są kosztowne.
Trzy sygnały że czas zbudować skill:
-
Powtarzalność: robisz to samo > 3 razy w tygodniu. Każda ręczna iteracja to czas i ryzyko błędu. Skill eliminuje oba.
-
Złożoność: workflow ma > 5 kroków lub warunki rozgałęzienia ("jeśli API zwróci 404, rób X, jeśli 200, rób Y"). Bez ustrukturyzowanych instrukcji Claude traci kontekst przy długich zadaniach.
-
Wymagania jakości: wynik musi spełniać określone standardy (format raportu, checklist przed deployem, zatwierdzone wzorce kodu). Skill koduje te standardy raz i egzekwuje je za każdym razem.
Kiedy skill nie jest potrzebny: jednorazowe zadanie, prosty jednokrokowy workflow ("podsumuj ten plik"), zadanie które zmienia się przy każdym wykonaniu na tyle, że instrukcje generyczne nie pomogą.
Dodatkowy sygnał: jeśli za każdym razem gdy wykonujesz jakiś wieloetapowy proces musisz wracać do wcześniejszych notatek żeby przypomnieć sobie kolejność kroków, to jest właśnie sygnał że czas zbudować skill. Zamiast "notes for myself how to do X" stwórz SKILL.md i niech Claude go egzekwuje. Twoje notatki zamienisz na zestaw instrukcji którego możesz używać bez czytania za każdym razem od nowa.
Wdrożenie Claude Code skills w projekcie i w zespole
Skill wdrażasz w projekcie przez umieszczenie SKILL.md w .claude/skills/. Cały zespół ma dostęp gdy folder .claude/ jest commitowany do repozytorium (typowo tak, globalnie ignorowane są tylko .claude/settings.local.json które przechowuje lokalne dane środowiskowe).
Ważna kwestia bezpieczeństwa: skills mogą wykonywać dowolne polecenia bash, tworzyć pliki, wywoływać API, kasować dane. Zanim udostępnisz skill zespołowi, przejrzyj go pod kątem nieodwracalnych operacji. Dobry skill ma "pkt kontrolny" przy każdej operacji nieodwracalnej: "Confirm: delete all entries in staging database? [yes/no]". Nie zakładaj, że Claude będzie ostrożny z własnej inicjatywy, jeśli instrukcje nie definiują momentów zatrzymania.
Kilka praktycznych reguł:
- Jeden plik, jedno zadanie. Nie twórz skilla który robi 5 różnych rzeczy w zależności od argumentów. Lepiej 5 osobnych skilli z czytelnymi nazwami.
- Wersjonuj razem z kodem. Skill zmienia się razem z projektem. Jeśli zmienił się endpoint API, skill który go używa też powinien być zaktualizowany w tym samym commicie.
- Testuj na małym scope. Przed użyciem produkcyjnym uruchom skill na testowym projekcie lub z flagą dry-run jeśli ją obsługujesz. Claude nie ma instynktu "to brzmi ryzykownie, zapytam" przy jasnych instrukcjach.
- Dokumentuj co NIE jest w skopie. Sekcja "What NOT to do" to najważniejsza część. Opisuje granice skilla tak samo precyzyjnie jak same kroki.
Jeśli chcesz zobaczyć jak agentic workflow z Claude Code skills wygląda na produkcji, skontaktuj się przez stronę usług. Wdrożenia agentów AI i automatyzacje n8n plus AI zaczynamy od 2 000 PLN netto.
Skill który działa: jedno zadanie, jasne guardrails, wynik weryfikowalny w każdym kroku.