Skille (SKILL.md) — kompletny poradnik: czym są, jak je pisać i kiedy naprawdę się opłacają

Czego się nauczysz

• Czym naprawdę jest skill — folderem z plikiem SKILL.md, który agent wczytuje dopiero wtedy, gdy jest potrzebny, i dlaczego to jedyny sensowny sposób na trzymanie dziesiątek procedur bez zapychania kontekstu.
• Jak czytać i pisać frontmatter — sześć pól otwartego standardu, ich limity, oraz rozszerzenia Claude Code, które działają lokalnie, ale wysypią upload na claude.ai.
• Jak napisać description, który faktycznie odpala skilla — bo to jedyne pole, które model widzi zanim zdecyduje, czy sięgnąć po Twoją procedurę.
• Gdzie tego używać — w czacie, w Claude Code, w agentach CLI (Cursor, Codex, Copilot, Gemini CLI, Goose), przez API, w pluginach i w zespole.
• Kiedy skill jest złym pomysłem — i co wtedy wybrać zamiast niego: instrukcje projektu, MCP, subagenta, hooka albo RAG.
• Kompletny przepis — od ręcznego wykonania zadania, przez sekcję „pułapki”, pętle walidacji i skrypty, po testy A/B, dystrybucję i audyt bezpieczeństwa.
• Dwa gotowe skille do skopiowania i przerobienia pod siebie.

Poradnik jest podzielony na pięć części. Możesz czytać po kolei albo skoczyć do części, która Cię interesuje — każda jest samodzielna.

---

Część 1. Czym jest skill i dlaczego to działa

Definicja w jednym zdaniu

Skill to folder z plikiem SKILL.md, w którym opisujesz agentowi procedurę — a agent wczytuje ten opis dopiero wtedy, gdy zadanie do niego pasuje.

Tyle. Żadnego API, żadnej instalacji, żadnego frameworka. Minimalny działający skill wygląda tak:

---
name: notatka-ze-spotkania
description: Zamienia surowe notatki lub transkrypcję ze spotkania w podsumowanie z decyzjami i zadaniami. Użyj, gdy użytkownik wkleja notatki ze spotkania, prosi o podsumowanie calla, listę ustaleń albo follow-up po rozmowie.
---

Zamień wklejone notatki w podsumowanie według szablonu poniżej.
Nie zmyślaj ustaleń — jeśli czegoś nie ma w notatkach, napisz „nie ustalono”.

## Szablon

**Cel spotkania:** jedno zdanie
**Decyzje:** lista, każda z osobą, która ją podjęła
**Zadania:** kto — co — do kiedy
**Otwarte pytania:** lista

Ten plik zapisany w odpowiednim katalogu sprawia, że agent — czy to w czacie, czy w terminalu — od tej chwili robi notatki ze spotkań tak samo za każdym razem.

Problem, który to rozwiązuje

Jeśli używasz AI dłużej niż tydzień, znasz ten schemat: masz swój sprawdzony prompt do jakiegoś zadania. Trzymasz go w notatniku. Wklejasz. Poprawiasz. Model coś przekręca, więc dopisujesz do promptu kolejne zdanie. Po miesiącu masz sześć wersji tego samego promptu w trzech miejscach i nie wiesz, która jest aktualna.

Naturalny odruch to wrzucić wszystko do stałych instrukcji — do instrukcji projektu, do CLAUDE.md, do systemowego promptu. To działa do pewnego momentu, a potem przestaje z dwóch powodów:

1. Okno kontekstowe to zasób, który się kończy. Wszystko, co wrzucisz do stałych instrukcji, jest w kontekście zawsze — także wtedy, gdy pytasz o coś zupełnie innego. Dwadzieścia procedur po 800 tokenów to 16 000 tokenów zjedzonych, zanim zadasz pierwsze pytanie.
2. Uwaga modelu też jest zasobem. Im więcej nieistotnych instrukcji w kontekście, tym większa szansa, że model zastosuje procedurę z zupełnie innego zadania.

Skille rozwiązują to jedną, prostą sztuczką.

Progressive disclosure — mechanizm, który trzeba zrozumieć

Agent nie wczytuje skilla w całości. Robi to na trzech poziomach:

Poziom	Co się ładuje	Kiedy	Koszt
1. Metadane	tylko name i description	na starcie sesji, dla każdego dostępnego skilla	ok. 100 tokenów na skilla
2. Instrukcje	całe ciało SKILL.md	dopiero gdy zadanie pasuje do opisu	zalecane < 5 000 tokenów
3. Zasoby	pliki z references/, scripts/, assets/	dopiero gdy instrukcja każe je otworzyć	dowolnie duże

Konsekwencja jest taka, że możesz mieć trzydzieści skilli i płacić za to około 3 000 tokenów na starcie, a pełną treść tego jednego potrzebnego dostać dopiero w momencie użycia. Dokumentacja API na 200 stron w references/ nie kosztuje nic, dopóki agent jej nie otworzy.

To jest cała idea. Wszystko inne w tym poradniku to konsekwencje tego mechanizmu.

Ważne, a często pomijane: gdy skill już się załaduje, jego treść zostaje w kontekście do końca sesji. Nie znika po jednej odpowiedzi. Dlatego każda linijka ciała SKILL.md to koszt powtarzalny, a nie jednorazowy — i dlatego zwięzłość ciała ma znaczenie większe, niż się wydaje.

Dlaczego to nie jest kolejny format jednego dostawcy

