Jak stworzyć skill Claude: napisz SKILL.md w 10 minut

Testujemy skille Claude zawodowo, przetestowaliśmy ich już setki, i wzorzec jest przygnębiający: większość skilli, które oblewają nasz przegląd, nie oblewa dlatego, że autor nie umiał napisać instrukcji. Oblewają, bo skill nigdy się nie ładował, albo ładował się, kiedy nie powinien, albo był trzema skillami w jednym trenczkocie. Wszystko naprawialne na etapie tworzenia, nic z tego nie da się naprawić później ładniejszym README.

To tutorial, który chcielibyśmy, żeby każdy zgłaszający przeczytał najpierw. Na koniec będziesz mieć działający skill: checklistę do code review, która przepycha Claude poza "wygląda dobrze, może zmień nazwę tej zmiennej" w stronę sprawdzania warunków brzegowych, ścieżek błędów i martwego kodu. To celowo realny przykład. Najlepszy skill społecznościowy w naszej kategorii coding, Code Review Checklist, robi dokładnie to i zdobywa 8/10 za wynik. Twój nie pobije go pierwszego dnia, ale zrozumiesz każdą decyzję, jaką podjął autor tamtego skilla.

Obietnica "10 minut" jest uczciwa, z jednym zastrzeżeniem. Napisanie pierwszej działającej wersji zajmuje około 10 minut. Przetestowanie jej porządnie zajmuje kolejne 30. Pomiń drugą część, a dołączysz do połowy publikowanych skilli, które nie przetrwają kontaktu ze świeżą sesją. Sekcję zwłok opisaliśmy w dlaczego połowa skilli Claude nie działa i wolelibyśmy nie dodawać twojego do tego zbioru danych.

Jeśli nigdy nie instalowałeś skilla i nie wiesz, czym on jest, przeczytaj najpierw czym są skille Claude i jak je zainstalować. Ten wpis zakłada, że korzystałeś już z co najmniej jednego.

Krok 1: zawęź go do jednego zadania

Zanim napiszesz linijkę, zdecyduj, co robi twój skill. Potem przetnij to na pół.

Największa pojedyncza przyczyna awarii, jaką widzimy w testach, to skille, które próbują robić wszystko. "Pomaga w jakości kodu" brzmi jak rozsądny zakres. Nie jest. Taki skill chce odpalać się przy code review, refaktorach, pisaniu testów, pytaniach o linting i debatach architektonicznych, co w praktyce oznacza, że Claude nie potrafi rozpoznać, kiedy go załadować, więc ładuje się nieprzewidywalnie albo wcale. Problemy z wyzwalaniem to numer jeden przyczyna niskiej oceny skilla w naszej metodologii, przed złymi instrukcjami i zepsutymi instalacjami. Nie dlatego, że wyzwalanie jest najtrudniejszą częścią tworzenia skilla, tylko dlatego, że rozlazły zakres wcześniej w procesie robi z tego problem nie do rozwiązania później.

Jeden skill, jedno zadanie. Oto test: czy potrafisz dokończyć zdanie "użyj tego skilla, gdy użytkownik prosi o ___" jedną konkretną frazą czasownikową? "Zrecenzowanie pull requesta albo diffa" przechodzi. "Poprawienie ich kodu" oblewa. Jeśli twoje zdanie ma "i" albo "lub" łączące niepowiązane czynności, piszesz dwa skille. Napisz dwa skille. Foldery są za darmo.

W naszym przykładzie zakres to: zrecenzuj diff albo PR pod kątem błędów poprawności, według stałej checklisty, tłumiąc nitpicki stylistyczne. Nie "pomóż z recenzjami". Nie "zrecenzuj i napraw". Zrecenzuj, zaraportuj, stop.

Krok 2: szablon SKILL.md

Skill to folder z jednym wymaganym plikiem. Nasz idzie do ~/.claude/skills/ do użytku osobistego, albo .claude/skills/ wewnątrz repozytorium, jeśli ma go dostać cały zespół:

review-checklist/
  SKILL.md          ← wymagany, i często wszystko, czego potrzebujesz
  reference/        ← opcjonalny, ładowany tylko gdy Claude zdecyduje go przeczytać
  templates/        ← opcjonalny, pliki, do których odwołują się twoje instrukcje

