Claude Code Skills po polsku, tutorial Agent Skills 2026

Spis treści

• Czym są Agent Skills
• Jak Claude odkrywa i odpala skille
• Struktura katalogu i SKILL.md
• Frontmatter, pola po kolei
• Twój pierwszy skill krok po kroku
• Pliki pomocnicze i progressive disclosure
• Kto może odpalić skill
• Skills vs subagents vs MCP
• 5 praktycznych skilli
• Antywzorce
• Co dalej
• FAQ

Aktualizacja: maj 2026. Agent Skills to najprostszy sposób, żeby nauczyć Claude Code powtarzalnej procedury raz, zamiast wklejać tę samą instrukcję do czatu co rozmowę. Skill to katalog z plikiem SKILL.md, który Claude ładuje dopiero gdy jest potrzebny. W tym tutorialu pokazuję czym są skille, jak Claude je odkrywa i odpala, pełny frontmatter, progressive disclosure z plikami pomocniczymi oraz różnicę vs subagents i MCP. Z gotowymi przykładami SKILL.md do skopiowania.

Czym są Agent Skills

Agent Skills to mechanizm, który rozszerza to, co Claude Code potrafi, bez pisania pluginu czy MCP servera. Tworzysz katalog z plikiem SKILL.md, w nim instrukcje, a Claude dodaje to do swojego zestawu możliwości. Claude używa skilla, gdy jest relevantny, albo Ty odpalasz go bezpośrednio komendą /nazwa-skilla.

Skill warto stworzyć dokładnie wtedy, gdy zauważasz, że wklejasz tę samą instrukcję, checklistę albo wieloetapową procedurę do czatu raz za razem, albo gdy sekcja w CLAUDE.md rozrosła się z faktu do procedury. W odróżnieniu od treści CLAUDE.md, ciało skilla ładuje się tylko gdy jest używane, więc długa baza referencyjna kosztuje prawie zero tokenów dopóki jej nie potrzebujesz.

Ważny fakt z maja 2026: w Claude Code custom commands zostały scalone ze skillami. Plik .claude/commands/deploy.md i skill .claude/skills/deploy/SKILL.md oba tworzą komendę /deploy i działają tak samo. Stare pliki .claude/commands/ nadal działają, ale skille dają więcej: katalog na pliki pomocnicze, kontrolę inwokacji oraz automatyczne ładowanie przez Claude.

Skille w Claude Code podążają za otwartym standardem Agent Skills, który działa też w innych narzędziach AI i przez Anthropic API. Claude Code dokłada na wierzchu własne rozszerzenia: kontrolę inwokacji, wykonanie w subagencie i dynamiczne wstrzykiwanie kontekstu.

Jak Claude odkrywa i odpala skille

Sercem skilli jest progressive disclosure, czyli stopniowe odsłanianie. Mechanizm ma dwa poziomy:

1. Metadane preload, na starcie sesji do system promptu Claude wczytywane są tylko name i description każdego zainstalowanego skilla. To wystarczy, żeby Claude wiedział, że skill istnieje i kiedy go użyć, bez ładowania całej treści.
2. Treść on-demand, pełny SKILL.md Claude czyta z dysku (przez Read/bash) dopiero, gdy zadanie pasuje do opisu. Pliki referencyjne i skrypty ładuje jeszcze później, tylko te, których realnie potrzebuje.

Dzięki temu możesz mieć dziesiątki czy setki skilli przy minimalnym koszcie kontekstu. To description jest tu krytyczny, bo na jego podstawie Claude wybiera właściwy skill spośród potencjalnie 100+ dostępnych. Zła nazwa albo mglisty opis to najczęstszy powód, dla którego skill się nie odpala.

Po inwokacji wyrenderowana treść SKILL.md wchodzi do rozmowy jako jedna wiadomość i zostaje do końca sesji. Claude Code nie czyta pliku ponownie w kolejnych turach, więc pisz instrukcje jak stałe wytyczne, nie jak jednorazowe kroki.

Struktura katalogu i SKILL.md

Każdy skill to katalog, którego punktem wejścia jest SKILL.md. Pozostałe pliki są opcjonalne:

my-skill/
├── SKILL.md           # główne instrukcje (wymagane)
├── reference.md       # szczegółowa dokumentacja (ładowana w razie potrzeby)
├── examples.md        # przykłady użycia (ładowane w razie potrzeby)
└── scripts/
    └── helper.py      # skrypt do wykonania (nie wczytywany do kontekstu)