Format wymyśliło Anthropic, ale wypuściło go jako otwarty standard — ten sam folder z SKILL.md czyta dziś kilkadziesiąt narzędzi, między innymi Claude Code, ChatGPT/Codex, Cursor, GitHub Copilot i VS Code, Gemini CLI, JetBrains Junie, Goose, OpenHands, Roo Code, Amp, Factory, Kiro, Letta, Tabnine, Snowflake Cortex Code, Databricks Genie Code, Laravel Boost i Spring AI.

Praktyczny wniosek: skill napisany raz jest przenośny. Jeśli zespół przesiądzie się z jednego agenta na inny, procedury zostają. To rzadka sytuacja w świecie AI i główny powód, dla którego warto pisać skille zamiast wiązać wiedzę firmową z konkretnym narzędziem.

Zastrzeżenie, które omawiam szczegółowo w części 2, w sekcji „Pola standardu vs rozszerzenia jednego narzędzia”: przenośne są sześć pól frontmattera i sam markdown. Rozszerzenia konkretnego narzędzia — nie.

Skill a wszystko inne: kiedy co

To najczęstsze źródło nieporozumień. Poniżej rozróżnienie, które warto zapamiętać:

Mechanizm	Co daje agentowi	Kiedy sięgasz
Prompt	jednorazową instrukcję	zadanie jednorazowe albo eksperyment
Instrukcje projektu / CLAUDE.md	stałe fakty i kontekst	„ten projekt używa pnpm”, „piszemy po polsku”, „nie ruszaj folderu legacy”
Skill	procedurę ładowaną na żądanie	„jak zrobić X krok po kroku”, powtarzalny workflow, format wyjścia
MCP / narzędzia	dostęp do systemu (Gmail, Jira, baza, Slack)	agent musi coś odczytać z albo zapisać do zewnętrznego systemu
Subagent	osobny kontekst i budżet	zadanie, które zaśmieciłoby główną rozmowę (research, przegląd kodu)
Hook	wymuszenie — deterministyczny skrypt	coś MUSI się wydarzyć zawsze (lint przed commitem, blokada na plik)

Najkrótsza wersja tego rozróżnienia:

MCP daje agentowi nowe ręce. Skill daje mu know-how, jak tych rąk używać. Hook pilnuje, żeby nie zapomniał.

Te rzeczy się nie wykluczają, tylko uzupełniają (jak działa sam protokół i jak podłączyć serwer, opisuje poradnik o MCP). Realny setup w firmie wygląda tak: MCP do Jiry (dostęp), skill „jak piszemy opisy zgłoszeń” (procedura), instrukcje projektu z nazwami boardów (fakty), hook blokujący commit bez numeru zgłoszenia (wymuszenie).

Jeżeli zastanawiasz się, czy Twoja potrzeba to w ogóle zadanie dla skilla — jest na to test decyzyjny w części 4.

---

Część 2. Anatomia pliku SKILL.md

Struktura katalogu

Skill to zawsze katalog, nie luźny plik. Wymagany jest tylko SKILL.md; reszta zależy od potrzeb:

moj-skill/
├── SKILL.md          # WYMAGANE: frontmatter + instrukcje
├── references/       # dokumentacja doczytywana na żądanie
│   ├── api.md
│   └── schema.yaml
├── scripts/          # kod do wykonania (Python, Bash, JS)
│   ├── waliduj.py
│   └── generuj.sh
└── assets/           # szablony, obrazy, dane
    └── szablon-raportu.docx

Nazwy references/, scripts/ i assets/ to konwencja, nie wymóg — ale trzymanie się jej sprawia, że każdy (człowiek i agent) od razu wie, co gdzie leży.

Zasada standardu: nazwa katalogu musi być identyczna z polem name we frontmatterze. (Claude Code jest tu łagodniejszy — traktuje name jako etykietę i domyślnie bierze nazwę komendy z katalogu — ale jeśli skill ma być przenośny, trzymaj się reguły standardu.)

Frontmatter — sześć pól standardu

Na górze SKILL.md idzie blok YAML między ---. Standard definiuje dokładnie sześć pól:

Pole	Wymagane	Limit	Do czego
name	tak	64 znaki	identyfikator skilla
description	tak	1024 znaki	co robi i kiedy użyć
license	nie	krótko	licencja (np. Apache-2.0)
compatibility	nie	500 znaków	wymagania środowiska
metadata	nie	mapa tekst→tekst	Twoje własne pola (autor, wersja)
allowed-tools	nie	tekst, nazwy rozdzielone spacjami	wstępnie zatwierdzone narzędzia (eksperymentalne)

name — zasady, o które łatwo się potknąć

• 1–64 znaki
• tylko małe litery, cyfry i myślniki
• nie może zaczynać się ani kończyć myślnikiem
• nie może zawierać dwóch myślników z rzędu
• musi być równa nazwie katalogu

name: analiza-pdf        # OK
name: raport-tygodniowy  # OK

name: Analiza-PDF        # ŹLE — wielkie litery
name: -raport            # ŹLE — myślnik na początku
name: raport--tygodniowy # ŹLE — podwójny myślnik

description — najważniejsze pole w całym pliku

To jedyna część skilla, którą model widzi zanim zdecyduje, czy go użyć. Zły opis oznacza, że świetny skill nigdy się nie odpali — albo, co gorsza, będzie odpalał się przy każdym pytaniu.

Wzór, który działa: co robi + kiedy użyć + słowa-wyzwalacze.

# ŹLE — model nie ma pojęcia, kiedy to jest potrzebne
description: Pomaga z PDF-ami.