Oto pełny SKILL.md, który zbudujemy, z adnotacjami. Skopiuj go, potem przeczytaj adnotacje, bo dwie z tych linijek mają dużo większe znaczenie niż reszta:

---
# 'name' to identyfikator: małe litery, myślniki, bez spacji.
# Claude go widzi, ale NIE steruje wyzwalaniem.
name: review-checklist

# 'description' to JEDYNA rzecz, którą Claude czyta, decydując,
# czy załadować ten skill. Wszystko poniżej frontmattera jest
# niewidoczne, dopóki ta decyzja nie zapadnie. Napisz go jak
# warunek wyzwalający, nie jak tekst marketingowy.
description: Use when the user asks to review code, review a
  PR, review a diff, or check a branch before merging. Runs a
  correctness-focused review checklist. Do NOT use for writing
  new code, fixing bugs the user already identified, or
  general refactoring requests.
---

# Code review checklist

When reviewing a diff or PR, work through this checklist in
order. Report only findings; do not fix anything unless asked.

## Procedure

1. Read the full diff before commenting on any line.
2. For each changed function, check:
   - Off-by-one risks at loop bounds and slice indices
   - Null/undefined paths: what happens when inputs are empty?
   - Error handling: are failures swallowed or logged and re-raised?
3. Check for dead code the change creates: unused imports,
   unreachable branches, orphaned helpers.
4. Check concurrency only if the diff touches shared state.
5. Verify new logic has test coverage. Missing tests are a
   finding, not a blocker.

## Reporting rules

- Max 10 findings, ordered by severity. If you found 30,
  report the 10 worst.
- Every finding needs a file, a line reference, and a one-line
  fix suggestion.
- Do NOT report: naming preferences, formatting, comment
  style, or anything a linter would catch.
- If the diff is clean, say so in one sentence. Do not invent
  findings to seem thorough.

To cały skill. Bez etapu buildowania, bez manifestu, bez rejestracji. Zrestartuj sesję Claude i już działa.

Frontmatter ma dokładnie dwa pola, które mają znaczenie. name to księgowość. description decyduje o wszystkim, i oto dlaczego: Claude trzyma w kontekście tylko nazwę i opis każdego zainstalowanego skilla. Treść twojego SKILL.md nie istnieje z perspektywy modelu, dopóki nie przeczyta opisu, nie zdecyduje "to pasuje do tego, czego chce użytkownik", i nie załaduje reszty. Genialna 200-liniowa checklista za mętnym opisem to genialna 200-liniowa checklista, której nikt nigdy nie wykona. W naszej rubryce oceniania wyzwalanie waży tyle samo, co jakość wyniku, dokładnie z tego powodu. Skill, który odpala się w 40% przypadków, to rzut monetą z dodatkowymi krokami.

Krok 3: napisz opis wyzwalacza

Skoro opis to warunek wyzwalający, napisz go jak warunek wyzwalający. Nazwij sformułowania, które wpisałby realny użytkownik. Uwzględnij przestrzeń negatywną, czyli sąsiednie prośby, przy których skill powinien milczeć.

Obok siebie, z realnych zgłoszeń, które testowaliśmy (lekko zanonimizowane):

Źle:

description: A powerful skill that helps improve code quality
  and catch issues early in the development process.

Dobrze:

description: Use when the user asks to review code, review a
  PR, review a diff, or check a branch before merging. Do NOT
  use for writing new code or fixing already-identified bugs.

Ten zły opisuje korzyść. Ten dobry opisuje moment. Claude nie czyta twojego opisu, żeby dać się przekonać; dopasowuje wzorce do faktycznych słów użytkownika. "Zrecenzuj ten PR" nie ma ani jednego wspólnego słowa z "pomaga poprawić jakość kodu", więc skill przesypia własny przypadek użycia. Testowaliśmy zgłoszenie niemal identyczne z tym złym przykładem: odpaliło się na 1 z 8 promptów w stylu code review. Po przepisaniu opisu tak, żeby nazywał sformułowania, ta sama treść, odpaliło się na 8 z 8.

Kolejna para, tym razem o przestrzeni negatywnej:

Źle:

description: Use for anything related to testing.

Dobrze:

description: Use when the user asks to write tests for
  existing code or asks what to test. Do NOT use when the
  user is doing TDD (writing tests before implementation) or
  debugging a failing test.

"Cokolwiek związanego z testowaniem" to sposób, żeby porwać sesję debugowania. Zbyt częste wyzwalanie jest cichsze niż zbyt rzadkie i równie szkodliwe: użytkownik dostaje odpowiedzi w stylu checklisty na pytania, które wymagały czegoś innego, obwinia model, odinstalowuje skill.

Mechaniczne zasady, które sprawdzają się we wszystkim, co testowaliśmy: nazwij trzy do pięciu konkretnych sformułowań użytkownika, dodaj co najmniej jedną klauzulę "do NOT use", trzymaj się poniżej mniej więcej 500 znaków i nigdy nie używaj słów "powerful", "comprehensive" ani "helps with". Te słowa korelują z niskimi ocenami za wyzwalanie w naszych danych na tyle konsekwentnie, że teraz reagujemy odruchowo na ich widok.

Krok 4: napisz treść, którą Claude faktycznie stosuje

Gdy skill się już załaduje, treść to zestaw instrukcji. Awaria tutaj jest subtelniejsza niż przy wyzwalaniu, ale równie częsta: instrukcje, które inspirują zamiast ograniczać. "Napisz dokładną, przemyślaną recenzję" to plakat motywacyjny. Claude już i tak chce być dokładny i przemyślany; to domyślne zachowanie, które próbujesz ukształtować, nie kształt sam w sobie.

Skille na szczycie naszych rankingów to listy ograniczeń. Test-Driven Development zabrania implementacji, zanim nie istnieje test, który zawodzi, kropka. Nasz przykładowy skill ogranicza liczbę znalezisk do 10 i zakazuje nitpickowania stylu wprost. Zwróć uwagę, ile jego linijek zaczyna się od "nie". To celowe. Modele domyślnie nadprodukują, więc najwartościowsze instrukcje są zwykle odejmujące.

Zasady dotyczące treści:

1. Ponumerowane procedury biją prozę. "Przejdź przez to po kolei" daje Claude kręgosłup; akapity dają mu klimat.
2. Podaj warunek zakończenia. Nasz skill mówi: zaraportuj znaleziska, nie naprawiaj. Bez tej linijki Claude pomocnie zacznie przepisywać kod, o co nikt nie prosił.
3. Zdefiniuj format wyniku. Maksymalne liczby, wymagane pola, jak wygląda czysty wynik. "Jeśli diff jest czysty, powiedz to" zapobiega wymyślaniu znalezisk, awarii, którą stale wyłapujemy w skillach typu review.
4. Rzadko potrzebne szczegóły umieść w plikach reference/. Jeśli twój skill ma 300-liniowy przewodnik stylu, który stosuje się raz w miesiącu, nie wklejaj go do SKILL.md, gdzie pali kontekst przy każdej aktywacji. Zapisz jako reference/style-guide.md i napisz "gdy użytkownik pyta o X, najpierw przeczytaj reference/style-guide.md". Claude załaduje go na żądanie.

Kiedy dodawać skrypty i szablony? Tylko wtedy, gdy instrukcje nie dają rady. Skill, który generuje konkretny plik konfiguracyjny, powinien dostarczyć templates/config.yaml i powiedzieć "skopiuj to, potem zmodyfikuj". Skill, który potrzebuje deterministycznego zachowania, powiedzmy parsowania formatu lockfile, powinien dostarczyć skrypt i polecić Claude go uruchomić zamiast reimplementować od zera za każdym razem. Ale większość skilli nie potrzebuje żadnego z nich. Nasz przykład nie potrzebuje żadnego. Każdy plik w folderze to coś, co teraz utrzymujesz, więc zasłuż na każdy z nich.

Krok 5: przetestuj lokalnie

Nie jesteś gotowy, gdy zadziała raz. "Zadziałało, kiedy próbowałem" to standard testowania każdego zepsutego skilla, jaki kiedykolwiek oblaliśmy. Oto minimalna bateria testów, i mapuje się blisko na to, co uruchamia nasza metodologia przy zgłoszeniach:

1. Świeża sesja. Zrestartuj Claude Code całkowicie. Skille ładują się na starcie sesji; testowanie w sesji, w której go napisałeś, niczego nie dowodzi.
2. Test wyzwalania, pozytywny. Wypróbuj trzy różne sformułowania, które wpisałby realny użytkownik: "zrecenzuj ten PR", "sprawdź ten diff, zanim zmergujesz", "przejrzyj moje zmiany". Wszystkie trzy powinny aktywować skill. Poznasz, że się odpalił, po tym, że wynik trzyma się twoich zasad (ograniczona, uporządkowana według wagi lista znalezisk wygląda zupełnie inaczej niż domyślna recenzja). Jeśli nie masz pewności, zapytaj Claude wprost, czy użył skilla.
3. Test wyzwalania, negatywny. Wypróbuj trzy sąsiednie prośby, które NIE powinny go odpalić: "napraw tego buga", "napisz funkcję parsującą daty", "dlaczego ten test nie przechodzi?". Jeśli twoja checklista recenzji pojawi się w sesji debugowania, opis potrzebuje klauzuli "do NOT use".
4. Porównanie z bazą odniesienia. Uruchom ten sam prompt recenzji w sesji ze skillem i bez niego. Jeśli nie potrafisz odróżnić wyników, skill nie zarabia na swój kontekst i powinieneś zaostrzyć ograniczenia. To nasz ulubiony test, bo jest bezlitosny. Około jedna trzecia skilli, które recenzujemy, go oblewa.
5. Test czystej instalacji. Jeśli planujesz publikację: skopiuj folder na inną maszynę (albo usuń i sklonuj od nowa), zastosuj się do własnego README dosłownie, i sprawdź, czy działa. Brakujące notatki o zależnościach umierają tutaj.

Cała bateria zajmuje 30 minut. Odfiltrowuje mniej więcej 80% awarii, jakie widzimy, co jest solidnym zwrotem za pół godziny.

Krok 6: przepuść przez walidator

Zanim opublikujesz, wklej swój SKILL.md do naszego darmowego walidatora skilli. Ocenia według tej samej rubryki, której używamy w recenzjach: długość i konkretność opisu, obecność konkretnych sformułowań wyzwalających, klauzule przestrzeni negatywnej, gęstość ograniczeń w treści, zdefiniowanie formatu, oczywiste antywzorce jak "powerful" i "anything related to".

To analiza statyczna, więc traktuj ją odpowiednio. Wyłapuje błędy widoczne w tekście, co w naszym doświadczeniu jest większością z nich, ale nie może uruchomić twojego skilla na żywych promptach. Przejście walidatora plus bateria z kroku 5 to prawdziwa poprzeczka. Samo przejście walidatora to zlintowany skill, który wciąż może się nie odpalać.

Jeśli wolisz interaktywną pomoc niż checker, Skill Creator od Anthropic to narzędzie, które polecamy. Zdobył 9,6 w naszych testach, buduje szkielet folderu, a jego etap optymalizacji opisu wymiernie poprawił wyzwalanie w naszych własnych wewnętrznych skillach. Używanie skilla do pisania skilli brzmi jak żart i działa mimo to.

Krok 7: opublikuj i zgłoś

Publikacja to normalne repozytorium GitHub. Konwencja układu:

your-repo/
  README.md           ← co robi, komenda instalacji, jeden przykład
  review-checklist/
    SKILL.md
    reference/

Umieść komendę instalacji w README jako blok do skopiowania, standardowy wzorzec to git clone plus cp -r review-checklist ~/.claude/skills/. Potem dodaj tag claude-skills do repozytorium. To nie dekoracja: tag to sposób, w jaki nasz crawler i każdy inny katalog odkrywa nowe skille. Repozytorium bez tagu jest w praktyce niewidoczne.

README warte napisania ma cztery rzeczy: jedno zdanie o tym, co robi skill, blok instalacyjny, jeden przykład przed/po, i wszelkie zależności. Przykład przed/po robi dla adopcji więcej niż wszystko inne razem wzięte, bo to jedyna część, która pokazuje, zamiast twierdzić.