Gdzie zapiszesz skill, decyduje kto może go użyć:

Lokalizacje skilli w Claude Code

Poziom	Ścieżka	Dotyczy
Osobisty	~/.claude/skills/<nazwa>/SKILL.md	Wszystkie Twoje projekty
Projektowy	.claude/skills/<nazwa>/SKILL.md	Tylko ten projekt
Plugin	<plugin>/skills/<nazwa>/SKILL.md	Tam, gdzie plugin włączony
Enterprise	Managed settings	Cała organizacja

Przy konflikcie nazw enterprise nadpisuje osobiste, a osobiste nadpisuje projektowe. Komenda, którą wpisujesz, bierze się z nazwy katalogu: .claude/skills/deploy-staging/SKILL.md daje /deploy-staging. Claude Code obserwuje katalogi skilli i podchwytuje zmiany w trakcie sesji bez restartu (poza tworzeniem zupełnie nowego katalogu top-level).

Frontmatter, pola po kolei

Frontmatter to YAML między znacznikami trzech myślników na górze SKILL.md. Wszystkie pola są opcjonalne, rekomendowane jest tylko description. Minimalny przykład:

---
name: api-conventions
description: Wzorce projektowania API w tym repo. Użyj gdy piszesz nowe endpointy.
---

Przy pisaniu endpointów API:
- Używaj nazewnictwa RESTful
- Zwracaj spójny format błędów
- Waliduj request

Najważniejsze pola frontmatter:

Pola frontmatter SKILL.md

Pole	Do czego
name	Nazwa wyświetlana na liście skilli. Domyślnie nazwa katalogu. Max 64 znaki, tylko małe litery, cyfry, myślniki. Bez słów zarezerwowanych "anthropic" i "claude".
description	Co skill robi i kiedy go użyć. Na tej podstawie Claude decyduje o inwokacji. Max 1024 znaki, trzecia osoba.
disable-model-invocation	true = tylko Ty odpalisz skill przez /nazwa. Dla akcji z konsekwencjami (deploy, commit).
user-invocable	false = ukrywa z menu /. Dla wiedzy tła, której nie odpalasz jak komendy.
allowed-tools	Narzędzia, których Claude użyje bez pytania o zgodę, gdy skill jest aktywny.
context	fork = skill biegnie w izolowanym subagencie, jego treść staje się promptem zadania.
agent	Który typ subagenta użyć, gdy ustawiony context: fork (np. Explore, Plan).

Pełny zestaw pól ma jeszcze m.in. argument-hint, arguments, disallowed-tools, model, effort, paths i hooks, ale na start wystarczy description.

Twój pierwszy skill krok po kroku

Zbudujmy skill, który podsumowuje niezacommitowane zmiany w repo i flaguje ryzykowne rzeczy. Pociągnie żywy diff do promptu, zanim Claude go przeczyta, więc odpowiedź jest oparta na realnym stanie repo.

Krok 1, katalog skilla:

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

Krok 2, plik ~/.claude/skills/summarize-changes/SKILL.md:

---
description: Podsumowuje niezacommitowane zmiany i flaguje ryzyko. Użyj gdy
  użytkownik pyta co się zmieniło, chce commit message albo prosi o review diffa.
---

## Aktualne zmiany

!`git diff HEAD`

## Instrukcje

Podsumuj zmiany powyżej w dwóch, trzech punktach, potem wypisz ryzyka jakie
zauważasz: brak obsługi błędów, hardkodowane wartości, testy do aktualizacji.
Jeśli diff jest pusty, powiedz że nie ma niezacommitowanych zmian.

Linia !`git diff HEAD` używa dynamicznego wstrzykiwania kontekstu: Claude Code uruchamia komendę i podmienia tę linię na jej output, zanim Claude zobaczy treść skilla. Instrukcje docierają z aktualnym diffem już wklejonym.

Krok 3, test. Otwórz projekt git, zrób małą zmianę, uruchom claude i albo zapytaj naturalnie:

Co zmieniłem?

(Claude dopasuje do description i sam załaduje skill), albo odpal bezpośrednio:

/summarize-changes

Tyle. Skille są wykrywane na żywo, więc edycja SKILL.md działa bez restartu sesji. Jeśli wcześniej pracowałeś z hookami w Claude Code, zauważysz, że skille i hooki rozwiązują różne problemy: skill mówi Claude jak coś zrobić, hook wymusza coś deterministycznie wokół zdarzeń narzędzi.