# DOBRZE — czynności, konteksty użycia i konkretne słowa kluczowe
description: >
  Wyciąga tekst i tabele z plików PDF, wypełnia formularze PDF i scala wiele
  plików w jeden. Użyj, gdy użytkownik wspomina o pliku PDF, skanie, fakturze
  w PDF, wypełnieniu formularza albo prosi o wyciągnięcie danych z dokumentu.

Trzy praktyczne reguły:

1. Pisz o zadaniu użytkownika, nie o mechanizmie. Model dopasowuje opis do tego, co ludzie piszą, a nie do tego, jak Twój skill działa w środku.
2. Wypisz realne sformułowania. „faktura”, „skan”, „wyciągnij dane z dokumentu” — to są prawdziwe wyzwalacze.
3. Najważniejszy przypadek użycia na początek. Niektóre klienty przycinają opis; to, co jest z przodu, ma większą szansę zadziałać.

compatibility i metadata

compatibility przydaje się rzadko — tylko gdy skill naprawdę czegoś wymaga od środowiska:

compatibility: Wymaga Pythona 3.12+, pakietu pandas i dostępu do internetu

metadata to wolna mapa na Twoje własne dane. Agent nic z nią nie robi, ale Twoje narzędzia (katalog skilli, CI) mogą:

metadata:
  author: zespol-danych
  version: "2.1"
  owner: slawomir

Ciało pliku — co i jak pisać

Po frontmatterze idzie zwykły markdown bez żadnych ograniczeń formatu. Ale trzy reguły warto traktować poważnie:

1. Trzymaj się poniżej ~500 linii / ~5 000 tokenów. Powyżej tego progu model zaczyna gubić, co jest istotne dla bieżącego zadania. Dłuższe treści przenieś do references/.

2. Dopisuj to, czego model nie wie. Wycinaj resztę. Przy każdym akapicie zadaj pytanie: „czy model zrobiłby to źle, gdyby tego nie było?”. Jeśli nie — usuń.

<!-- ŹLE — model wie, czym jest PDF -->
PDF (Portable Document Format) to popularny format plików zawierający tekst
i obrazy. Aby wyciągnąć z niego tekst, potrzebna jest biblioteka.
Polecana jest pdfplumber, bo dobrze radzi sobie z większością przypadków.

<!-- DOBRZE — od razu to, czego model sam nie wybierze -->
Do wyciągania tekstu użyj `pdfplumber`.
Dla skanów przełącz się na `pdf2image` + `pytesseract`.

3. Podaj domyślne rozwiązanie, nie menu. Lista pięciu równorzędnych bibliotek to zaproszenie do losowego wyboru. Wskaż jedną i dopisz wyjątek.

Wzorce, które realnie poprawiają skille

Pięć konstrukcji, które warto znać. Nie każdy skill potrzebuje wszystkich.

Sekcja „Pułapki”

Najcenniejsza część większości skilli. Nie ogólniki („obsługuj błędy”), tylko konkretne fakty, które łamią rozsądne założenia:

## Pułapki

- Tabela `uzytkownicy` używa miękkiego usuwania. Bez `WHERE deleted_at IS NULL`
  w wynikach będą konta skasowane.
- To samo ID nazywa się `user_id` w bazie, `uid` w usłudze auth
  i `accountId` w API rozliczeń.
- `/health` zwraca 200, dopóki żyje serwer WWW — nawet gdy baza leży.
  Do sprawdzenia stanu usługi używaj `/ready`.

Praktyka, która działa: za każdym razem, gdy musisz poprawić agenta, dopisz poprawkę do „Pułapek”. To najtańszy sposób na iteracyjne ulepszanie skilla.

Szablon wyjścia

Modele znacznie lepiej dopasowują się do konkretnej struktury niż do jej opisu słownego. Zamiast pisać „raport ma mieć streszczenie, wnioski i rekomendacje”, wklej szkielet:

## Struktura raportu

# [Tytuł]

## Streszczenie
[jeden akapit]

## Kluczowe wnioski
- wniosek z liczbą lub cytatem
- wniosek z liczbą lub cytatem

## Rekomendacje
1. konkretne działanie
2. konkretne działanie

Checklista dla procesów wieloetapowych

## Przebieg

- [ ] 1. Przeanalizuj formularz: `scripts/analizuj.py`
- [ ] 2. Uzupełnij mapowanie pól w `pola.json`
- [ ] 3. Zwaliduj mapowanie: `scripts/waliduj.py`
- [ ] 4. Wypełnij formularz: `scripts/wypelnij.py`
- [ ] 5. Sprawdź wynik

Pętla walidacji

Zamiast liczyć, że agent zrobi dobrze za pierwszym razem — każ mu sprawdzić własną pracę:

1. Wprowadź zmiany
2. Uruchom walidację: `python scripts/waliduj.py output/`
3. Jeśli walidacja nie przechodzi — przeczytaj komunikat, popraw, uruchom ponownie
4. Przejdź dalej dopiero po przejściu walidacji

Plan → walidacja → wykonanie

Dla operacji nieodwracalnych lub masowych. Agent najpierw tworzy plan w formacie strukturalnym, potem konfrontuje go ze źródłem prawdy, i dopiero wtedy wykonuje. Klucz to krok walidacji z komunikatem błędu na tyle konkretnym, żeby agent umiał się sam poprawić.

Pliki dodatkowe — i jak kazać agentowi je otwierać

Sam fakt, że plik leży w references/, nic nie daje. Agent musi wiedzieć kiedy go otworzyć. Porównaj:

<!-- ŹLE — agent nie ma sygnału, kiedy sięgnąć -->
Szczegóły znajdziesz w references/.

