Jak napisać własny Skill w Claude Code. Od procesu do działającego SKILL.md.
Napisałem swój pierwszy Skill który działał. Wyrzuciłem go dwa tygodnie później.
Nie dlatego że był zepsuty. Dlatego że był zły. Działał, ale nie robił tego co powinien. Claude go interpretował inaczej niż zakładałem, wyniki były niespójne, a kiedy próbowałem go poprawić, okazało się że problem był na poziomie fundamentalnym, nie w szczegółach.
Drugi był lepszy. Trzeci działa w produkcji od miesiąca i używam go codziennie.
Zebrałem z tego procesu kilka rzeczy których nauczyłem się w trudniejszy sposób niż musiałem.
Zanim otworzysz edytor
Największy błąd pierwszego Skilla polegał na tym że zacząłem od pisania. Wiedziałem że chcę Skill do code review, wiedziałem że SKILL.md to plik YAML z instrukcją i zacząłem pisać. Wynik był listą ogólnych zasad opakowaną w nagłówki.
Skill nie jest listą zasad. Skill to procedura. Żeby napisać dobrą procedurę, musisz odpowiedzieć na trzy pytania zanim napiszesz cokolwiek.
Co dokładnie robi ten proces kiedy go wykonujesz? Nie ogólnie, krok po kroku. Gdzie zaczynasz, co sprawdzasz, gdzie podejmujesz decyzje, co jest outputem.
Gdzie są decyzje które musi podjąć człowiek? To będą stop conditions w twoim Skilla. Miejsca gdzie Claude ma się zatrzymać i zapytać zamiast zgadywać.
Jak wygląda dobry output? Konkretnie. Jeśli nie możesz opisać jak wygląda wynik kiedy Skill zadziałał dobrze, Claude też nie będzie wiedział kiedy skończyć.
Te trzy pytania zajmują pięć minut. Oszczędzają kilka godzin przerabiania.
Potrzebujesz pomocy z tym tematem?
Pomagam firmom wdrażać nowoczesne rozwiązania. Umów bezpłatną 30-minutową rozmowę.
Umów bezpłatną rozmowę →
Anatomia SKILL.md
Plik ma dwie części. Nagłówek YAML między --- to metadane które Claude czyta zawsze, przy każdej sesji, żeby wiedzieć czy Skill jest releventny. Treść po nagłówku to instrukcja operacyjna którą Claude czyta kiedy Skill jest aktywowany.
W nagłówku masz kilka pól które mają znaczenie praktyczne.
name to komenda przez którą wywołujesz Skill. Piszesz /code-review, Claude wie że ma uruchomić Skill o nazwie code-review.
description to najważniejsze pole po nazwie. Claude czyta to żeby zdecydować czy aktywować Skill automatycznie gdy kontekst pasuje. Pisz konkretnie co Skill robi i kiedy go używać. „Pomaga z kodem” to zły opis. „Code review przed commitem, sprawdza bezpieczeństwo i zgodność z ESLint, użyj po napisaniu nowej funkcji” to dobry opis.
allowed-tools to lista narzędzi do których Skill ma dostęp. Minimalizm: tylko to co faktycznie potrzebuje. Jeśli Skill tylko czyta pliki i odpowiada, daj mu Read i Glob. Nie dawaj Bash jeśli nie wywołuje komend.
user-invocable: true sprawia że możesz wywołać Skill przez /nazwa. Dla własnych Skills prawie zawsze chcesz tego.
Jak pisać instrukcję żeby Claude ją rozumiał
Największa różnica między Skillem który działa spójnie a Skillem który za każdym razem robi coś innego to precyzja instrukcji.
Claude rozumie sekwencje. „Najpierw zrób X, potem Y, potem Z” jest dla niego jasne. „Pamiętaj o X, Y i Z” to lista zasad którą stosuje w dowolnej kolejności i z dowolną interpretacją.
Zamiast kategorii, pisz etapy. Zamiast „Sekcja: Bezpieczeństwo”, pisz „Krok 2: Sprawdź walidację wejść na granicach systemu”. Etapy dają sekwencję, kategorie dają przestrzeń do interpretacji.
Zdefiniuj output konkretnie. Jeśli Skill ma wygenerować raport, napisz jak raport ma wyglądać. Nagłówki, sekcje, format. Claude odtworzy ten format. Bez definicji formatu Claude produkuje co mu się wydaje odpowiednie, i za każdym razem może to wyglądać inaczej.
Napisz co Skill nie robi. Claude jest domyślnie pomocny i rozszerza zakres zadania jeśli widzi coś co mógłby poprawić. Jeśli chcesz Skill do code review, nie do refaktoringu, napisz wprost: „nie sugerujesz refaktoringu jeśli nie był proszony, skupiasz się wyłącznie na bugach i bezpieczeństwie.”
Dodaj stop conditions. Miejsca gdzie Claude ma się zatrzymać zamiast kontynuować: „jeśli zidentyfikujesz więcej niż trzy krytyczne problemy, zatrzymaj się i zapytaj czy kontynuować zanim przejdziesz dalej.”
Zrób to z ekspertem
Bezpłatna 30-minutowa konsultacja — bez zobowiązań.
Zarezerwuj termin →
Konkretny przykład: od procesu do SKILL.md
Mam w agencji proces przygotowania specyfikacji technicznej z briefu klienta. Zanim miałem Skill, wyglądał tak: czytałem brief, wyłapywałem co jest jasne a co nie, wymyślałem pytania które trzeba zadać przed wyceną, estymowałem złożoność poszczególnych elementów.
Kiedy napisałem to jako Skill, zacząłem od opisania tego procesu werbalnie. Krok po kroku. Okazało się że mam pięć etapów i trzy miejsca gdzie zawsze zatrzymuję się żeby zapytać klienta albo kolegę.
Frontmatter:
---
name: brief-do-spec
description: >
Przetwarza brief klienta na specyfikację techniczną.
Wypisuje co jest jasne, co wymaga dopytania, estymuje złożoność.
Użyj po pierwszej rozmowie z klientem.
version: 1.0
user-invocable: true
allowed-tools:
- Read
---Instrukcja zaczyna się od: „Na podstawie $ARGUMENTS (brief klienta lub ścieżka do pliku).” Potem pięć etapów numerowanych. Potem definicja outputu z nagłówkami które mają pojawić się w specyfikacji. Potem sekcja „czego nie robisz”: nie wyceniasz w godzinach, nie zakładasz że czegoś nie ma w briefie jeśli nie zostało powiedziane wprost, nie kontynuujesz jeśli brakuje informacji o stacku technicznym.
Wersja 1.0 działała w 70%. Wersja 1.1, po tygodniu używania i trzech iteracjach, działa w 90%. Idealny nie istnieje, ale 90% wystarczy do produkcji.
Gdzie Skill trafia i jak go wywołać
Globalnie, przez npx skills add albo ręcznie do ~/.claude/skills/nazwa/, Skill jest dostępny we wszystkich projektach we wszystkich sesjach.
Lokalnie, w katalogu .claude/skills/nazwa/ w projekcie, Skill jest dostępny tylko w tym projekcie. Jeśli dodasz go do repozytorium, każdy kto sklonuje repo ma go automatycznie. Dobre dla konwencji projektu, złe jeśli Skill zawiera coś poufnego.
Lokalny Skill o tej samej nazwie co globalny wygrywa. Możesz mieć ogólny code-review globalnie i specyficzny dla klienta code-review lokalnie w jego projekcie.
Trzy iteracje zanim uznasz że Skill jest gotowy
Wersja 1.0 to hipoteza. Piszesz co myślisz że powinno działać. Testujesz. Patrzysz gdzie Claude interpretuje inaczej niż zakładałeś. To są miejsca gdzie instrukcja jest niejednoznaczna, nie miejsca gdzie Claude jest głupi.
Wersja 1.1 poprawia niejednoznaczności z 1.0. Zwykle to kwestia bardziej precyzyjnych etapów, lepiej zdefiniowanego outputu i kilku stop conditions których nie pomyślałeś przy pierwszym podejściu.
Wersja 1.2, po kolejnym tygodniu używania, zazwyczaj jest wystarczająco dobra żeby powiedzieć że Skill jest stabilny.
Skills to żywe dokumenty. Nie szlifujesz ich zanim wypuścisz. Wypuszczasz i iterujesz. Wersja 1.0 zawsze jest niedoskonała. Wersja 1.5 prawie zawsze jest przydatna.
Kiedy Skill nie jest odpowiedzią
Przez miesiąc próbowałem napisać Skill do estymacji godzin dla ofert. Nie działał. Nie dlatego że był źle napisany. Dlatego że estymacja w agencji zależy od zmiennych których Skill nie może znać: kto będzie to robił, jaki jest teraz poziom stresu w zespole, jak bardzo lubimy tego klienta, ile mamy innych projektów w tym czasie.
Wyrzuciłem go. Skills najlepiej działają gdzie proces jest powtarzalny i ma jasny output. Gdzie wymagana jest ekspercka ocena z nieprzewidywalnych zmiennych, Skill może pomóc w przygotowaniu, ale decyzja zostaje przy człowieku.
To nie jest wada Skills. To jest uczciwe rozgraniczenie między tym co można ustrukturyzować a tym co wymaga osądu.
To trzecia część serii o Skills w Claude Code. Poprzednie: Twoja firma też ma amnezję, Skills to nie są prompty, Jak znaleźć dobre Skills.
]]>Zostań w pętli
Nowe artykuły, narzędzia i case study — prosto na maila.