Pliki pomocnicze i progressive disclosure

Gdy skill rośnie, nie pakuj wszystkiego do SKILL.md. Trzymaj go pod 500 linii i wynoś szczegóły do osobnych plików, które Claude wczyta dopiero gdy będą potrzebne. Referencje do tych plików dawaj wprost z SKILL.md, żeby Claude wiedział co zawierają.

---
name: pdf-processing
description: Wyciąga tekst i tabele z PDF, wypełnia formularze, łączy dokumenty.
  Użyj przy pracy z PDF albo gdy użytkownik wspomina formularze czy ekstrakcję.
---

# PDF Processing

## Quick start

Wyciągnij tekst przez pdfplumber:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

## Zaawansowane

- Wypełnianie formularzy: zobacz [FORMS.md](FORMS.md)
- Pełne API: zobacz [REFERENCE.md](REFERENCE.md)
- Przykłady: zobacz [EXAMPLES.md](EXAMPLES.md)

Claude wczyta FORMS.md, REFERENCE.md czy EXAMPLES.md dopiero, gdy zadanie ich wymaga. Dwie zasady z dokumentacji Anthropic:

• Referencje jeden poziom w głąb. Wszystkie pliki linkuj bezpośrednio z SKILL.md. Zagnieżdżone referencje (plik A linkuje do B, B do C) powodują, że Claude czyta je częściowo (np. head -100) i mu coś umyka.
• Skrypty wykonuje, nie wczytuje. Utility script (np. scripts/validate.py) Claude odpala przez bash, do kontekstu trafia tylko output. Napisz wprost "uruchom analyze_form.py" (wykonaj) albo "zobacz analyze_form.py" (czytaj jako referencję).

Kto może odpalić skill

Domyślnie obaj: Ty wpisujesz /nazwa, a Claude ładuje skill automatycznie. Dwa pola to zmieniają:

---
name: deploy
description: Deploy aplikacji na produkcję
disable-model-invocation: true
---

Zdeployuj $ARGUMENTS na produkcję:

1. Uruchom testy
2. Zbuduj aplikację
3. Wypchnij na target
4. Zweryfikuj deployment

Wpływ pól na inwokację

Frontmatter	Ty odpalisz	Claude odpali
(domyślnie)	Tak	Tak
disable-model-invocation: true	Tak	Nie
user-invocable: false	Nie	Tak

Użyj disable-model-invocation dla akcji z konsekwencjami (/commit, /deploy, /send-slack-message), nie chcesz, żeby Claude deployował bo kod wygląda gotowo. Użyj user-invocable: false dla wiedzy tła, jak skill legacy-system-context opisujący stary system: Claude ma to znać, ale /legacy-system-context nie jest sensowną akcją dla użytkownika.

Skille przekazują też argumenty. Placeholder $ARGUMENTS zostaje podmieniony na to, co wpiszesz po nazwie. /fix-issue 123 daje Claude "Napraw issue 123...". Pojedyncze argumenty bierzesz przez $ARGUMENTS[0] albo skrót $0.

Skills vs subagents vs MCP

To trzy różne warstwy, które często mylimy. Krótkie rozróżnienie:

Skills vs subagents vs MCP

Mechanizm	Co daje Claude	Kiedy używać
Skill	Instrukcję, procedurę, wiedzę wstrzykniętą do kontekstu	Powtarzalna checklista, konwencje, workflow ("jak to robimy")
Subagent	Izolowaną instancję Claude z własnym kontekstem i narzędziami	Delegacja zadania, praca równoległa, oszczędność kontekstu głównej sesji
MCP server	Nowe narzędzia i dane zewnętrzne przez JSON-RPC	Dostęp do bazy, GitHub, Linear, własnego API ("nowe zdolności")

Mantra: skille mówią Claude jak coś zrobić, MCP daje Claude nowe narzędzia, subagenty dają Claude osobny wątek. Łączą się ze sobą. Skill z polem context: fork odpala się w izolowanym subagencie, a skill może w instrukcjach odwoływać się do narzędzi MCP (pełną nazwą, np. GitHub:create_issue). Jeśli chcesz głębiej wejść w te dwie warstwy, mam osobne tutoriale: Claude Code subagents po polsku oraz Claude Code MCP Server po polsku.

5 praktycznych skilli do skopiowania

1. Konwencje commitów (reference, auto-invoke)

---
name: commit-conventions
description: Format commit messages tego repo (conventional commits). Użyj gdy
  użytkownik pisze commit albo prosi o wiadomość commita.