<!-- DOBRZE — jasny warunek -->
Jeśli API zwróci status inny niż 2xx, przeczytaj `references/bledy-api.md`
i zastosuj opisaną tam procedurę ponowienia.

Pełny schemat bazy jest w `references/schema.yaml` — otwórz go przed
napisaniem pierwszego zapytania SQL.

Ścieżki podajesz względem katalogu skilla i trzymasz płasko — jeden poziom zagnieżdżenia. Łańcuchy „plik A odsyła do B, B do C” gubią się.

Kiedy pisać skrypt zamiast instrukcji

Sygnał jest prosty: jeśli obserwujesz, że agent za każdym razem wymyśla od nowa tę samą logikę — wykres, parser konkretnego formatu, walidator — to znak, żeby napisać skrypt raz, przetestować go i wrzucić do scripts/. Skrypt jest deterministyczny, tańszy w tokenach i nie halucynuje.

Odwrotnie: jeśli zadanie wymaga oceny sytuacji i wyborów zależnych od kontekstu — to robota dla instrukcji, nie dla kodu.

Pola standardu vs rozszerzenia jednego narzędzia

Tu jest najczęstsza pułapka przy dzieleniu się skillami. Claude Code obsługuje dużo więcej pól niż standard — i to bardzo użyteczne pola. Ale skill z takim polem nie przejdzie uploadu na claude.ai ani przez Skills API; dostaniesz twardy błąd, nie ciche zignorowanie pola:

Unexpected key(s) in SKILL.md frontmatter: argument-hint.
Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

Najważniejsze rozszerzenia Claude Code:

Pole	Co robi
disable-model-invocation: true	tylko Ty możesz odpalić skilla przez /nazwa; model nie ruszy go sam — mocno zalecane dla /deploy, /commit, wysyłania wiadomości
user-invocable: false	odwrotnie: tylko model, skill znika z menu / — dla wiedzy tła, która nie jest akcją
when_to_use	dodatkowe wyzwalacze doklejane do opisu
argument-hint / arguments	podpowiedź i nazwane argumenty pozycyjne
allowed-tools / disallowed-tools	wstępna zgoda na narzędzia / odebranie narzędzi na czas tury
model, effort	wymuszenie modelu i poziomu wysiłku na czas działania skilla
context: fork + agent	uruchomienie skilla w osobnym subagencie, w izolowanym kontekście
paths	skill aktywuje się tylko przy pracy z plikami pasującymi do wzorca
hooks	rejestracja hooków w momencie odpalenia skilla

Do tego dochodzą mechanizmy w treści, których standard nie zna:

• podstawienia: $ARGUMENTS, $0/$1, ${CLAUDE_SKILL_DIR}, ${CLAUDE_PROJECT_DIR}, ${CLAUDE_SESSION_ID}
• wstrzykiwanie dynamicznego kontekstu: !`git diff HEAD` — komenda uruchamia się przed wysłaniem treści do modelu, a jej wynik ląduje w prompcie

To ostatnie jest mocniejsze, niż wygląda. Skill z linią !`git diff HEAD` dostaje realny diff, a nie zgadywanie:

---
description: Podsumowuje niezacommitowane zmiany i wskazuje ryzykowne miejsca.
---

## Bieżące zmiany

!`git diff HEAD`

## Zadanie

Podsumuj zmiany w 2–3 punktach, potem wypisz ryzyka: brak obsługi błędów,
zaszyte wartości, testy do aktualizacji. Jeśli diff jest pusty — powiedz to wprost.

Przy uploadzie na claude.ai i przez Skills API dochodzą jeszcze dwa ograniczenia samej nazwy, o których łatwo zapomnieć: name nie może zawierać ciągów „anthropic” ani „claude”, ani znaczników XML. Skill nazwany claude-raporty przejdzie lokalnie, a odbije się przy wgrywaniu.

Praktyczna zasada: jeśli skill ma żyć tylko w Twoim repo — korzystaj ze wszystkiego. Jeśli ma trafić do czatu, do API albo do innego narzędzia — trzymaj się sześciu pól standardu i czystego markdownu.

---

Część 3. Gdzie i jak się tego używa

Mapa wsparcia platform

Platforma	Wbudowane skille	Własne skille	Jak dostarczasz
claude.ai / aplikacja Claude	tak (pptx, xlsx, docx, pdf)	tak	upload w ustawieniach, per użytkownik
Claude Code	tak (bundled)	tak	pliki na dysku
Claude API	tak	tak	Skills API + narzędzie wykonywania kodu
Cursor, Copilot/VS Code, Codex, Gemini CLI, Goose, OpenHands i inne	zależnie od narzędzia	tak	katalog w repo lub w konfiguracji użytkownika

Rzecz, która zaskakuje najczęściej: synchronizacja działa w jedną stronę i nie jest automatyczna. Skille włączone na koncie claude.ai trafiają do sesji chmurowych i Cowork (są pobierane na starcie sesji), ale skill leżący na Twoim dysku nie trafi sam do czatu ani do chmury. W drugą stronę — żeby lokalny Claude Code widział skille z konta — trzeba jawnie włączyć synchronizację zmienną środowiskową; skille lądują wtedy w ~/.claude/skills/synced/.

3.1. W czacie (claude.ai, aplikacja Claude)

Najniższy próg wejścia i najczęstszy scenariusz dla osób nietechnicznych.

Wbudowane skille obsługują dokumenty: PowerPoint, Excel, Word i PDF. Działają domyślnie, bez żadnej konfiguracji — prośba „zrób z tego prezentację” kończy się realnym plikiem .pptx, a nie opisem slajdów.

