Umiejętności Claude i plik SKILL.md dla developerów: VS Code, JetBrains, Cursor

Większość zespołów nadużywa Claude Skills na jeden z dwóch sposobów. Albo zamieniają plik SKILL.md w kosz na wszystko, albo nigdy nie odchodzi od ogromnych, skopiowanych promptów.

Oba podejścia są niedbałe. Jeśli chcesz, aby Skills działały w prawdziwym środowisku deweloperskim, musisz traktować je jak kod i logikę operacyjną, a nie jak poetyckie prompty.

Claude Skills to katalogi zakotwiczone przez plik SKILL.md, z opcjonalnymi skryptami, odniesieniami i zasobami. Działają dzięki stopniowemu ujawnianiu (progressive disclosure). Agent zaczyna od załadowania tylko zwartej metadanych, takich jak nazwa i opis umiejętności, a pełne instrukcje odczytuje dopiero, gdy zadanie pasuje. Dzięki temu agent może mieć wiele dostępnych umiejętności, nie obciążając każdej sesji od samego początku.

Własne wskazówki Anthropic jasno określają intended podział pracy. CLAUDE.md służy do trwałego, zawsze aktywnego kontekstu projektu. Skills są przeznaczone do powtarzalnej wiedzy, playbooków i wywoławalnych workflow, które powinny być ładowane na żądanie. Claude Code nawet włączył stare polecenia niestandardowe do tego samego mechanizmu, więc legacy pliki .claude/commands/*.md nadal działają, ale Skills są teraz lepszym długoterminowym kształtem — i najbardziej powtarzalnym blokiem budulcowym w dowolnym workflow deweloperskim zasilany AI.

Kiedy używać Claude Skills: CLAUDE.md vs Skills vs Hooks

Warto stworzyć Claude Skill, gdy ciągle wklejasz tę samą listę kontrolną, ten sam playbook wdrożeniowy, tę samą rubrykę code review lub te same pułapki wewnętrzne API do czatu. Anthropic zaleca tworzenie umiejętności, gdy ciągle ponownie używasz tej samej procedury, lub gdy sekcja CLAUDE.md rozrosła się w proces, a nie w fakt. To praktyczna odpowiedź na pytanie FAQ “Czym jest Claude Skill i kiedy należy go użyć”. Używaj Skillu dla powtarzalnych procedur, a nie dla ogólnych gustów czy szerokich reguł repo.

Prawdziwa wygrana to kontrola nad kosztem kontekstu i zachowaniem. Dobry Skill jest ładowany tylko wtedy, gdy jest potrzebny, podczas gdy rozrośnięty CLAUDE.md jest ładowany w każdej sesji. Anthropic zaleca utrzymywanie CLAUDE.md krótkiego i przenoszenie wiedzy dziedzinowej lub procedur do Skills właśnie dlatego, że ładowanie na żądanie utrzymuje agenta skupionego na zadaniu przed nim.

Moja zdaniowa zasada jest prosta. Jeśli instrukcja powinna obowiązywać w każdej sesji, należy umieścić ją w CLAUDE.md. Jeśli instrukcja jest powtarzalną metodą, listą kontrolną lub workflow, który ma znaczenie tylko czasami, należy umieścić go w Skillu. Jeśli akcja musi nastąpić automatycznie przy każdym pasującym zdarzeniu, prawdopodobnie należy ją umieścić w hooku, a nie w Skillu. Przegląd funkcji Anthropic układa te narzędzia w model warstwowy prawie dokładnie w ten sposób.

Praktyczny dowód dla każdego: jeśli znajdziesz się w sytuacji wklejania tych samych instrukcji do każdego czatu, to jest Skill. Jeśli sekcja CLAUDE.md rozrosła się w proces krok-po-kroku, wydobyj go do Skillu. Jeśli chcesz, aby coś wywoływało się cicho za każdym razem, gdy plik jest zapisywany, napisz hook.

Obsługa Claude Skills w IDE: VS Code, JetBrains, Cursor i Codex

Claude Code działa na CLI, Desktopie, VS Code, JetBrains, w przeglądarce oraz w przepływach zdalnej kontroli związanych z mobilnością. Anthropic opisuje CLI jako najbardziej kompletną powierzchnię lokalną, podczas gdy integracje IDE rezygnują z niektórych możliwości dostępnych tylko w CLI na rzecz natywnego przeglądu edytora, kontekstu plików i lepszej ergonomii workflow. Konfiguracja, pamięć projektu i serwery MCP są współdzielone między powierzchniami lokalnymi, więc twoja konfiguracja .claude podąża za Tobą, a nie jest uwięziona w jednym edytorze.

Dla VS Code, Anthropic mówi, że rozszerzenie jest zalecanym interfejsem wewnątrz edytora. Zapewnia przegląd planu, inline diffy, wsparcie dla wzmianek o plikach i zintegrowany dostęp do CLI. Ten sam przepływ instalacji odsłania również bezpośrednią ścieżkę dla Cursora. Dla JetBrains, obecna lista obsługiwanych edytorów obejmuje IntelliJ IDEA, PyCharm, Android Studio, WebStorm, PhpStorm i GoLand, z wbudowaną w wtyczkę obsługą przeglądania diffów, udostępniania wyboru, skrótów do odniesień do plików i udostępniania diagnostyki.

Obsługa JetBrains jest lepsza niż wielu deweloperów zdaje sobie sprawę. Jeśli uruchamiasz claude z zintegrowanego terminala IDE, funkcje integracji są aktywne automatycznie. Jeśli zaczynasz z zewnętrznego terminala, dokumentacja Anthropic opisuje polecenie /ide do połączenia Claude Code z sesją JetBrains i wyraźnie zaleca uruchamianie z tego samego rootu projektu, aby Claude widział te same pliki, co IDE. Jeśli używasz trybów automatycznego edytowania w JetBrains, Anthropic ostrzega również, że pliki konfiguracyjne IDE mogą stać się częścią powierzchni edytowalnej, więc ręczne zatwierdzenia są bezpieczniejszym domyślnym ustawieniem w tym środowisku.

Teraz większa kwestia. Claude Skills to nie tylko rzecz Claude Code. Agent Skills to otwarty standard. Oficjalny przewodnik szybkiego startu Agent Skills mówi, że ta sama umiejętność może działać w VS Code z GitHub Copilot, Claude Code i OpenAI Codex, a własne dokumenty Codex OpenAI mówią, że Skills są dostępne w CLI Codex, rozszerzeniu IDE i aplikacji. Przewodnik wdrożenia Agent Skills dodaje ważny szczegół przenośności: .agents/skills stało się konwencją międzyklientową, podczas gdy niektórzy klienci skanują również .claude/skills ze względów praktycznej kompatybilności.

Oto więc praktyczna zasada kompatybilności, którą rekomenduję. Jeśli budujesz tylko dla Claude Code, autoruj w .claude/skills. Jeśli naprawdę chcesz przenośności między klientami, celuj w otwarty kształt Agent Skills i użyj .agents/skills jako ścieżki kanonicznej. Nie udawaj, że te dwa cele są identyczne. Są powiązane, ale nie identyczne.

Szybkie odniesienie kompatybilności:

Struktura pliku SKILL.md, układ folderów i lokalizacje przechowywania

Właściwy Skill to folder, a nie losowy plik markdown leżący u podstawy repo. Podstawowa specyfikacja wymaga katalogu z plikiem SKILL.md i pozwala na opcjonalne katalogi scripts/, references/ i assets/. SKILL.md musi zawierać frontmatter YAML, a następnie instrukcje w markdownie. W specyfikacji name i description są wymagane, name jest ograniczony do 64 znaków używając liter małych, cyfr i myślników, compatibility służy tylko do rzeczywistych wymagań środowiskowych, a allowed-tools jest eksperymentalne w implementacjach.

Claude Code jest nieco luźniejszy niż przenośna specyfikacja, ponieważ może wywnioskować nazwę z katalogu i powrócić do pierwszego akapitu, gdy description brakuje. Nie powinieneś polegać na tym, jeśli zależy Ci na przenośności lub przewidywalności. Claude.ai wymaga, aby nazwa katalogu pasowała do pola name, a jego ścieżka uploadu niestandardowego Skillu ogranicza opisy do 200 znaków, mimo że szersza specyfikacja pozwala na znacznie więcej. Przenośny wybór to ustawienie jawnego name, utrzymanie identycznego katalogu i napisanie precyzyjnego opisu, który mieści się w ciasnych limitach. To odpowiada na temat FAQ “Co powinien zawierać plik SKILL.md” bez owijania w bawełnę.

Zacznij od struktury tak nudnej:

repo/
  .claude/
    skills/
      review-pr/
        SKILL.md
        scripts/
          review.sh
        references/
          checklist.md
        assets/
          comment-template.md

Jeśli przenośność między klientami obsługującymi Skills jest ważniejsza niż wygoda Claude Code, zachowaj ten sam wewnętrzny kształt i zamień .claude/skills/ na .agents/skills/. Struktura folderów jest w obu przypadkach tym samym pomysłem.

Dla Claude Code lokalizacje przechowywania są proste. Umiejętności projektu żyją w .claude/skills/<skill-name>/SKILL.md. Umiejętności osobiste żyją w ~/.claude/skills/<skill-name>/SKILL.md. Umiejętności dystrybuowane przez wtyczki żyją pod <plugin>/skills/<skill-name>/SKILL.md. Anthropic dokumentuje priorytety między wbudowanymi zakresami jako przedsiębiorstwo nad osobistym nad projektem, podczas gdy umiejętności wtyczek unikają kolizji, używając formy z nazwą przestrzeni, takiej jak plugin-name:skill-name. Na Windowsie ~/.claude rozwija się do %USERPROFILE%\.claude, a CLAUDE_CONFIG_DIR może przenieść cały katalog bazowy.

Wybór między zakresem projektu a osobistym jest prosty. Używaj .claude/skills/ wewnątrz repo, gdy Skill jest ściśle powiązany z tą bazą kodu — na przykład playbook wdrożeniowy, który zna Twoje konkretne nazwy klastrów, lub rubryka review dostosowana do konwencji Twojego zespołu. Używaj ~/.claude/skills/ dla Skills, które podróżują z Tobą między projektami: osobiste listy kontrolne, ogólne generatory changelogów, preferowane workflow debugowania. Wszystko, co umieściłbyś w repo dotfiles, należy do zakresu osobistego.

Kilka ostrych krawędzi warto zapamiętać. SKILL.md musi być nazwany dokładnie z tą wielkością liter. Przewodnik PDF Anthropic zaleca nazwy folderów w stylu kebab-case i wyraźnie mówi, aby nie umieszczać README.md wewnątrz folderu skillu, ponieważ operacyjna dokumentacja powinna żyć w SKILL.md lub references/. Ten sam przewodnik podkreśla również, że nazewnictwo SKILL.md jest czułe na wielkość liter. To są nudne ograniczenia, ale nudne ograniczenia sprawiają, że narzędzia są niezawodne.

Claude Code robi też właściwą rzecz dla monorepo. Automatycznie odkrywa zagnieżdżone katalogi .claude/skills/, gdy pracujesz w podkatalogach, co jest idealne dla umiejętności na poziomie pakietu lub usługi. Obserwuje również istniejące katalogi skillów pod kątem zmian na żywo podczas bieżącej sesji. Jedna pułapka restartu to stworzenie katalogu skillów najwyższego poziomu, który nie istniał, gdy sesja się rozpoczęła. Anthropic dokumentuje to jako przypadek, w którym faktycznie musisz zrestartować, aby nowy katalog mógł być obserwowany.

Najlepsze praktyki Claude Skills: opisy, skrypty i zakres

Najszybszym sposobem na stworzenie bezużytecznego Skillu jest poproszenie LLM o wymyślenie go z ogólnej wiedzy szkoleniowej. Przewodnik najlepszych praktyk Anthropic ostrzega właśnie przed tym. Wartościowe elementy to specyficzne dla dziedziny korekty, przypadki brzegowe, wybory narzędzi i konwencje, których model nie byliby w stanie wiarygodnie wymyślić samodzielnie. Prawidłowy workflow polega na rozwiązaniu zadania raz z agentem, skorygowaniu go, aż zadziała, a następnie wydobyciu metody do Skillu.

Zakresz Skill jak dobrą funkcję, a nie jak wiki. Anthropic mówi, że Skills powinny enkapsułować spójną jednostkę pracy. Zbyt wąski, i zmuszasz do nakładania wielu skillów dla jednego zadania. Zbyt szeroki, i agent nie może ich aktywować precyzyjnie. Przewodnik najlepszych praktyk jest bezwzględny, że nadmiernie kompletne skilli mogą szkodzić bardziej niż pomagać, ponieważ model goni nieistotne instrukcje i traci sygnał.

Jakość opisu to nie kwestia kosmetyczna. To warstwa routingu. Zarówno Anthropic, jak i dokumenty Agent Skills mówią, że pole description jest głównym mechanizmem, którego model używa do decyzji, czy w ogóle załadować Skill. Dobre opisy mówią, co Skill robi, kiedy go użyć i frazy wyzwalające lub typy plików, które użytkownik faktycznie wspomni. Złe opisy są niejasne, zbyt techniczne lub szerokie, aby pasować do nonsensu. To jest prawdziwa odpowiedź na pytanie FAQ “Dlaczego Claude Skill nie wywołuje się”. Zazwyczaj router jest zły, a nie model.

Kontrast jest jasny obok siebie:

Złe opisy — zbyt niejasne do wiarygodnego routingu:

• Pomaga w code review — pasuje do wszystkiego, nic nie rozróżnia
• Użyteczne dla zadań deweloperskich — szersze niż zapytanie wyszukiwania
• Asystuje przy pisaniu — nie router, tylko etykietka kategorii

Dobre opisy — specyficzny język wyzwalania:

• Przeglądaj pull requests pod kątem problemów z bezpieczeństwem, ryzykiem migracji i brakujących testów. Użyj przy przeglądaniu PR, git diff lub krytycznej zmianie wydania.
• Generuj changelog z wyjścia git log. Użyj przy przygotowywaniu wydania, pisaniu notatek o wydaniu lub podsumowywaniu commitów od ostatniego tagu.
• Stwórz szkielet nowego HTTP handlera Go z walidacją żądań i middleware błędów. Użyj przy dodawaniu nowego endpointu lub trasy do usługi Go.

Wzór jest tym samym za każdym razem: podaj, co robi Skill, nazwij dokładne frazy użytkownika, które powinny go aktywować, i opcjonalnie nazwij typy plików lub narzędzia, które są istotne. Jeśli Twój opis pasowałby do ogólnego zapytania Google, nie jest wystarczająco specyficzny.

Jeśli workflow ma skutki uboczne, zrób to manualnie. Claude Code to odsłania bezpośrednio. disable-model-invocation: true sprawia, że Skill jest wywołany tylko przez użytkownika, co Anthropic zaleca dla akcji takich jak wdrożenia, commity lub wiadomości wychodzące. user-invocable: false idzie w drugą stronę i ukrywa Skill z menu slashowego, jednocześnie pozwalając Claude używać go jako wiedzy tła. To odpowiada na temat FAQ “Kiedy skill powinien być manualny zamiast automatyczny” w jednym zdaniu: manualny dla ryzyka, automatyczny dla bezpiecznych powtarzalnych wskazówek.

Utrzymuj SKILL.md wystarczająco mały, aby pozostał zrozumiały. Anthropic zaleca utrzymanie go poniżej 500 linii i około 5000 tokenów, a następnie przenoszenie szczegółowego materiału do references/ lub podobnych plików z jawnymi instrukcjami ładowania. “Czytaj references/api-errors.md, jeśli API zwraca nie-200” to dobry wzór. “Zobacz references/” to leniwe. Claude Code wstrzykuje również renderowany Skill do rozmowy jako wiadomość i nie czyta ponownie pliku w kolejnych turach. Po kompresji kontekstu tylko niedawna zawartość Skillu jest przenoszona dalej w ramach budżetu tokenów. Ogromne Skilli są więc nie tylko brzydkie. Są kruche w długich sesjach.

Dobry SKILL.md może pozostać bardzo prosty:

---
name: review-pr
description: Przeglądaj pull requests pod kątem problemów z bezpieczeństwem, ryzykiem migracji i brakujących testów. Użyj przy przeglądaniu PR, git diff lub krytycznej zmianie wydania.
compatibility: Zaprojektowano dla Claude Code. Wymaga git i gh.
disable-model-invocation: true
allowed-tools: Bash(git diff *) Bash(gh pr diff *) Read Grep Glob
---
# Przegląd PR

Przeczytaj references/checklist.md przed uruchomieniem jakichkolwiek poleceń.

1. Zbierz diff i zmienione pliki.
2. Zaznacz problemy z poprawnością, bezpieczeństwem i pokryciem testów.
3. Zwróć wyniki pogrupowane według powagi z odniesieniami do plików.
4. Zaproponuj najpierw najbezpieczniejszą naprawę.

Używaj skryptów, gdy determinizm jest ważniejszy niż elokwencja. Przewodnik skryptów Skills jest tu doskonały. Mówi, że skrypty skierowane do agenta muszą unikać promptów interaktywnych, dokumentować użycie przez --help, emitować pomocne komunikaty błędów, preferować strukturalne wyjście, takie jak JSON lub CSV na stdout, wysyłać diagnostykę na stderr i obsługiwać użycie odporne na ponowne próby. Zaleca również pinowanie wersji narzędzi jednorazowych i jawne opisywanie wymagań środowiska w SKILL.md lub polu compatibility, zamiast zakładać, że środowisko ma odpowiednie pakiety.

Minimalny, ale poprawny skrypt skierowany do agenta wygląda tak:

#!/usr/bin/env bash
# scripts/collect-diff.sh — wywoływany przez skill review-pr
# Użycie: collect-diff.sh <base-ref> [<head-ref>]
set -euo pipefail

BASE="${1:?Usage: collect-diff.sh <base-ref> [<head-ref>]}"
HEAD="${2:-HEAD}"

# Strukturalne wyjście na stdout, aby agent mógł je parsować
git diff "${BASE}...${HEAD}" --stat --name-only \
  | jq -Rs '{
      "changed_files": split("\n") | map(select(length > 0))
    }' \
  || { printf '{"error":"git diff failed"}\n' >&2; exit 1; }

Trzy rzeczy sprawiają, że jest to bezpieczne dla agenta. set -euo pipefail zapewnia, że skrypt kończy się głośno przy każdej awarii, zamiast cicho kontynuować. JSON na stdout daje agentowi format, który może parsować bez zgadywania. Diagnostyka idzie na stderr, aby strumień stdout agenta pozostał czysty. Nic z tego nie jest sprytne. Wszystko jest konieczne.

Jedna subtelną pułapką jest allowed-tools. W specyfikacji jest eksperymentalne i wsparcie się różni. W Claude Code zatwierdza z góry konkretne narzędzia, gdy Skill jest aktywny, ale nie ogranicza uniwersum wywoławalnych narzędzi, a reguły odmowy nadal należą do uprawnień Claude Code. W SDK Claude Agent, Anthropic wyraźnie mówi, że frontmatter allowed-tools w SKILL.md nie ma zastosowania, więc aplikacje SDK muszą wymuszać dostęp do narzędzi w głównej konfiguracji allowed_tools lub allowedTools. Jeśli zignorujesz tę różnicę, Twój Skill będzie zachowywał się inaczej w CLI i w automatyzacji zasilanej przez SDK.

Jedna kolejna zaawansowana zasługa jest warta skradnięcia. Gdy workflow zalałby Twój główny wątek logami, wyszukiwaniem plików lub długim wynikiem badawczym, Claude Code pozwala Skillowi działać w odgałęzionym podagencie używając context: fork i agenta takiego jak Explore. Anthropic pokazuje to dla workflow badawczych, gdzie ciężka praca dzieje się w izolowanym kontekście, a główna rozmowa otrzymuje podsumowanie. Dla głębokiej eksploracji bazy kodu, to jest znacznie lepszy projekt niż ogromny inline Skill, który zanieczyszcza główną sesję.

Odgałęziony Skill wygląda tak w frontmatter:

---
name: explore-codebase
description: Głęboka eksploracja nieznanej bazy kodu. Użyj przy onboardingu do nowego repo, audytowaniu architektury lub mapowaniu zależności modułów.
context: fork
agent: Explore
compatibility: Wymaga Claude Code CLI.
---
# Eksploracja bazy kodu

1. Przejrzyj drzewo katalogów i podsumuj moduły najwyższego poziomu.
2. Zidentyfikuj główne punkty wejścia i ich odpowiedzialności.
3. Zmapuj graf zależności między pakietami.
4. Zwróć strukturalne podsumowanie do głównej sesji — nie surową listę plików.

Kluczowa linia to context: fork. Bez niej, wynik eksploracji lądowałby inline w Twojej rozmowie. Z nią, podagent działa we własnym oknie kontekstowym i oddaje podsumowanie. Różnica ma znaczenie w dużych repo, gdzie sama eksploracja może zużyć tysiące tokenów.

Testowanie Claude Skills: wyzwalacze, poprawność i porównania bazowe

Skill nie jest testowany, bo jeden happy-path demo zadziałał raz. Przewodnik Anthropic dzieli testowanie na trzy warstwy: testowanie ręczne w Claude.ai, testowanie skryptowe w Claude Code i testowanie programowe przez API Skills. Zalecane obszary oceny to wyzwalanie, poprawność funkcjonalna i wydajność w porównaniu z bazą bez Skillu. To również najlepsza odpowiedź na pytanie FAQ “Jak testujesz, czy skill jest niezawodny”. Testujesz wybór trasy, jakość wyjścia i wydajność, a nie tylko to, czy model brzmiał pewnie.

Oficjalne wskazówki dotyczące ewaluacji dają czystą strukturę dla przypadków testowych. Każdy przypadek powinien zawierać realistyczny prompt użytkownika, czytelny dla człowieka opis oczekiwanego wyjścia i opcjonalne pliki wejściowe. Dokumenty przechowują je w evals/evals.json wewnątrz katalogu Skillu, co jest sensowną konwencją, nawet jeśli stworzysz własne harnis.

Użyj pliku fixture i układu eval bez zbędnych ozdobników:

{
  "skill_name": "review-pr",
  "evals": [
    {
      "id": 1,
      "prompt": "Przeanalizuj ten PR pod kątem problemów z bezpieczeństwem i brakujących testów",
      "expected_output": "Wyniki pogrupowane według powagi z odniesieniami do plików i co najmniej jedną rekomendacją testu.",
      "files": ["evals/files/pr-diff.patch"]
    },
    {
      "id": 2,
      "prompt": "Podsumuj commity z ostatniego tygodnia",
      "expected_output": "Skill nie powinien się aktywować.",
      "files": []
    }
  ]
}

Moja własna zasada testowa jest bardziej surowa niż większość zespołów używa, ale zgadza się z oficjalnymi wskazówkami. Każdy poważny Skill powinien mieć zapytania, które powinny się wywołać, zapytania, które nie powinny się wywołać, co najmniej jeden test przypadku brzegowego i porównanie bazowe bez Skillu. Przykłady Anthropic porównują wywołania narzędzi, nieudane wywołania API, pętle wyjaśnień i zużycie tokenów z i bez Skillu, ponieważ “działa” nie to samo co “ulepsza workflow”.

Jeśli testujesz przez Claude Agent SDK, pamiętaj o instalacji. Skilli to artefakt plików, a nie rejestracje programowe. Anthropic mówi, że musisz włączyć narzędzie "Skill" i załadować odpowiednie ustawienia plików przez settingSources lub setting_sources. Jeśli pomijasz user lub project, lub wskazujesz cwd w złym miejscu, SDK nie odkryje Skillu. Anthropic nawet zaleca zadanie pytania “Jakie skilli są dostępne?” jako bezpośredniej kontroli odkrycia.

Testuj też na modelu i kliencie, który faktycznie zamierzasz wdrożyć. Otwarty przewodnik szybkiego startu Agent Skills wyraźnie ostrzega, że niezawodność używania narzędzi różni się między modelami, a niektóre modele mogą odpowiadać bezpośrednio zamiast wykonywać polecenie, które Skill zamierza. To nie zawsze jest problem projektowania Skillu. Czasami jest to problem wyboru modelu, i Twoja macierz testowa powinna to ujawnić.

Rozwiązywanie problemów z Claude Skills: częste awarie i naprawy

Gdy Skill zachowuje się niepoprawnie, zakładaj pakowanie przed inteligencją. Najczęstsze awarie to wciąż nudne.

• Jeśli Skill nie jest w ogóle znaleziony, zweryfikuj, czy plik jest nazwany dokładnie SKILL.md, z poprawną wielkością liter, wewnątrz poprawnego katalogu. Przewodnik rozwiązywania problemów Anthropic wskazuje wielkość liter nazwy pliku jawnie, a jego dokumenty Claude Code i SDK skierują Cię bezpośrednio do .claude/skills/*/SKILL.md i ~/.claude/skills/*/SKILL.md jako pierwszych kontrolek.
• Jeśli frontmatter jest nieprawidłowy, sprawdź najpierw delimitery YAML i cudzysłowy. Przykłady Anthropic pokazują klasyczne błędy: brakujące ---, niezamknięte cudzysłowy lub nieprawidłowe nazwy ze spacjami i wielkimi literami. Nazwy skillów powinny być małymi literami i myślnikami.
• Jeśli Skill istnieje, ale się nie wywołuje, opis jest zazwyczaj zbyt niejasny. Własne rozwiązywanie problemów Claude Code mówi, aby uwzględnić słowa kluczowe, które użytkownicy naturalnie by powiedzieli, zweryfikować, czy Skill pojawia się, gdy pytasz “Jakie skilli są dostępne?”, i spróbować sformułować frazy bliższe opisowi. Przewodnik PDF Anthropic dodaje świetny trik diagnostyczny: zapytaj Claude, kiedy użyłby Skillu i posłuchaj, jak on parafrazuje opis z powrotem do Ciebie.
• Jeśli Skill wywołuje się zbyt często, zawęź zakres. Anthropic zaleca czynienie opisu bardziej specyficznym, dodawanie negatywnych wyzwalaczy i używanie disable-model-invocation: true dla workflow, które chcesz tylko przez jawną komendę. Nadmierne wywoływanie to zazwyczaj niedostatecznie zdefiniowany język routingu.
• Jeśli Skill wydaje się tracić wpływ w długich sesjach, pamiętaj, że opisy mogą być skracane w katalogu Claude Code, gdy jest wiele skillów, a wywołane Skilli są później przenoszone w ramach budżetu tokenów po kompresji. Anthropic zaleca front-loading słów kluczowych w opisie, przycinanie nadmiernego tekstu i, konkretnie dla Claude Code, dostosowanie SLASH_COMMAND_TOOL_CHAR_BUDGET, jeśli listy opisów są zbyt agresywnie ściskane.
• Jeśli zszyty skrypt zaciąga się lub zachowuje się błędnie, sprawdź, czy oczekuje on wejścia interaktywnego. Przewodnik skryptów mówi, że agenty działają w powłokach nieinteraktywnych, więc prompty TTY, dialogi haseł i menu potwierdzeń to błędy projektowe. Akceptuj wejście przez flagi, zmienne środowiskowe lub stdin i uczyniaj awarie jawnymi.
• Jeśli SDK nie widzi Twojego Skillu, potwierdź, że allowed_tools zawiera "Skill", że settingSources lub setting_sources zawiera user i/lub project, i że cwd wskazuje na katalog, który faktycznie zawiera .claude/skills/. Bez tego ustawienia system Skillu nie jest włączony, niezależnie od tego, jak poprawnie wygląda Twój markdown.
• Jeśli Skill oparty na MCP ładuje się, ale wywołania narzędzi zawodzą, lista kontrolna rozwiązywania problemów Anthropic jest sensowna: zweryfikuj, czy serwer MCP jest podłączony, potwierdź uwierzytelnienie i zakresy, przetestuj narzędzie MCP bezpośrednio bez Skillu, a następnie sprawdź dokładne nazwy narzędzi, ponieważ są one czułe na wielkość liter.

Nudna prawda jest taka, że dobre Claude Skills wyglądają jak dobre inżynieria operacyjna. Jasne nazwy. Małe pliki. Jawne wyzwalacze. Deterministyczne skrypty tam, gdzie to konieczne. Prawdziwe testy. Jeśli Twój Skill czyta się jak zwięzły runbook, agent ma szansę walki. Jeśli czyta się jak burza mózgów, po prostu ukryłeś chaos w folderze.