---

Generuj commit messages w formacie: type(scope): krótki opis

Przykład:
Input: dodano logowanie JWT
Output: feat(auth): implement JWT-based authentication

2. Deploy (task, tylko ręcznie)

---
name: deploy
description: Deploy aplikacji na produkcję
disable-model-invocation: true
allowed-tools: Bash(npm run *) Bash(git push *)
---

Zdeployuj na produkcję:
1. npm run test
2. npm run build
3. git push origin main
4. Zweryfikuj health check

3. Code review z żywym diffem (context: fork)

---
name: review-changes
description: Review niezacommitowanych zmian pod kątem bugów i bezpieczeństwa
context: fork
agent: Explore
allowed-tools: Bash(git *)
---

## Diff
!`git diff HEAD`

## Zadanie
Zrób review zmian powyżej: bugi, edge case, brak walidacji, sekrety w kodzie.

4. Wiedza tła o legacy systemie (user-invocable: false)

---
name: legacy-billing-context
description: Jak działa stary moduł billingu. Claude powinien to znać przy
  pracy z plikami w katalogu billing/.
user-invocable: false
paths: src/billing/**
---

Stary moduł billing używa kolejki SQS i tabeli legacy_invoices.
Nigdy nie modyfikuj schematu bezpośrednio, idź przez migracje w db/migrations.

5. Skill z argumentem (fix issue)

---
name: fix-issue
description: Napraw issue GitHub po numerze
disable-model-invocation: true
argument-hint: [issue-number]
---

Napraw issue $ARGUMENTS zgodnie ze standardami repo:
1. Przeczytaj opis issue
2. Zaimplementuj fix
3. Napisz testy
4. Stwórz commit

Antywzorce, czego unikać

1. Mglisty description. "Pomaga z dokumentami" gwarantuje, że Claude nie odpali skilla. Pisz konkretnie, w trzeciej osobie, ze słowami kluczowymi i "kiedy użyć".
2. Pierwsza osoba w opisie. "Mogę ci pomóc z..." psuje wykrywanie, bo opis idzie do system promptu. Zawsze trzecia osoba: "Przetwarza pliki Excel...".
3. Przegadane SKILL.md. Claude jest mądry, nie tłumacz mu czym jest PDF. Tylko kontekst, którego nie ma. Trzymaj ciało pod 500 linii.
4. Głęboko zagnieżdżone referencje. Plik A → B → C kończy się częściowym czytaniem. Wszystkie referencje jeden poziom od SKILL.md.
5. Ścieżki Windows. Zawsze forward slash (scripts/helper.py), nawet na Windows. Backslash wywala się na Unix.
6. Za dużo opcji. Nie wypisuj pięciu bibliotek do wyboru. Daj jeden default z furtką ("dla skanów użyj OCR").
7. Informacje wrażliwe na czas. Nie pisz "przed sierpniem 2025 użyj starego API". Trzymaj aktualną metodę na wierzchu, stare w sekcji "old patterns".

Co dalej

Skille to jedna z warstw zaawansowanego Claude Code. Sensowna kolejność nauki:

1. Najpierw basics, Claude Code tutorial po polsku
2. Potem skille (ten artykuł), zacznij od jednego skilla na powtarzalną procedurę
3. Potem automatyzacja zdarzeń, Claude Code hooks po polsku
4. Potem delegacja, Claude Code subagents po polsku
5. Na końcu zewnętrzne narzędzia, Claude Code MCP Server po polsku

Najczęściej zadawane pytania

Powiązane artykuły

Claude Code•9 min

Claude Code cena 2026, ile kosztuje i czy jest darmowy

Claude Code cena w PLN i USD, plany Pro i Max, API pay-as-you-go, darmowe kredyty i alternatywy. Najtańsza legalna ścieżka. Stan maj 2026.

Czytaj

Claude Code•9 min

Claude Max plan po polsku, ceny i limity 2026

Plan Claude Max po polsku: ceny Max 5x i 20x, ile zapytań daje, Claude Pro vs Max, Max vs API. Limity sesji i tygodniowe. Stan maj 2026, dla kogo warto.

Czytaj

Claude Code•14 min

Jak zbudować apkę z Claude Code, build-along 2026

Build-along po polsku: jak zbudować apkę z Claude Code od zera. Next.js, /init, Plan Mode, test, deploy na Vercel. Aplikacja z AI bez kodu, krok po kroku.

Czytaj