Własny skill wgrywasz jako spakowany folder w ustawieniach konta. Od tej chwili jest dostępny w Twoich rozmowach — model sięga po niego sam, gdy description pasuje do tego, o co prosisz.

Ograniczenia, o których warto wiedzieć:

• zasięg jest indywidualny — skill działa dla Ciebie, nie dla całej organizacji
• możliwości środowiska wykonawczego (np. dostęp do sieci) różnią się od tych w Claude Code — nie zakładaj, że skrypt pobierający dane z internetu zadziała tak samo
• rozszerzenia Claude Code (context: fork, !`komenda`, $ARGUMENTS) tu nie zadziałają — plik musi trzymać się standardu

Typowe zastosowania w czacie: format raportu tygodniowego, ton i struktura komunikacji marketingowej, checklista analizy umowy, standard notatki ze spotkania, styl odpowiedzi do klientów.

3.2. W Claude Code i agentach terminalowych

Tu skille są najmocniejsze, bo mają dostęp do systemu plików, sieci i mogą uruchamiać skrypty.

Lokalizacja decyduje o zasięgu:

Miejsce	Ścieżka	Kto z tego korzysta
Osobiste	~/.claude/skills/<nazwa>/SKILL.md	Ty, we wszystkich projektach
Projektowe	.claude/skills/<nazwa>/SKILL.md	każdy, kto sklonuje repo
Plugin	<plugin>/skills/<nazwa>/SKILL.md	wszędzie, gdzie plugin jest włączony
Organizacyjne	ustawienia zarządzane	cała firma

Kilka rzeczy, które warto wiedzieć od razu:

• Odpalanie ręczne: wpisujesz /nazwa-skilla. Nazwa komendy bierze się z nazwy katalogu (w pluginach — z pola name, z prefiksem pluginu).
• Odpalanie automatyczne: model sam sięga po skilla, gdy description pasuje do zadania.
• Argumenty: /napraw-zgloszenie 431 trafia do $ARGUMENTS w treści skilla.
• Podmiana bez restartu: edytujesz SKILL.md, zmiana łapie się w bieżącej sesji.
• Kolejność przy konfliktach nazw: organizacja → osobiste → projektowe. Skille z pluginów mają własną przestrzeń nazw (plugin:nazwa), więc nie kolidują.
• Monorepo: skille z zagnieżdżonych katalogów .claude/skills/ doładowują się, gdy agent dotknie pliku w tym podkatalogu. Pakiet może więc wieźć własne procedury.

3.3. W sesjach chmurowych, Cowork i zadaniach cyklicznych

Pułapka, która potrafi zjeść godzinę debugowania: sesje uruchamiane w chmurze nie czytają ~/.claude/skills/ z Twojego dysku. Ładują skille włączone dla Twojego konta claude.ai, synchronizowane na starcie sesji.

Jeśli skill jest tylko lokalnie, zadanie cykliczne zgłosi, że go nie znalazło. Rozwiązania:

• włącz skilla dla konta claude.ai (działa w sesjach chmurowych i Cowork), albo
• zacommituj go do .claude/skills/ w repozytorium (działa w sesjach chmurowych), albo
• dostarcz go w pluginie zadeklarowanym w ustawieniach repozytorium

3.4. Przez API — we własnym agencie

Jeśli budujesz własnego agenta, skille dostarczasz przez Skills API. Dwa warunki techniczne:

• włączone narzędzie wykonywania kodu (skille działają w sandboksie)
• odpowiedni nagłówek beta w żądaniu

Ograniczenia środowiska API: brak dostępu do sieci, brak instalacji pakietów w locie — tylko biblioteki wstępnie skonfigurowane w sandboksie. Zasięg jest na poziomie workspace’u, więc skill wgrany raz obsługuje wszystkie aplikacje w tej przestrzeni. To dobra wiadomość dla zespołów: jedno miejsce, jedna wersja procedury.

3.5. W innych narzędziach

Skoro format jest otwarty, ten sam katalog czyta Cursor, Copilot i VS Code, Codex, Gemini CLI, Goose, OpenHands, Roo Code, Amp, Kiro, Junie i kilkadziesiąt innych. Szczegóły ścieżki różnią się między narzędziami, ale treść pliku zostaje ta sama.

Praktyczny wniosek dla zespołu mieszanego: trzymaj skille w repo, w standardowym formacie. Każdy podłączy je swoim narzędziem.

Dystrybucja w zespole — cztery drogi

Sposób	Dla kogo	Uwagi
Katalog w repo (.claude/skills/)	zespół projektowy	najprościej, wersjonowane w gicie, review w PR
Plugin / marketplace	wiele zespołów	pakiet: skille + agenci + hooki + serwery MCP
Konto claude.ai	osoby nietechniczne, sesje chmurowe	upload przez ustawienia
Ustawienia zarządzane	cała organizacja	wdrożenie centralne, bez działania użytkownika

Jeśli rozdajesz nie same skille, tylko komplet rozszerzeń naraz — skille, subagentów, hooki i serwery MCP — właściwym opakowaniem przestaje być katalog, a staje się plugin. Jak go zbudować, zwersjonować i wystawić we własnym marketplace, opisuje poradnik o pluginach dla agentów AI.

---

Część 4. Kiedy skille się opłacają, a kiedy są stratą czasu

Test trzech pytań

Zanim napiszesz skilla, odpowiedz sobie:

1. Czy robiłem to zadanie co najmniej trzy razy? Jeśli nie — napisz prompt. Skille dla zadań jednorazowych to koszt bez zwrotu.
2. Czy model bez tej instrukcji zrobiłby to źle? Jeśli poradziłby sobie sam — skill tylko zapycha kontekst. To pytanie odsiewa większość niepotrzebnych skilli.
3. Czy to procedura, czy fakt? Procedura („jak robimy X”) to skill. Fakt („używamy pnpm”) to instrukcje projektu.

