Claude Code zignorował mój skill 5 razy. Naprawiła to 1 linijka

Skill w Claude Code może działać bez zarzutu, gdy wywołasz go po nazwie, a mimo to nigdy nie załadować się sam. Nasz działał za każdym razem, gdy wpisaliśmy jego nazwę, i był pomijany za każdym razem, gdy prosiliśmy o to samo zwykłymi słowami. Patrzyliśmy, jak jest pomijany, przeczytaliśmy dlaczego i przepisaliśmy jedną linię, która to naprawiła.

Skill to zapisany zestaw instrukcji, który Claude Code podejmuje sam, gdy twoja prośba do niego pasuje. O dopasowaniu decyduje jedna linia, którą Claude czyta, zanim wybierze, a nie twoje instrukcje. Sześć kroków poniżej prowadzi od promptu, który wciąż wpisujesz od nowa, do skilla ładującego się samodzielnie, plus test dwudziestu próśb, który wyłapie pominięty skill, zanim zrobi to twój zespół.

Test (ta sama prośba, świeże sesje)	Skill załadowany
Wywołany po nazwie (/release-notes)	2 z 2
Zwykłe słowa, oryginalny opis	0 z 5
Zwykłe słowa, przepisany opis	5 z 5

Skill to folder z jednym plikiem w środku, SKILL.md. Plik zaczyna się od krótkiego nagłówka (nazwa i jednozdaniowy opis), po którym idą instrukcje. Działa jak funkcja: wywołujący czyta sygnaturę i docstring, a ciało uruchamia się dopiero wtedy, gdy zostanie wywołane. Zapisz go w katalogu domowym, by mieć go w każdym projekcie, albo w repozytorium, żeby dostał go każdy, kto tam pracuje.

Zacznij od zadania, nie od pliku. Weź prompt, który wciąż wpisujesz od nowa, i zapisz dokładny wynik, jakiego chcesz. Nasz to cotygodniowe release notes: commity od poniedziałku, pogrupowane według obszaru, bez chore'ów, jedna linia na zmianę z numerem pull requesta. W open-source'owym repozytorium Hono ten długi prompt dał czyste notatki dla ośmiu poprawek błędów z tygodnia i ten wynik stał się celem, który skill musiał trafić.

Nie każdy prompt zasługuje na skill. Jednorazowe pytanie nie, a skill, którego nigdy nie użyjesz ponownie, to kolejna linia, którą Claude musi przeczytać. Prowadź krótką listę promptów, które wpisujesz co tydzień; ten na szczycie zostaje twoim pierwszym skillem.

Utwórz .claude/skills/release-notes/SKILL.md w swoim projekcie: folder skills wewnątrz ukrytego folderu .claude, folder nazwany jak skill i plik skilla w środku. Folder ma znaczenie. Luźny release-notes.md w ogóle się nie ładuje, a dokumentacja wymienia to jako pierwszą rzecz do sprawdzenia.

Nagłówek to kilka opisanych linii między dwoma rzędami kresek i musi zaczynać się w pierwszej linii pliku, inaczej Claude Code go ignoruje. Nasz miał nazwę, release-notes, i opis, jaki napisałaby większość osób:

---
name: release-notes
description: Generates changelog documents from repository history.
---

Pod nagłówkiem idą instrukcje jako ponumerowane kroki, takie, jakie dałbyś nowemu koledze z zespołu. Nasz ma pięć: znajdź commity od poniedziałku, pomiń commity chore i docs, pogrupuj według zakresu conventional commits, napisz jedną prostą linię na zmianę i wypisz blok z tytułem i krótkim podsumowaniem na górze. Anthropic zaleca, by ta część była krótka. Nie musisz restartować: Claude Code podejmuje nowy lub edytowany skill w sesji, w której już jesteś.

