Skill Claude się nie odpala? Napraw to w 6 krokach

Zainstalowałeś skill, poprosiłeś Claude'a o rzecz, do której ten skill służy, a Claude zachował się, jakby skill nie istniał. Bez błędu, bez ostrzeżenia, bez niczego do grepnięcia. Cisza.

Widzimy to bez przerwy. SkillProof instaluje i testuje każdy skill z naszego katalogu na czystej maszynie, a nieodpalanie się to najczęstszy defekt, jaki znajdujemy. Jest też najbardziej naprawialny: prawie każde zgłoszenie „skill nie działa" w naszych logach testowych sprowadza się do jednej z sześciu przyczyn, a pięć z nich wyklucza się w mniej niż minutę.

Najpierw przejdź checklistę. Reszta artykułu rozwija każdy check o objaw, przyczynę i fix.

Checklista na 30 sekund

1. Właściwy folder? Plik musi być w ~/.claude/skills/<skill-name>/SKILL.md, jeden folder na skill, nazwa pliku dokładnie SKILL.md.
2. Był restart? Claude skanuje skille na starcie sesji. Zmiany zrobione w trakcie sesji są niewidoczne do restartu.
3. Kolizja nazw? Dwa skille z tym samym name przesłaniają się nawzajem. Przeżywa tylko jeden.
4. Opis zbyt mglisty? Jeśli opis nie wymienia tego, o co użytkownicy dosłownie proszą, Claude nigdy go nie dopasuje. To przyczyna numer jeden.
5. Frontmatter poprawny? Jeden zepsuty znak YAML czyni cały skill niewidzialnym, po cichu.
6. Konfliktujący skill? Inny zainstalowany skill z nakładającym się opisem może wygrywać dopasowanie.

Jeśli wszystkie sześć przechodzi, a skill się aktywuje, ale output się nie zmienia, to inna awaria. Skocz do sekcji gdy się odpala, ale nic nie robi.

Check 1: skill leży w złym folderze

Objaw. Skill nigdy nie pojawia się, gdy pytasz Claude'a „jakie skille masz zainstalowane?". Jakbyś nigdy go nie skopiował.

Przyczyna. Claude patrzy tylko w konkretne miejsca: ~/.claude/skills/ dla skilli osobistych i .claude/skills/ w projekcie dla projektowych. Wewnątrz układ jest ścisły: jeden folder na skill, z plikiem o nazwie dokładnie SKILL.md. Błędy, które przy instalowaniu społecznościowych skilli do testów widzimy najczęściej: kopiowanie całego sklonowanego repo (ścieżka robi się skills/some-repo/skills/pdf-helper/SKILL.md, o poziom za głęboko), wrzucenie SKILL.md bezpośrednio do ~/.claude/skills/ bez własnego folderu i pisane małymi literami skill.md, które część systemów plików wybacza, a część nie.

Fix. Zweryfikuj z terminala:

ls ~/.claude/skills/*/SKILL.md

Każdy oczekiwany skill powinien wypisać dokładnie jedną linijkę. Jeśli skilla brakuje albo jego ścieżka ma dodatkowe zagnieżdżenie, przenieś folder tak, żeby SKILL.md leżał jeden poziom poniżej skills/. Nasz przewodnik instalacji przechodzi poprawny układ dla każdej platformy.

Check 2: nie zrestartowałeś

Objaw. Struktura folderów jest poprawna, naprawiłeś ją dwie minuty temu, a Claude wciąż nie widzi skilla w tej samej rozmowie.

Przyczyna. Odkrywanie skilli dzieje się raz, na starcie. Claude czyta frontmatter każdego SKILL.md, jaki znajdzie, i trzyma ten indeks przez całą sesję. Skill dodany, przemianowany albo zedytowany w trakcie sesji nie istnieje z punktu widzenia działającej sesji.

Fix. W Claude Code wyjdź i zacznij nową sesję. W aplikacji desktopowej zamknij ją całkowicie przez Cmd+Q na macOS (zamknięcie okna się nie liczy) i otwórz ponownie. To tak tanie do wykluczenia, że robimy to przed każdym głębszym debugowaniem — tak jak restartujesz router, zanim zadzwonisz do dostawcy internetu.

Check 3: kolizja nazw przesłania twój skill

Objaw. Zainstalowałeś skill, folder się zgadza, zrestartowałeś, a lista skilli pokazuje albo nic nowego, albo inny skill odpowiadający na tę samą nazwę.

Przyczyna. Nazwy skilli muszą być unikalne. Jeśli skill osobisty i projektowy dzielą name albo dwa zainstalowane packi wysyłają po skillu o nazwie seo-audit, jeden przesłania drugi bez ostrzeżenia. Trafiliśmy na to we własnej pracy nad katalogiem: dwa packi marketingowe zainstalowane obok siebie dały cichy duplikat i ten, którego chcieliśmy, nigdy się nie załadował.

Fix. Poszukaj duplikatów:

grep -h "^name:" ~/.claude/skills/*/SKILL.md .claude/skills/*/SKILL.md 2>/dev/null | sort | uniq -d

Jakikolwiek output oznacza kolizję. Zmień nazwę folderu i pole name tej kopii, którą kontrolujesz, zrestartuj i sprawdź listę ponownie.

Check 4: opis nigdy nie mówi, kiedy się odpalić

Objaw. Skill widnieje na liście zainstalowanych. Poproszony po nazwie działa świetnie. Poproszony o zadanie twoimi słowami — nic.

Przyczyna. To ta duża i zasługuje na własną sekcję, więc tutaj wersja skrócona: Claude decyduje, czy załadować skill, czytając wyłącznie jego pole description i porównując je z twoją prośbą. Jeśli opis mówi, czym skill jest, zamiast kiedy go użyć, dopasowanie nigdy się nie wydarzy. Skill nie jest zepsuty. Jest niereklamowany.

Fix. Przepisz opis wokół fraz, które użytkownicy naprawdę wpisują. Głębsza analiza poniżej pokazuje trzy prawdziwe wzorce porażki i ich przeróbki.

Check 5: frontmatter jest niepoprawny

Objaw. Folder poprawny, restart zrobiony, bez kolizji nazw, a skill dalej w ogóle nie pojawia się na liście. Wygląda jak check 1, ale ścieżka jest w porządku.

Przyczyna. Blok YAML na górze SKILL.md nie dał się sparsować, a skill z nieparsowalnym frontmatterem jest po prostu pomijany. Typowi winowajcy z naszych notatek testowych: brakujące zamykające ---, niecytowany dwukropek w opisie („Use for: reports" psuje parser), drukarskie cudzysłowy wklejone z posta na blogu albo z Google Doca, tabulatory użyte do wcięć i name łamiący reguły formatu (tylko małe litery, cyfry i myślniki, maks 64 znaki; opisy do 1024).

Fix. Otwórz plik i przyjrzyj się blokowi — albo pomiń oględziny: wklej go do naszego walidatora skilli, a ten natychmiast oflaguje błędy parsowania, naruszenia formatu i skażenie drukarskimi cudzysłowami. Jeśli frontmatter się parsuje, a skill nadal się chowa, wróć do checka 1, bo w tym momencie to prawie zawsze ścieżka.

Check 6: inny skill wygrywa dopasowanie

Objaw. Prosisz o zadanie i jakiś skill się aktywuje — tylko nie twój. Albo zachowanie zmienia się w sposób pasujący do instrukcji innego skilla.

Przyczyna. Gdy kilka opisów wiarygodnie pokrywa prośbę, Claude wybiera ten, który czyta się jak najlepsze dopasowanie, a szerszy, pewniejszy siebie opis zwykle bije węższy. Zainstaluj ogólny skill „asystent pisania" obok swojego „formatera release notes", a generalista potrafi połknąć każdą prośbę o pisanie, łącznie z release notes.

Fix. Zaostrz oba opisy tak, żeby ich terytoria się nie nakładały, i dodaj jawne wykluczenia. Linijka typu "Do NOT use for release notes or changelogs" w opisie generalisty jest toporna i działa. Jeśli nie kontrolujesz skilla-winowajcy, wyłącz go na czas testowania swojego, a potem zdecyduj, czy naprawdę potrzebujesz obu.

Dlaczego opisy zawodzą: głębsza analiza

Testujemy każdy skill, który listujemy, i problemy z triggerowaniem to powód numer jeden niskich ocen w naszych recenzjach. Nie zepsute skrypty, nie złe instrukcje. Opisy, które nigdy nie są dopasowywane.

Mechanika to wyjaśnia. Na starcie Claude ładuje tylko name i description każdego skilla, z grubsza sto tokenów. Ciało, choćby genialne, zostaje na dysku, dopóki opis nie wygra dopasowania z twoją prośbą. Opis to pitch sprzedażowy wygłaszany modelowi, a większość autorów pisze go jak muzealną etykietkę.

Oto trzy wzorce, za które obniżamy oceny najczęściej, z przeróbkami, które naprawiły je w naszych retestach.

Wzorzec 1: skromna etykietka.

description: Helps with documents.

Nic tutaj nie łączy się z niczym, co użytkownik by wpisał. Porównaj skill DOCX od Anthropic, który przeszedł nasze testy triggerów za pierwszym podejściem. Jego opis wymienia format pliku, akcje i sformułowania, które powinny go aktywować. Przeróbka według tej samej logiki:

description: Create, edit, and format Word documents (.docx).
  Use when the user mentions a Word doc, .docx file, memo,
  letter, or asks for a deliverable "as a document."

Wzorzec 2: nazwa wewnętrzna.

description: Runs the acme-formatter pipeline with corporate config.

To opisuje implementację. Żaden użytkownik nie prosi Claude'a o „odpalenie pipeline'u acme-formatter"; prosi o „ogarnięcie tego raportu, zanim wyślę go klientowi". Przeróbka tłumaczy skill na słownik użytkownika:

description: Reformat rough drafts into client-ready reports using
  Acme's corporate style. Use when the user wants to clean up,
  polish, or "make presentable" a document for external sharing.

Wzorzec 3: zachłanny koc.

description: Use for any writing task.

Porażka odwrotna. To pasuje do wszystkiego, czyli koliduje z każdym innym skillem okołopisarskim i odpala się, kiedy nie powinno — a użytkownicy wyłączają go w tydzień. Przeróbka zawęża roszczenie i grodzi krawędzie:

description: Write and edit marketing copy: landing pages, ads,
  and email campaigns. Do NOT use for technical docs, code
  comments, or internal memos.

Test, który stosujemy przy recenzji: przeczytaj sam opis i zapytaj: „gdyby użytkownik wpisał swoją prośbę naturalnie, czy te słowa by ją dopasowały?". Pisz w trzeciej osobie, powiedz, co skill robi i kiedy ma zastosowanie, i zawrzyj rzeczowniki, których ludzie naprawdę używają. Jeśli piszesz skill od zera, nasz przewodnik autorski omawia to głębiej, a Skill Creator od Anthropic domyślnie scaffolduje opisy, które ten test przechodzą.

Jak porządnie przetestować triggerowanie

Większość ludzi testuje skill, nazywając go: „użyj skilla do faktur na tym". To nie dowodzi niczego, bo nazwanie skilla całkowicie omija dopasowanie opisu. To jak testowanie czujnika dymu przyciskiem testowym i wniosek, że dom jest ognioodporny.

Testuj tak, jak zapytałby użytkownik, za każdym razem w świeżej sesji. Dla skilla wyciągającego dane z faktur trzy sformułowania, które powinny go odpalić:

• „Wyciągnij sumy z tych PDF-ów z fakturami."
• „Mam 30 faktur od dostawców, zbierz kwoty i daty do tabeli."
• „Wyodrębnij pozycje z tego rachunku."

I dwa, które nie powinny:

• „Streść mi tego PDF-a." (Ogólna praca na PDF-ach; terytorium innego skilla.)
• „Napisz do tego klienta maila z fakturą." (Komponowanie, nie wyciąganie.)

Jeśli sformułowanie „powinno odpalić" nie robi nic, zapytaj Claude'a wprost: „Którego z zainstalowanych skilli użyłbyś do tej prośby i dlaczego?". Odpowiedź pokazuje rozumowanie dopasowania i zwykle wskazuje prosto na słaby punkt opisu. Jeśli sformułowania „nie powinno" i tak aktywują skill, masz zachłanny koc i potrzebujesz wykluczeń. To dokładnie protokół, który przechodzimy w testach katalogowych, i ta sama dyscyplina, której uczy skill Systematic Debugging: najpierw reprodukcja, jedna zmienna naraz, wierz dowodom.

Gdy się odpala, ale nic nie robi

Załóżmy, że skill jednak się aktywuje. Możesz to potwierdzić, pytając Claude'a w trakcie rozmowy, czy dla tej prośby załadował się jakiś skill — powie ci. Ale output wygląda tak samo jak zanim cokolwiek zainstalowałeś.

To nie jest problem triggera i nic z powyższego tego nie naprawi. To problem ciała: instrukcje wewnątrz skilla są zbyt mgliste, żeby zmienić zachowanie, albo skill odwołuje się do dołączonych plików, których nie ma pod oczekiwanymi ścieżkami, albo wywołuje skrypt, którego zależności nikt nie zadeklarował. Opis wprowadził skill przez drzwi, a zawartość wywróciła się w środku.

W naszych testach to drugi duży kubeł porażek, mniej więcej lustrzane odbicie defektów triggerowania, i główny powód, dla którego około połowa społecznościowych skilli oblewa nasze testy. Szybki dyskryminator: jeśli zachowanie nie zmieniło się wcale, podejrzewaj triggerowanie; jeśli zmieniło się, ale źle albo częściowo, podejrzewaj ciało. Debuguj odpowiednio, bo fixy się nie pokrywają.

Haczyki platformowe

Format skilli jest wszędzie identyczny, ale odkrywanie nie — i skill działający w jednym miejscu może wyglądać na martwy w innym.

Claude Code czyta foldery na dysku: ~/.claude/skills/ osobiste, .claude/skills/ per projekt. Ładują się oba; kolizje nazw między zakresami rozstrzygają się do jednego zwycięzcy (check 3). Po każdej zmianie restartuj sesję.

Claude Desktop nie czyta twoich folderów skilli. Skille wgrywa się jako zip przez Settings, w sekcji Capabilities, a zip musi zawierać folder skilla na najwyższym poziomie — nie goły SKILL.md i nie katalog-opakowanie. Skill, który triggeruje się świetnie w Claude Code, będzie na Desktopie po prostu nieobecny, dopóki nie wgrasz go tam osobno.

claude.ai przyjmuje tę samą ścieżkę uploadu co Desktop, z dwoma dodatkowymi sposobami na przegraną: skille wymagają włączonej funkcji code execution na twoim planie, a administratorzy workspace'a mogą wyłączyć skille dla całej organizacji — wtedy nic, co wgrasz, nigdy się nie odpali i żaden błąd tego nie powie. Zapytaj admina, zanim spędzisz wieczór na przepisywaniu opisów.

Jeszcze jedna międzyplatformowa pułapka: ciało skilla napisane pod Claude Code, które odpala git albo czyta lokalne pliki projektu, poprawnie się striggeruje na claude.ai, a potem wywróci w sandboksie. To problem ciała w platformowym kostiumie.

Kiedy przestać debugować

Jeśli to twój własny skill, nie odpuszczaj — każdy fix powyżej jest trwały, a walidator plus test pięciu sformułowań doprowadzą cię do celu. Jeśli to skill zewnętrzny i spaliłeś już ponad dwadzieścia minut na cudzym polu description, uczciwie jest wymienić go na taki, który już przeszedł tę checklistę: każdy skill na naszych listach najlepszych zaliczył testy triggerów na czystej maszynie, zanim go dodaliśmy.

FAQ

Jak potwierdzić, że skill w ogóle jest zainstalowany?

Zapytaj Claude'a „jakie skille masz zainstalowane?" w świeżej sesji. Jeśli twojego skilla nie ma w odpowiedzi, problemem jest odkrywanie (checki 1, 3 i 5: folder, kolizja, frontmatter), a nie triggerowanie. Jeśli jest na liście, ale nigdy się nie aktywuje, problemem jest opis (checki 4 i 6).

Czy mogę po prostu wymusić trigger, nazywając skill?

Tak. „Użyj skilla docx do napisania tej notatki" ładuje skill bezpośrednio i to dobre obejście na czas debugowania. Nie jest to jednak fix: skill, który za każdym razem trzeba przywoływać po nazwie, to skill z zepsutym opisem — i zapomnisz go przywołać dokładnie wtedy, gdy będzie się to liczyło.

Dlaczego mój skill działa w Claude Code, ale nie na Desktopie ani claude.ai?

Różne ścieżki odkrywania. Claude Code czyta foldery na dysku; Desktop i claude.ai widzą tylko skille wgrane przez Settings jako zip z folderem skilla na najwyższym poziomie. Na claude.ai potwierdź też, że code execution jest włączone i że admin workspace'a nie wyłączył skilli całkowicie.

Czy instalacja zbyt wielu skilli psuje triggerowanie?

Nie bezpośrednio. Pięćdziesiąt skilli to kilka tysięcy tokenów metadanych, czyli tanio. Prawdziwe ryzyko to nakładanie się: im więcej opisów zainstalujesz, tym większa szansa, że dwa z nich roszczą sobie prawa do tego samego terytorium — i wtedy czasem wygrywa ten niewłaściwy (check 6). Instaluj wedle potrzeby i wycinaj skille, które nigdy się nie odpalają.

Mój skill odpalił się wczoraj, a dziś nie. Czy to normalne?

Zdarza się. Dopasowaniem steruje model, nie regex, więc opis na granicy odpali się na jednym sformułowaniu i przegapi niemal identyczne. Jeśli skill jest kapryśny, a nie martwy, potraktuj to jak słaby opis: dodaj do pola description dokładne frazy, które się nie załapały, zrestartuj i przetestuj ponownie. Niezawodne skille odpalają się na każdym rozsądnym sformułowaniu — dlatego my testujemy pięcioma, nie jednym.