Kiedy skill jest właściwym wyborem

• Powtarzalna procedura wieloetapowa. Onboarding klienta, release, audyt SEO, przygotowanie raportu miesięcznego.
• Wiedza specyficzna dla firmy. Konwencje kodu, schemat bazy, sposób opisywania zgłoszeń, tone of voice — rzeczy, których model nie ma skąd znać.
• Wymuszony format wyjścia. Gdy raport ma zawsze wyglądać tak samo, szablon w skillu bije opisywanie formatu w każdym prompcie.
• Narzędzia z pułapkami. API, które zwraca 200 przy błędzie. Biblioteka z nieoczywistym API. Sekcja „Pułapki” oszczędza godziny.
• Dystrybucja wiedzy w zespole. Skill to najtańszy znany mi sposób, żeby wiedza jednej osoby stała się domyślnym zachowaniem agenta dla wszystkich.
• Workflow z walidacją. Wszędzie tam, gdzie da się sprawdzić wynik skryptem, pętla walidacji drastycznie podnosi jakość.

Kiedy odpuścić — i co zamiast

Sytuacja	Zamiast skilla
Zadanie jednorazowe	zwykły prompt
Wiedza ogólna, którą model ma	nic — nie pisz tego
Stały fakt o projekcie	instrukcje projektu / CLAUDE.md
Potrzebny dostęp do systemu	serwer MCP albo narzędzie
Coś musi się wydarzyć zawsze	hook lub skrypt w CI
Tysiące stron dokumentacji	RAG, nie references/
Zadanie zaśmiecające rozmowę	subagent (lub skill z context: fork)

Anty-wzorce, które widać najczęściej

Skill-encyklopedia. Ktoś wrzuca 2 000 linii dokumentacji do SKILL.md. Model gubi się, co jest istotne, i podąża za instrukcjami, które nie dotyczą bieżącego zadania. Zwięzła procedura z jednym działającym przykładem bije wyczerpującą dokumentację.

Opis w stylu „pomaga z X”. Skill się nie odpala i nikt nie wie dlaczego. Prawie zawsze winny jest description bez konkretnych wyzwalaczy.

Skill wygenerowany przez model bez Twojej wiedzy. Poprosisz LLM „napisz skilla do obsługi zgłoszeń” i dostaniesz zbiór ogólników: „obsługuj błędy właściwie”, „stosuj najlepsze praktyki”. Wartość skilla bierze się z rzeczy specyficznych — Twoich schematów, Twoich pułapek, Twoich poprawek. Model ich nie zna.

Zbyt wąski zakres. Trzy skille — „pobierz dane”, „przelicz”, „sformatuj” — ładują się razem przy jednym zadaniu i potrafią sobie przeczyć. Jedna spójna jednostka pracy jest lepsza.

Zbyt szeroki zakres. Skill „obsługa bazy danych” obejmujący i zapytania analityczne, i administrację, i migracje nie odpala się precyzyjnie, bo nie wiadomo, kiedy jest właściwy.

Menu zamiast domyślnej opcji. „Możesz użyć pypdf, pdfplumber, PyMuPDF albo pdf2image” — model wybierze losowo i za każdym razem inaczej.

Ignorowanie kosztu kontekstu. Trzydzieści skilli to ~3 000 tokenów opisów na starcie każdej sesji. To do zaakceptowania. Ale ciało skilla, który się załadował, zostaje do końca rozmowy — pięć rozwlekłych skilli w jednej sesji potrafi zjeść więcej kontekstu niż sama praca.

---

Część 5. Przepis: własny skill od zera do produkcji

Krok 0. Zrób zadanie ręcznie i notuj

Najczęstszy błąd to zaczynanie od pisania SKILL.md. Zacznij od wykonania zadania w rozmowie z agentem — normalnie, z poprawkami. I zapisuj:

• kroki, które zadziałały — kolejność, która doprowadziła do celu
• poprawki, które musiałeś wprowadzić — „użyj biblioteki X, nie Y”, „sprawdź przypadek Z”
• formaty wejścia i wyjścia — jak wyglądały dane
• kontekst, którego agent nie miał — nazwy, konwencje, ograniczenia

Ta lista to szkielet skilla. Poprawki z punktu drugiego trafią wprost do sekcji „Pułapki” i będą najcenniejszą częścią pliku.

Alternatywnie, jeśli masz gotowe materiały — runbooki, dokumentację wewnętrzną, komentarze z code review, historię poprawek w gicie, opisy incydentów — możesz je podać modelowi jako źródło do syntezy skilla. Kluczowe słowo: materiał specyficzny dla Was, nie ogólny artykuł „best practices”.

Krok 1. Nazwa i opis

Nazwa: krótko, po polsku lub angielsku, małe litery z myślnikami, zgodnie z nazwą katalogu.

Opis: wzór z części 2 — co robi + kiedy użyć + wyzwalacze. I od razu test opisu: wypisz dziesięć promptów, przy których skill powinien się odpalić, i pięć, przy których nie powinien. Sprawdź w świeżych sesjach. Jeśli odpala się na wszystkim — opis jest za szeroki. Jeśli na niczym — brakuje w nim słów, których faktycznie używasz.

Krok 2. Ciało — dopasuj sztywność do kruchości

To nie jest tak, że cały skill ma być równie precyzyjny. Dopasuj poziom nakazowości do tego, jak kruche jest zadanie.