Przetestuj go po nazwie: wpisz ukośnik, wybierz skill w menu, naciśnij enter. W świeżych sesjach nasz czytał log commitów, grupował poprawki według obszaru i pisał notatki dokładnie tak, jak chcieliśmy, za każdym razem. Haczyk w tym, że ty i każdy w twoim zespole musicie pamiętać jego nazwę.

Kolega z zespołu nie wpisze nazwy skilla. Otworzy nową sesję i poprosi tak, jak poprosiłby ciebie. Przetestuj więc właśnie to: otwórz świeżą sesję (nową rozmowę, w której nic nie jest załadowane) i poproś o zadanie własnymi słowami. Ma być świeża, bo już użyty skill zostaje w rozmowie, a test w takiej sesji niczego nie dowodzi.

Wpisaliśmy „what did we ship this week?”. Claude sam uruchomił log commitów i napisał podsumowanie po swojemu, bez śladu skilla. Odpowiedzi nie były złe, ale różniły się między uruchomieniami: jedna liczyła od poniedziałku, inna od ostatniego tagu wydania i wciągnęła zmianę w dokumentacji, którą skill by pominął. W pięciu świeżych sesjach skill został pominięty we wszystkich pięciu.

Pięć uruchomień to demo, nie statystyka. Ale skill, który działa po nazwie i jest za każdym razem pomijany w zwykłych słowach, nie wykonuje swojej pracy, a ponieważ przeszedł test po nazwie z kroku drugiego, nigdy nie przyszłoby ci do głowy tego sprawdzać.

Zanim zmienisz choć słowo, zrób trzy sprawdzenia:

1. /skills wypisuje każdy skill, który widzi sesja. Wyszukaj swój. Nasz był na liście i włączony, ale w konfiguracji było 277 skilli, a kilka skilli z pluginów pasowało do „release” przed naszym.
2. claude --debug zapisuje szczegółowy log tego, co ładuje Claude Code. Poszukaj linii o skillach. U nas projektowy skill był załadowany, a do tego pojawiło się ostrzeżenie, że lista skilli przekracza budżet, więc część opisów jest ucinana.
3. claude plugin validate .claude/skills sprawdza, czy nagłówek jest poprawnie zbudowany. To ważne: zepsuty nagłówek nadal pozwala uruchomić skill po nazwie, ale Claude nie potrafi go już dopasować sam. Nasz przeszedł.

Sprawdzenie	Co ci mówi	Nasz wynik
/skills	Czy skill jest widoczny i włączony?	Na liście, włączony (277 skilli)
--debug	Czy się załadował? Czy lista jest ucięta?	Załadowany; ostrzeżenie o przekroczeniu budżetu listy
plugin validate	Czy nagłówek się parsuje?	Przeszedł

Gdy plik jest załadowany, a nagłówek poprawny, przyczyną jest opis. Dopóki Claude nie zdecyduje się załadować skilla, nie czyta twoich instrukcji. Czyta jedną linię na skill, nazwę i opis, i dopasowuje je do twoich słów. Nasz mówił „generates changelog documents from repository history”; prośba mówiła „what did we ship this week”. Te dwa zdania nie mają wspólnego słowa. Claude nigdy nie przeczytał naszych instrukcji; przeczytał jedną linię, a ta linia nie używała naszych słów.

Ostrzeżenie o budżecie oznacza, że Claude Code przycina opisy, żeby wszystko się zmieściło, najpierw te najrzadziej używane, a zupełnie nowy skill jest ze wszystkich używany najrzadziej. Sprawdź, czy twój przetrwał: nasz tak, bo prośby z jego własnymi słowami nadal go ładowały.

Napisz opis na moment, gdy ktoś prosi, a nie dla pliku. Powiedz, co skill robi, kiedy go użyć i jakich słów ludzie naprawdę używają. Nasz stał się:

description: Writes this week's release notes from git log, grouped by scope (router, css, jsx). Use when the user asks what we shipped, what changed this week, for release notes, a changelog, or a summary of recent commits.

