Jak napisać dobry SKILL.md: dobre praktyki od Anthropic i z własnych 26 skilli

Dobry SKILL.md ma krótki, konkretny opis w trzeciej osobie, który mówi Claude'owi, co skill robi i kiedy go użyć, oraz treść poniżej 500 linii, która resztę wiedzy trzyma w plikach ładowanych na żądanie. Tyle mówi dokumentacja Anthropic. Poniżej dokładam to, czego nauczyłem się na 26 skillach, które trzymam u siebie w ~/.claude/skills.

TL;DR

• Wymagane są tylko dwa pola: name (do 64 znaków, małe litery, cyfry, myślniki) i description (do 1024 znaków).
• Description to wyzwalacz. Pisz w trzeciej osobie, konkretnie, ze słowami, których naprawdę używasz w promptach. Jeśli piszesz po polsku, daj polskie słowa.
• Treść SKILL.md poniżej 500 linii, odnośniki do plików tylko jeden poziom w głąb, spis treści w plikach dłuższych niż 100 linii.
• Najpierw scenariusze testowe (co najmniej trzy), potem dokumentacja. Testuj na modelu, którego użyjesz.
• Pisz skrypty tak, żeby dało się je przeczytać w kilka minut. Ktoś, kto instaluje twój skill, powinien to zrobić.

Anatomia SKILL.md

Skill to folder z plikiem SKILL.md i opcjonalnymi plikami pomocniczymi. Anthropic definiuje go tak: "Each Skill packages instructions, metadata, and optional resources (scripts, templates) that Claude uses automatically when relevant." Plik zaczyna się od frontmattera YAML, pod nim są instrukcje w Markdownie.

Pola frontmattera i limity

Pole	Wymagane	Zasady z dokumentacji
name	tak	najwyżej 64 znaki, tylko małe litery, cyfry i myślniki, bez tagów XML, bez słów „anthropic” i „claude”
description	tak	niepusty, najwyżej 1024 znaki, bez tagów XML, mówi co skill robi i kiedy go użyć
disable-model-invocation	nie (Claude Code)	true oznacza, że Claude nie wywoła skilla sam, tylko ty przez /nazwa
user-invocable	nie (Claude Code)	false oznacza, że skill wywołuje tylko Claude

Przy nazwach Anthropic zaleca formę gerundium, czyli processing-pdfs. Akceptowalne są też pdf-processing i process-pdfs. Unikaj nazw typu helper, utils, tools, documents, data, files: nic nie mówią ani tobie, ani modelowi.

Minimalny przykład

Prosty skill do porządkowania notatek ze spotkań. Wymyśliłem go na potrzeby tego tekstu, ale tak wyglądają moje skille w praktyce:

meeting-notes/
  SKILL.md
  references/
    format.md

---
name: summarizing-meeting-notes
description: Summarizes meeting transcripts and notes into decisions, action items with owners and open questions. Use when the user pastes a meeting transcript or call notes, or asks for a meeting summary or a follow-up email.
---

# Summarizing meeting notes

1. Read the whole transcript before writing anything.
2. Extract decisions, action items (owner + deadline if stated) and open questions.
3. Never invent an owner or a deadline. Write "not stated" instead.
4. Use the output format from references/format.md.

Zwróć uwagę na trzy rzeczy. Nazwa mówi, co skill robi. Opis ma dwie części: co robi i kiedy go użyć. Format odpowiedzi siedzi w osobnym pliku, do którego SKILL.md prowadzi bezpośrednio.

Description to wyzwalacz, nie ozdobnik

To najważniejsza linia w całym pliku. Dokumentacja opisuje mechanizm progressive disclosure: metadane, czyli name i description, zajmują około 100 tokenów na skill i są w kontekście zawsze. Treść SKILL.md (według dokumentacji „Under 5k tokens”) ładuje się dopiero, gdy skill pasuje do zadania. Pliki dodatkowe i skrypty jeszcze później, na żądanie. Claude decyduje więc o użyciu skilla, widząc tylko opis.

Anthropic pisze wprost: "Always write in third person." Przykłady z dokumentacji:

Dobrze	Źle
„Processes Excel files and generates reports.”	„I can help you process Excel files.”
konkretne czynności i słowa kluczowe	„Helps with documents”

Polskie prompty, polskie słowa w opisie

Tu jest rzecz, której nie znajdziesz w dokumentacji, a która u mnie zrobiła różnicę. Piszę do Claude'a po polsku. Opisy zainstalowanych skilli są po angielsku. Gdy proszę o „paletę kolorów do aplikacji rezerwacyjnej”, w opisie nie ma ani jednego z tych słów. Dlatego w zainstalowanym skillu UI/UX Pro Max przepisałem description po polsku, żeby uruchamiał się na moje polskie prompty. Dokumentacja tego nie zabrania: wymaga tylko niepustego tekstu do 1024 znaków.

Ten sam opis spotkań w wersji dla kogoś, kto pisze po polsku:

description: Streszcza notatki i transkrypcje spotkań do listy decyzji, zadań z właścicielami i otwartych pytań. Używaj, gdy użytkownik wkleja transkrypcję lub notatki ze spotkania albo prosi o podsumowanie spotkania lub maila po spotkaniu.

W moich własnych skillach opis zawsze zawiera słowa, które faktycznie piszę. Skill humanizer pilnuje stylu polskich tekstów, fact-checker wymaga źródła dla każdej liczby, remove-ai-marks czyści niewidoczne znaki. Każdy z nich ma w opisie konkretne sytuacje: mail, oferta, post. Gdy opis był ogólny, skill albo milczał, albo odpalał się przy złych zadaniach.

Treść: poniżej 500 linii i jeden poziom odnośników

Dokumentacja: "Keep the SKILL.md body under 500 lines for optimal performance." Gdy zbliżasz się do tej granicy, dziel treść na pliki. Trzy zasady:

• Odnośniki jeden poziom w głąb. "Keep references one level deep from SKILL.md." SKILL.md może linkować do a.md, ale a.md nie powinien prowadzić dalej do b.md.
• Spis treści w długich plikach. Plik referencyjny dłuższy niż 100 linii dostaje spis treści na górze.
• W SKILL.md zostaje to, co potrzebne zawsze. Szczegóły formatów, długie przykłady i tabele idą do plików, które Claude czyta tylko wtedy, gdy ich potrzebuje.

To samo podejście opisuję szerzej w przewodniku po optymalizacji tokenów w Claude Code: im mniej ląduje w kontekście na starcie, tym lepiej.

Skrypty: zasady z dokumentacji

• „Solve, don't defer”. Skrypt obsługuje błędy sam, zamiast zostawiać je Claude'owi do rozwiązania.
• Bez „voodoo constants”. Każda stała w skrypcie ma uzasadnienie. Jeśli limit wynosi tyle, a nie inaczej, napisz dlaczego.
• Uruchomić czy przeczytać. W instrukcji napisz jasno, czy Claude ma skrypt wykonać, czy przeczytać go jako wzór.
• Ścieżki z ukośnikiem /, nigdy windowsowe.

Antywzorce

• ścieżki w stylu Windows,
• zbyt wiele opcji naraz zamiast jednej domyślnej drogi,
• informacje zależne od daty w głównej treści (stare wzorce trzymaj w osobnej sekcji),
• niespójna terminologia, czyli raz „faktura”, raz „rachunek” na to samo,
• zakładanie, że narzędzie jest zainstalowane.

Ostatni punkt widzę najczęściej w cudzych skillach. Jeśli skill potrzebuje Pythona albo Playwrighta, napisz to w SKILL.md i podaj, co zrobić, gdy go brak.

Testowanie: najpierw scenariusze, potem dokumentacja

Anthropic odwraca typową kolejność: "Create evaluations BEFORE writing extensive documentation." Przygotuj co najmniej trzy scenariusze, czyli prompty, na które skill powinien zareagować, i sprawdź wynik. Testuj na modelach, których użyjesz: Haiku, Sonnet albo Opus. Skill, który działa na jednym, nie musi działać tak samo na innym.

Jedna uczciwa uwaga: "There is not currently a built-in way to run these evaluations." Scenariusze uruchamiasz sam. U mnie to po prostu kilka promptów zapisanych obok skilla, które puszczam po każdej zmianie opisu. Dobrze dodać też scenariusz negatywny: prompt, przy którym skill nie powinien się uruchomić.

Pola specyficzne dla Claude Code

Domyślnie skill może wywołać zarówno użytkownik (przez /nazwa), jak i Claude sam. Dwa pola to zmieniają:

• disable-model-invocation: true: Claude nie wywoła skilla sam. Przydaje się przy skillach, które robią coś, czego nie chcesz uruchamiać przypadkiem.
• user-invocable: false: skill wywołuje tylko Claude, nie ma go jako komendy.

Gdzie leżą pliki: osobiste skille w ~/.claude/skills/<nazwa>/SKILL.md, projektowe w .claude/skills/<nazwa>/SKILL.md (te commitujesz dla zespołu), skille z pluginów wywołujesz jako /plugin-name:skill-name. Claude Code obserwuje katalogi skilli i łapie zmiany bez restartu, więc poprawki opisu sprawdzisz od razu. Starszy format .claude/commands/ nadal działa.

U siebie trzymam skille jako symlinki z ~/.agents/skills i rozdzielam prywatne od firmowych: firmowe leżą w osobnym katalogu .claude/skills w repozytorium firmowym. Dzięki temu skill do ofert prywatnych nie odpali się przy pracy dla pracodawcy.

Od czego zacząć

Repozytorium anthropics/skills (187 751 gwiazdek, listopad 2026) ma trzy rzeczy, które warto otworzyć przed pisaniem:

• skill skill-creator, który pomaga tworzyć nowe skille,
• katalog template/ z szablonem SKILL.md,
• katalog spec/ z plikiem agent-skills-spec.md, czyli specyfikacją formatu.

