Claude Code skills: jak napisać SKILL.md i kiedy wystarczy CLAUDE.md

👁 118 przeczytań

Skill w Claude Code to folder z plikiem SKILL.md: na górze opis, kiedy agent ma go użyć, niżej instrukcje krok po kroku. Wywołujesz go komendą /nazwa albo Claude sam go wybiera, gdy Twoje polecenie pasuje do opisu. Poniżej opisuję, jak napisać pierwszy skill, które pola frontmattera mają znaczenie, kiedy zamiast skilla wystarczy CLAUDE.md albo hook i jak wyglądają moje własne skille. Całe narzędzie opisuję w hubie Claude Code.

Skill, CLAUDE.md czy hook: co do czego

Te trzy mechanizmy łatwo pomylić, a każdy rozwiązuje inny problem:

Dokumentacja Anthropic daje prostą regułę: jeśli w CLAUDE.md zamiast faktu pojawia się procedura z kilkoma krokami albo coś, co dotyczy tylko części projektu, przenieś to do skilla. A jeśli coś musi się wydarzyć niezależnie od tego, co postanowi model, to robota dla hooka, bo CLAUDE.md i skille są tylko kontekstem.

Pierwszy skill w 5 minut

Przykład z dokumentacji, który streszcza niezatwierdzone zmiany w Git i wskazuje ryzyka. Najpierw folder:

mkdir -p ~/.claude/skills/summarize-changes

Potem plik ~/.claude/skills/summarize-changes/SKILL.md:

---
description: Streszcza niezatwierdzone zmiany i wskazuje
  ryzyka. Użyj, gdy pytam, co się zmieniło, albo
  proszę o opis commita.
---
## Aktualne zmiany
!`git diff HEAD`

## Instrukcje
Streść zmiany w 2-3 punktach, potem wypisz ryzyka:
brak obsługi błędów, wpisane na sztywno wartości,
testy do aktualizacji. Pusty diff: napisz, że nie ma zmian.

Linia !`git diff HEAD` to wstrzyknięcie kontekstu: Claude Code uruchamia polecenie i podstawia jego wynik, zanim model przeczyta skill. Agent dostaje aktualny diff, a nie zgaduje go z otwartych plików.

Test: w dowolnym repozytorium zmień plik, uruchom claude i zapytaj „co zmieniłem?” albo wpisz /summarize-changes.

Pola frontmattera, które naprawdę się przydają

• description - najważniejsze pole. Na jego podstawie agent decyduje, czy użyć skilla. Opis razem z polem when_to_use ma limit 1536 znaków, więc najważniejszy przypadek użycia daj na początek.
• name - nazwa komendy w menu /. Domyślnie nazwa folderu.
• disable-model-invocation: true - agent nie uruchomi skilla sam, tylko Ty komendą. Dobre dla wdrożeń i wszystkiego, co zmienia stan na zewnątrz.
• allowed-tools - narzędzia, których agent może użyć bez pytania w turze, w której działa skill.
• model i effort - inny model albo poziom rozumowania na czas działania skilla.
• context: fork - skill działa w osobnym subagencie, więc jego robota nie zapycha głównej rozmowy.
• paths - wzorce plików, przy których skill ma się włączać automatycznie, np. tylko przy plikach w src/api/.
• argument-hint i $ARGUMENTS - argumenty z linii komend: /deploy staging podstawi „staging” w miejsce $ARGUMENTS albo $0.

W folderze skilla mogą leżeć też pliki pomocnicze: szablony, skrypty, przykłady. Odwołujesz się do nich przez ${CLAUDE_SKILL_DIR}, a agent czyta je dopiero wtedy, gdy są potrzebne.

Gdzie zapisać skill

• ~/.claude/skills/ - Twoje skille we wszystkich projektach na tym komputerze.
• .claude/skills/ w repozytorium - dla wszystkich, którzy pracują w projekcie. Commitujesz razem z kodem.
• Podkatalog projektu, np. apps/web/.claude/skills/ - ładuje się, gdy agent zacznie pracować na plikach w tym katalogu.
• Wtyczka (plugin) - skille dzielone między projektami i zespołami, wywoływane jako /wtyczka:skill.

Claude Code ma też wbudowane skille, m.in. /doctor (przegląd konfiguracji z propozycjami poprawek), /code-review, /debug, /loop i parę /run oraz /verify, które uruchamiają aplikację i sprawdzają zmianę na działającym programie zamiast tylko na testach.