Potem zgłoś go do SkillProof. Testowanie i wpis na listę są darmowe. Przepuszczamy zgłoszenie przez ten sam proces, co wszystko inne w katalogu: świeża instalacja z twojego README, bateria testów wyzwalania, porównanie z bazą odniesienia, ocena wyniku. Jeśli przejdzie, trafia na listę z oceną, a ty możesz wstawić odznakę "SkillProof tested" do swojego README. Dla nieznanego autora z dwudniowym repozytorium niezależny werdykt testowy to różnica między "losowym SKILL.md z internetu" a czymś, co obcy faktycznie zainstaluje. Jeśli nie przejdzie, dostajesz notatki o awariach, poprawiasz i zgłaszasz ponownie. Sporo skilli na liście przeszło przez dwie rundy.

Częste błędy, jakie widzimy w zgłoszeniach

Po kilkuset recenzjach wciąż pojawia się ta sama piątka.

Mętne opisy. Wciąż na pierwszym miejscu, z dużym zapasem. Jeśli twój opis mógłby opisywać trzy inne skille, nie opisuje żadnego z nich.

Skill kitchen-sink. Jeden SKILL.md obsługujący recenzje, commity, refaktory i dokumentację. Każde zadanie rozwadnia wyzwalacz pozostałych. Podziel to.

Powtarzanie domyślnych zachowań modelu. Treść, która mówi "bądź jasny, bądź dokładny, myśl krok po kroku" nic nie dodaje. Claude i tak to robi. Jeśli usunięcie linijki nie zmieniłoby wyniku, usuń tę linijkę.

Brak ograniczeń negatywnych. Skille, które mówią tylko, co robić, nigdy co przestać robić. Linijki "do NOT" to miejsce, gdzie żyje większość zmiany zachowania.

Nietestowane instrukcje instalacyjne. README mówi, że skopiuj jeden folder; skill po cichu zależy od drugiego skilla albo pakietu Pythona. Umiera na naszym teście czystej instalacji za każdym razem, i to najłatwiejsza do uniknięcia awaria na tej liście.

FAQ

Czy muszę umieć programować, żeby stworzyć skill Claude? Nie. SKILL.md to markdown z nagłówkiem YAML. Jeśli twój skill dostarcza skrypty pomocnicze, będziesz musiał je napisać, ale skille czysto instrukcyjne, czyli większość z nich, to zwykłe pisanie. Skill z tego wpisu nie zawiera ani linijki kodu.

Jak długi powinien być SKILL.md? Tak krótki, jak to możliwe, żeby wciąż ograniczać zachowanie, typowo 30 do 150 linii. Poniżej około 20 linii zwykle nic nie dodaje ponad domyślne zachowanie; powyżej kilkuset powinieneś przenosić szczegóły do plików reference/. Długość to koszt płacony przy każdej aktywacji, nie sygnał jakości.

Dlaczego mój skill się nie odpala? Prawie zawsze opis. Sprawdź, czy nazywa sformułowania, które faktycznie wpisuje użytkownik, zamiast opisywać korzyści, i potwierdź, że zrestartowałeś sesję po instalacji, bo skille ładują się na starcie sesji. Jeśli odpala się na niektórych sformułowaniach, a na innych nie, dodaj brakujące wprost do opisu.

Jaka jest różnica między skillem a serwerem MCP? Skill to instrukcje: markdown, który kształtuje zachowanie Claude, nigdzie nie działa żaden kod. Serwer MCP to program, który daje Claude nowe możliwości, jak zapytania do twojej bazy danych. Jeśli twój pomysł brzmi "Claude powinien podchodzić do X inaczej", to skill. Jeśli brzmi "Claude potrzebuje dostępu do Y", to MCP. Dłuższa wersja w Skille Claude vs MCP.

Czy mogę pobierać opłaty za skill Claude? Nie ma wbudowanego mechanizmu płatności; skille to pliki, a publiczny ekosystem działa na otwartych repozytoriach. Niektórzy autorzy sprzedają prywatne pakiety skilli zespołom jako usługi konsultingowe, co działa, bo wartością jest zakodowana ekspertyza, nie plik. Cokolwiek przeznaczone do publicznego katalogu powinno mieć otwartą licencję, bo nikt nie instaluje skilla, którego nie może przeczytać.

Zawęź do jednego zadania, napisz wyzwalacz jak regex w prozie, ograniczaj zamiast inspirować, i testuj w świeżej sesji, zanim komuś powiesz. To całe rzemiosło. Reszta to iteracja, a kolejka zgłoszeń jest otwarta.