Gdy wiele podejść jest poprawnych, daj agentowi swobodę i wyjaśnij dlaczego — agent, który rozumie cel, lepiej decyduje w sytuacjach, których nie przewidziałeś:

## Przegląd kodu

1. Sprawdź zapytania do bazy pod kątem SQL injection (parametryzowane zapytania)
2. Zweryfikuj kontrolę uprawnień na każdym endpoincie
3. Poszukaj wyścigów w kodzie współbieżnym
4. Upewnij się, że komunikaty błędów nie wyciekają szczegółów wewnętrznych

Gdy operacja jest krucha albo nieodwracalna — bądź kategoryczny:

## Migracja bazy

Wykonaj dokładnie tę sekwencję:

    python scripts/migrate.py --verify --backup

Nie modyfikuj komendy i nie dodawaj flag.

Większość skilli ma jedno i drugie. Kalibruj każdą sekcję osobno.

Krok 3. Podziel treść: SKILL.md vs pliki

Do SKILL.md trafia to, co potrzebne przy każdym uruchomieniu: procedura, pułapki, szablon wyjścia. Do references/ — to, co potrzebne czasem: pełny schemat, tabela kodów błędów, specyfikacja API. Do scripts/ — powtarzalna logika. Do assets/ — szablony plików.

I znowu: przy każdym pliku pomocniczym napisz w SKILL.md, w jakiej sytuacji agent ma go otworzyć.

Wyjątek wart zapamiętania: pułapki zostaw w SKILL.md. Jeśli wyniesiesz je do osobnego pliku, agent często nie rozpozna momentu, w którym powinien tam zajrzeć — bo pułapka z definicji jest czymś, czego się nie spodziewa.

Krok 4. Przetestuj porównawczo

Zobaczenie, że skill się odpalił, znaczy tylko tyle, że model go znalazł — nie że zrobił to, o co Ci chodziło. Sprawdzaj dwie rzeczy osobno: czy odpala się na właściwych promptach i czy wynik jest lepszy, gdy się odpali.

Metoda jest ta sama w obu przypadkach: zbierz kilka realnych promptów i uruchom każdy w świeżej sesji — raz ze skillem, raz bez — a potem porównaj. Świeża sesja jest istotna: kontekst z pisania skilla maskuje luki w samych instrukcjach.

Do zautomatyzowania tej pętli w Claude Code służy plugin skill-creator: trzyma przypadki testowe, uruchamia każdy w osobnym subagencie, ocenia wyniki, liczy pass rate i zużycie tokenów ze skillem i bez, robi ślepe porównanie A/B dwóch wersji i osobno testuje trafność samego description.

Do sprawdzenia poprawności formalnej (frontmatter, nazewnictwo) jest walidator referencyjny:

skills-ref validate ./moj-skill

Czytaj przebiegi, nie tylko wyniki końcowe. Jeśli agent marnuje kroki na ślepe zaułki, przyczyna jest zwykle jedna z trzech: instrukcja za mało konkretna (agent próbuje kilku podejść), instrukcja niepasująca do zadania (i tak ją wykonuje), albo za dużo opcji bez wskazanej domyślnej.

Krok 5. Iteruj na realnych uruchomieniach

Pierwsza wersja skilla prawie zawsze wymaga poprawek. Wrzucaj z powrotem do procesu wszystkie wyniki, nie tylko porażki. Pytania: co odpaliło skilla niepotrzebnie? Czego zabrakło? Co można wyciąć?

Nawet jedno przejście „uruchom → popraw” zauważalnie podnosi jakość. Przy trudniejszych domenach potrzeba kilku.

Krok 6. Bezpieczeństwo — potraktuj to poważnie

Skill to wykonywalny prompt. Skill z allowed-tools może przyznać agentowi szerokie uprawnienia, skill z !`komenda` uruchamia kod przed wysłaniem treści do modelu, a skill ze skryptem uruchamia go w Twoim środowisku.

Konsekwencje:

• Instaluj skille tylko z zaufanych źródeł. Złośliwy skill może pokierować agentem tak, żeby wykonał szkodliwe operacje.
• Przeczytaj cały katalog przed użyciem — nie tylko SKILL.md, ale też scripts/ i pliki referencyjne. Szczególną uwagę zwróć na skille pobierające dane z zewnętrznych URL-i: to wektor prompt injection.
• Rób review skilli w PR jak kodu. Skill w repo projektu potrafi przyznać sobie uprawnienia do narzędzi — a jego allowed-tools działa nawet w katalogu, którego nigdy nie oznaczyłeś jako zaufany.
• Skille z efektami ubocznymi oznaczaj disable-model-invocation: true. Nie chcesz, żeby model sam zdecydował o wdrożeniu na produkcję, bo „kod wygląda na gotowy”.
• W organizacji rozważ wyłączenie wykonywania komend powłoki w skillach przez ustawienia zarządzane.

Krok 7. Wersjonuj i utrzymuj

Skill, którego nikt nie utrzymuje, po pół roku uczy agenta nieaktualnej procedury — i robi to z pełnym przekonaniem. To gorsze niż brak skilla.

• Trzymaj skille w gicie, ze zwykłym review.
• Wersję i właściciela zapisz w metadata.
• Ustal kadencję przeglądu — tak samo jak przy bazie wiedzy do RAG-a.
• Gdy zmienia się procedura, zmieniaj skilla w tym samym PR co kod.

---

Pełny przykład: skill „raport-tygodniowy”

Kompletny, realistyczny skill do skopiowania. Trzyma się sześciu pól standardu, więc zadziała wszędzie — w czacie, w Claude Code i przez API.