Przewodnik Anthropic o pisaniu skilli dodaje jedną zasadę: pisz w trzeciej osobie („Writes”), nigdy „I can help” ani „You can use this”.

Potem udowodnij to w świeżej sesji z tą samą prośbą. „What did we ship this week?” teraz załadowało skill, zanim Claude cokolwiek ruszył, a notatki wyszły w naszym formacie, w pięciu na pięć świeżych sesji.

Zrób też punkt odniesienia: wyłącz skill nadpisaniem skilla w lokalnym pliku ustawień (ukrywa go bez usuwania). Po wyłączeniu Claude wracał do własnego podsumowania; po włączeniu skill się ładował. Różnicę zrobił skill, nie przypadek.

Ograniczenie: opis, który pasuje do zbyt wielu rzeczy, sprawia, że skill odpala tam, gdzie nie powinien. Dodawaj słowa, których naprawdę używasz, a nie wszystkie, jakie przyjdą ci do głowy.

Jedna prośba udowodniła poprawkę; skill, na którym polega zespół, jest wywoływany na wiele sposobów. Skill-creator od Anthropic opisuje test: dwadzieścia próśb, mieszanka takich, które powinny załadować skill, i bliskich pudeł, które nie powinny. Bliskie pudło brzmi podobnie, ale to inne zadanie, na przykład „write a commit message for my staged changes”. Uruchom każdą prośbę w osobnej świeżej sesji i zanotuj, czy skill się załadował. Własny skrypt skill-creatora nie widział skilla w naszej wersji Claude Code, więc te same dwadzieścia próśb uruchomiliśmy własnym krótkim skryptem.

Opis	Prośby, które powinny go załadować i to zrobiły	Bliskie pudła, które go załadowały
Oryginalny	4 z 10	0 z 10
Przepisany	10 z 10	0 z 10

Przed przepisaniem skill ładował się tylko przy prośbach, które już zawierały „release notes”, „changelog” lub „release”: dopasowywanie słów z kroku czwartego, jak na dłoni. Po przepisaniu ładował się przy każdej prośbie, przy której powinien, i nadal omijał każde bliskie pudło.

Skill, który nigdy nie może zawieść, wymuś. Wpisz jego nazwę albo dodaj hook (mały skrypt, który Claude Code uruchamia w ustalonym momencie, tu przy każdej wysłanej wiadomości), którego wyjście każe Claude użyć skilla do tego zadania. Z hookiem nawet oryginalny opis załadował skill przy zwykłej prośbie. Ograniczenie: każde uruchomienie testu kosztuje realny limit użycia, a hook dodaje linię do każdej wiadomości, więc zachowaj go dla niewielu skilli, które naprawdę muszą się odpalić. Uruchamiaj swoją listę ponownie, ilekroć zmieniasz opis.

Nasz skill do release notes działał za każdym razem po nazwie, był pomijany w każdej świeżej sesji w zwykłych słowach, a jedna przepisana linia sprawiła, że ładował się za każdym razem. Powód: Claude czyta jedną linię na skill, zanim zdecyduje, i dopasowuje twoje słowa, a nie twoje intencje.

Skill się opłaca przy zadaniu, które powtarzasz ze stałym wynikiem: cotygodniowe notatki, opis pull requesta, checklista wydania. Nie opłaca się przy jednorazowym pytaniu i nie jest narzędziem do reguły, która musi zawsze obowiązywać; to zadanie dla hooka. Kosztuje cię też stos nieużywanych skilli, bo gdy jest ich za dużo, Claude Code zaczyna ucinać opisy, najrzadziej używane najpierw. Dobry opis podnosi szanse, ale nie sprawi, że skill odpali przy zadaniu, do którego nigdy nie był przeznaczony, a garść uruchomień to demo, więc twoja lista próśb testowych jest prawdziwym sprawdzianem.

Jedna zasada: pisz opis słowami, których naprawdę używasz, gdy prosisz o to zadanie.