Moje skille i czego mnie nauczyły

Mam kilka własnych skilli osobistych. Najkrótszy, do teledysków AI, ma 24 linie: kolejność etapów, sprawdzone ustawienia i listę rzeczy, które w moich testach nie działały. Zamiast tłumaczyć agentowi proces przy każdym nowym klipie, piszę „zrób teledysk do tego utworu” i skill ustawia całą resztę.

Ważniejsza lekcja dotyczy opisu. Drugi skill, do animacji renderowanych kodem, ma w description wprost: „TYLKO gdy wprost proszę o animację renderowaną kodem. NIE używać do teledysków”. Oba skille dotyczą wideo, a nie chcę, żeby agent sięgał po animację z kodu, gdy proszę o teledysk. Opis działa jak instrukcja wyboru, więc warto w nim pisać także, kiedy skilla nie używać.

Trzecia rzecz: w skillu zapisuję datę ostatniego sprawdzenia, np. „stan 23.10.2026”. Narzędzia AI zmieniają się co kilka tygodni i skill bez daty po miesiącu prowadzi agenta starą ścieżką.

Gdy skill nie działa

• Agent go nie uruchamia - opis jest zbyt ogólny. Dopisz frazy, jakimi naprawdę o to prosisz („gdy proszę o wdrożenie”, „gdy pytam o koszty”).
• Uruchamia się za często - zawęź opis, dodaj wykluczenia albo ustaw disable-model-invocation: true i wywołuj ręcznie.
• Nie widać go w menu - sprawdź ścieżkę: osobny folder, a w nim plik o nazwie dokładnie SKILL.md. Skille z podkatalogów projektu pojawiają się dopiero, gdy agent zacznie pracować na plikach w tym katalogu.
• Zjada limit - /usage pokazuje, ile zużycia przypada na skille, subagentów i serwery MCP. Jak liczą się limity planów, opisuję w tekście Claude Code cena.

Hook w dwóch zdaniach, bo pytacie razem ze skillami

Hook to polecenie powłoki, które Claude Code uruchamia w określonym momencie, np. PostToolUse po każdej edycji pliku albo PreToolUse przed poleceniem, które można zablokować. Konfigurujesz go w settings.json w bloku "hooks", a listę aktywnych hooków pokazuje komenda /hooks. Przykład z formatowaniem po każdej edycji jest w hubie, a gdy potrzebujesz własnego narzędzia zamiast instrukcji, zobacz własny serwer MCP w 15 minut.

Najczęstsze pytania

Co to są skille w Claude Code?

Pliki SKILL.md z opisem i instrukcjami, które agent ładuje wtedy, gdy są potrzebne. Wywołujesz je komendą /nazwa albo agent wybiera je sam po opisie.

Czym skill różni się od CLAUDE.md?

CLAUDE.md ładuje się na starcie każdej sesji i powinien zawierać krótkie fakty o projekcie. Skill ładuje się tylko przy użyciu, więc mieści długie procedury bez kosztu w każdej rozmowie.

Gdzie trzymać skille?

Osobiste w ~/.claude/skills/nazwa/SKILL.md, projektowe w .claude/skills/nazwa/SKILL.md w repozytorium, żeby dostał je cały zespół.

Czy skille z Claude Code działają w innych narzędziach?

Format opiera się na otwartym standardzie Agent Skills (agentskills.io), więc podstawowy SKILL.md da się użyć także w innych narzędziach zgodnych ze standardem. Pola specyficzne dla Claude Code, np. context: fork, poza nim nie zadziałają.

Co się stało z własnymi komendami w .claude/commands?

Działają dalej i tworzą komendy tak samo jak skille. Anthropic połączył oba mechanizmy, a skille dodają folder na pliki pomocnicze i kontrolę, kto je wywołuje.

Źródła i data sprawdzenia

• Claude Code Docs: skille - lokalizacje, frontmatter, wbudowane skille, rozwiązywanie problemów (odczyt 25.10.2026)
• Claude Code Docs: CLAUDE.md i pamięć (odczyt 25.10.2026)
• Claude Code Docs: hooki (odczyt 25.10.2026)
• Claude Code Docs: koszty i /usage (odczyt 25.10.2026)
• Agent Skills - otwarty standard skilli (odczyt 25.10.2026)