Skill nie uruchamia się - dlaczego Claude go nie widzi

Claude Code

Skill nie uruchamia się - dlaczego Claude go nie widzi

W skrócie

Nic tak nie frustruje jak skill, który napisałeś, a którego Claude Code, oficjalne narzędzie CLI od Anthropic, uparcie nie widzi. Zwykle powód jest prozaiczny: plik leży nie tam, gdzie trzeba, ma literówkę w nagłówku albo opis, który nie mówi Claude, kiedy go użyć. Przejdźmy przez najczęstsze przyczyny po kolei, tak aby Twoja komenda wreszcie się pojawiła i uruchamiała.

Jak to wygląda w praktyce

Wpisujesz / w sesji i Twojej komendy nie ma na liście podpowiedzi. Albo komenda jest, ale gdy prosisz Claude, żeby sam skorzystał ze skilla w pasującej sytuacji, nic się nie dzieje - musisz wywoływać go ręcznie. Bywa też, że skill w ogóle nie wczytuje się przy starcie, mimo że plik istnieje. Wszystkie te objawy sprowadzają się do tego, że Claude Code albo nie znajduje definicji, albo nie potrafi jej poprawnie odczytać, albo nie wie, kiedy jej użyć.

Dlaczego Claude Code tak działa

Claude Code wykrywa komendy i skille po ścisłej konwencji lokalizacji i struktury. Komenda to plik Markdown w .claude/commands/ (w projekcie) lub ~/.claude/commands/ (globalnie); skill to katalog w .claude/skills/nazwa/ z plikiem SKILL.md w środku. Jeśli plik leży poza tymi ścieżkami albo skill nie ma pliku o dokładnej nazwie SKILL.md, narzędzie go nie zobaczy.

Druga rodzina przyczyn to nagłówek YAML. Otwierający znacznik --- musi być pierwszą linią pliku, a pola muszą należeć do dozwolonego zestawu - nieznane pole potrafi wywołać twardy błąd (na przykład komunikat o niespodziewanym kluczu we frontmatterze). Trzecia sprawa to opis: to na podstawie pola description Claude decyduje, kiedy skill jest przydatny. Zbyt ogólny opis sprawia, że Claude go nie kojarzy z sytuacją. Jeśli natomiast ustawisz disable-model-invocation, świadomie wyłączasz automatyczne uruchamianie - wtedy skill działa tylko na Twoje wyraźne wywołanie i to jest zachowanie zgodne z konfiguracją, a nie usterka.

Jak to rozwiązać krok po kroku

1. Sprawdź lokalizację. Komenda ma leżeć w .claude/commands/ lub ~/.claude/commands/, a skill w .claude/skills/nazwa/SKILL.md. Potwierdź, że nie zapisałeś pliku w innym katalogu.
2. Zweryfikuj nazwę pliku skilla. Musi to być dokładnie SKILL.md (wielkość liter ma znaczenie), a plik musi siedzieć we własnym podkatalogu o nazwie skilla.
3. Popraw nagłówek YAML. Upewnij się, że pierwsza linia pliku to ---, że nagłówek jest poprawnie zamknięty drugim --- i że używasz wyłącznie dozwolonych pól (jak name, description, allowed-tools). Nieznane pole może zablokować wczytanie.
4. Napisz konkretny description. Zamiast pomaga z kodem napisz, do czego dokładnie służy i kiedy go użyć - to po tym opisie Claude decyduje o automatycznym uruchomieniu.
5. Sprawdź disable-model-invocation. Jeśli je ustawiłeś, Claude nie odpali skilla sam - wywołaj go ręcznie przez /nazwa. Jeśli chcesz, żeby uruchamiał się automatycznie, usuń to pole.
6. Przeładuj listę komend. Wpisz / i poszukaj komendy; jeśli dodałeś plik w trakcie sesji, zrestartuj sesję Claude Code, żeby odświeżył wykrywanie.
7. Wyklucz konflikt nazw i zasięgu. Jeśli komenda o tej samej nazwie istnieje w kilku miejscach (projekt, katalog domowy, wtyczka), sprawdź, która wersja się ładuje, i ujednolić nazewnictwo.

Jak sprawdzić, że zadziałało

Po poprawkach wpisz / - komenda powinna pojawić się na liście z Twoją nazwą i opisem. Uruchom ją i potwierdź, że wykonuje zapisany prompt. Aby sprawdzić automatyczne wywołanie skilla, opisz Claude sytuację pasującą do jego description bez podawania nazwy - jeśli opis jest trafny i nie ustawiłeś disable-model-invocation, Claude sam sięgnie po skill. Gdy nagłówek miał błąd, po jego naprawie zniknie komunikat o niespodziewanym kluczu we frontmatterze.

Wróć do listy: 100 najczęstszych problemów z Claude Code

Szkolenie Claude Code - od zera do zespołu agentów AI -->

Szkolenie Claude Code - od zera do zespołu agentów AI

Tryb planowania, tryby uprawnień, komendy, MCP, hooki i systemy multi-agent - wszystko na żywym kodzie podczas trzydniowego szkolenia. Prowadzi Łukasz Matuszewski. Szkolenie ma terminy gwarantowane - odbędzie się niezależnie od liczby zgłoszeń.

Sprawdź szkolenie Claude Code

To szkolenie może być dofinansowane dla Ciebie z KFS lub BUR.

★★★★★Średnia ocena naszych szkoleń w Google: 5/5