---
name: raport-tygodniowy
description: >
  Składa tygodniowy raport statusu projektu z surowych notatek, listy zadań
  i danych liczbowych. Użyj, gdy użytkownik prosi o raport tygodniowy, status
  tygodnia, podsumowanie sprintu, „co się działo w tym tygodniu” albo wkleja
  notatki z prośbą o raport dla zarządu.
license: Proprietary
metadata:
  author: zespol-operacyjny
  version: "1.3"
---

Złóż raport tygodniowy według szablonu poniżej. Pracuj wyłącznie na danych,
które dostałeś — nie uzupełniaj brakujących liczb szacunkami.

## Kroki

1. Wypisz z materiału wszystkie zdarzenia z datami.
2. Przypisz każde do jednej kategorii: Dowiezione / W toku / Zablokowane.
3. Wyciągnij liczby (czas, koszt, liczba zgłoszeń). Przy każdej podaj źródło.
4. Zidentyfikuj ryzyka: rzeczy zablokowane dłużej niż 5 dni lub bez właściciela.
5. Złóż raport wg szablonu.
6. Sprawdź według checklisty na końcu. Popraw, jeśli coś nie przechodzi.

## Szablon

# Raport tygodniowy — [projekt], tydzień [nr] ([daty])

**Status ogólny:** zielony / żółty / czerwony — jedno zdanie uzasadnienia

## Dowiezione
- [co] — [kto] — [wpływ w jednym zdaniu]

## W toku
- [co] — [kto] — [planowany termin]

## Zablokowane
- [co] — [blokuje: kto/co] — [od kiedy] — [czego potrzeba, żeby ruszyć]

## Liczby
| Wskaźnik | Ten tydzień | Poprzedni | Zmiana |
|---|---|---|---|

## Ryzyka i decyzje do podjęcia
1. [ryzyko] → [proponowana decyzja] → [kto decyduje]

## Pułapki

- „Zrobione” w notatkach często oznacza „zrobione, ale nie wdrożone”.
  Do sekcji „Dowiezione” wpisuj tylko rzeczy wdrożone na produkcję.
- Jeżeli w materiale nie ma danych z poprzedniego tygodnia, w kolumnie
  „Poprzedni” wpisz „b.d.” — nie przepisuj wartości z tego tygodnia.
- Status „czerwony” wymaga co najmniej jednej pozycji w „Ryzykach”.
- Nie wpisuj nazwisk osób spoza organizacji — używaj roli („klient”, „dostawca”).

## Checklista przed oddaniem

- [ ] Każda liczba ma źródło
- [ ] Każda pozycja „Zablokowane” ma czego potrzeba, żeby ruszyć
- [ ] Status ogólny zgadza się z zawartością sekcji
- [ ] Raport mieści się na jednej stronie

Drugi przykład: skill z walidacją i skryptem

Wersja dla zespołów technicznych — pokazuje pętlę walidacji i wywołanie skryptu z katalogu skilla:

---
name: migracja-schematu
description: >
  Przeprowadza migrację schematu bazy danych w tym projekcie, z kopią zapasową
  i weryfikacją. Użyj, gdy użytkownik prosi o migrację bazy, zmianę schematu,
  dodanie kolumny albo uruchomienie migracji na staging.
compatibility: Wymaga Pythona 3.12+, dostępu do bazy i uprawnień do zapisu w ./backups
---

## Zanim zaczniesz

Przeczytaj `references/schema.yaml`, żeby poznać aktualny stan schematu.
Nie pisz migracji z pamięci.

## Procedura

1. Wygeneruj plan migracji: `scripts/plan.py --out plan.json`
2. Zwaliduj plan wobec bieżącego schematu: `scripts/waliduj.py plan.json`
3. Jeśli walidacja nie przechodzi — przeczytaj komunikat, popraw `plan.json`,
   uruchom walidację ponownie. Nie przechodź dalej przed przejściem walidacji.
4. Wykonaj dokładnie: `python scripts/migrate.py --verify --backup plan.json`
   Nie dodawaj innych flag.
5. Potwierdź wynik: `scripts/sprawdz.py`

## Pułapki

- Migracje na produkcji wymagają okna serwisowego — nigdy nie uruchamiaj
  kroku 4 na produkcji bez wyraźnej zgody użytkownika w tej rozmowie.
- `scripts/waliduj.py` kończy się kodem 1, gdy znajdzie problem. To normalne,
  nie błąd narzędzia — przeczytaj komunikat.
- Kolumny z indeksem trzeba dodawać w dwóch krokach (dodaj kolumnę,
  potem indeks współbieżnie), inaczej migracja zablokuje tabelę.

---

Ściąga

Struktura

nazwa-skilla/
├── SKILL.md      # < 500 linii, < 5 000 tokenów
├── references/   # doczytywane warunkowo
├── scripts/      # kod, gdy agent powtarza tę samą logikę
└── assets/       # szablony

Frontmatter przenośny (sześć pól) name · description · license · compatibility · metadata · allowed-tools

Trzy pytania przed napisaniem skilla Robiłem to 3+ razy? · Model zrobiłby to źle bez tego? · To procedura, nie fakt?

Pięć wzorców, które działają Pułapki · Szablon wyjścia · Checklista · Pętla walidacji · Plan → walidacja → wykonanie

Trzy najczęstsze błędy Opis bez wyzwalaczy · SKILL.md jako encyklopedia · menu opcji zamiast domyślnej

Jedna zasada nadrzędna Dopisuj to, czego model nie wie. Resztę wytnij.