Repozytorium dodasz w Claude Code jako marketplace komendą /plugin marketplace add anthropics/skills. Jeśli dopiero zaczynasz ze skillami, przeczytaj najpierw czym są skille i jak je zainstalować, a potem rozbiór SKILL.md od frontend-design, który dobrze pokazuje, jak Anthropic pisze własne instrukcje.

Bezpieczeństwo, także dla autorów

Anthropic pisze: "Use Skills only from trusted sources: those you created yourself or obtained from Anthropic." oraz "Audit thoroughly: Review all files bundled in the Skill." Jako autor odwróć to pytanie: czy ktoś obcy przeczyta twój skill i uzna, że może mu zaufać?

Ta ostrożność ma podstawy. Snyk w raporcie ToxicSkills (luty 2026) przeskanował 3 984 skille z ClawHub i skills.sh. 1 467 z nich (36,82%) miało co najmniej jedną lukę bezpieczeństwa, 534 (13,4%) co najmniej jedną krytyczną, a badacze potwierdzili 76 złośliwych payloadów: kradzież danych logowania, backdoory, wyciek danych. Twój skill będzie oceniany na tym tle.

• Skrypty krótkie i czytelne, bez zaciemnionego kodu.
• Napisz w README, czy skrypty łączą się z siecią i czy coś instalują. Dobry wzór to README UI/UX Pro Max, które deklaruje, że skrypty używają tylko biblioteki standardowej, niczego nie instalują i nie łączą się z siecią. Sam sprawdziłem ich skrypty i importują tylko bibliotekę standardową Pythona.
• Nie wkładaj do skilla kluczy ani haseł. Skill to zwykłe pliki, które trafiają do repozytorium i do kontekstu modelu.
• Pamiętaj, że Agent Skills nie są objęte ZDR. Claude Enterprise może włączyć skanowanie treści własnych skilli wgrywanych w claude.ai i Cowork.

Zasada dla każdego, kto instaluje cudze skille, jest ta sama: przeczytaj SKILL.md i skrypty przed instalacją.

Checklista przed udostępnieniem skilla

Sprawdź	Kryterium
name	do 64 znaków, małe litery, cyfry, myślniki, bez „anthropic” i „claude”, najlepiej gerundium
description	do 1024 znaków, trzecia osoba, co robi i kiedy użyć, słowa z twoich promptów
Długość treści	poniżej 500 linii
Odnośniki	jeden poziom w głąb, spis treści w plikach dłuższych niż 100 linii
Skrypty	obsługują błędy, stałe uzasadnione, jasne „uruchom” albo „przeczytaj”, ścieżki z /
Zależności	wypisane, bez zakładania, że narzędzie już jest
Testy	co najmniej trzy scenariusze, na modelu, którego użyjesz
Bezpieczeństwo	bez sekretów, jasna informacja o sieci i instalacjach

FAQ

Jakie pola są wymagane w SKILL.md?
Tylko dwa: name i description. Name ma najwyżej 64 znaki, same małe litery, cyfry i myślniki, bez tagów XML i bez słów anthropic oraz claude. Description nie może być pusty, ma najwyżej 1024 znaki i mówi, co skill robi i kiedy go użyć.

Jak długi może być SKILL.md?
Anthropic zaleca, żeby treść SKILL.md miała mniej niż 500 linii. Gdy zbliżasz się do tej granicy, przenieś szczegóły do osobnych plików, do których SKILL.md linkuje bezpośrednio, bez łańcuchów odnośników.

Dlaczego Claude nie uruchamia mojego skilla?
Najczęściej winny jest description. Claude widzi na starcie tylko name i description, więc opis musi być konkretny, w trzeciej osobie i zawierać słowa, których używasz w promptach. Jeśli piszesz prompty po polsku, dodaj do opisu polskie słowa kluczowe.

Czy description można napisać po polsku?
Dokumentacja tego nie zabrania, wymaga tylko niepustego tekstu do 1024 znaków bez tagów XML. Sam przepisałem description zainstalowanego skilla UI/UX Pro Max po polsku, żeby uruchamiał się na moje polskie prompty.

Jak przetestować skill przed udostępnieniem?
Przygotuj co najmniej trzy scenariusze testowe, zanim napiszesz rozbudowaną dokumentację, i sprawdź skill na modelach, których faktycznie użyjesz: Haiku, Sonnet lub Opus. Wbudowanego narzędzia do uruchamiania takich ewaluacji na razie nie ma.

Ten tekst powstał w moim pipeline z wieloma subagentami, gdzie fact-checker i humanizer to właśnie skille opisane wyżej. Pod artykułem jest darmowa paczka dwóch skilli do pracy z UX: Laws of UX i szablon design systemu. Powiązane: skille do projektowania UI, kompletny przewodnik, UI/UX Pro Max: instalacja, test i bezpieczeństwo oraz najlepsze skille do Claude Code w 2026.