# Jak prawidłowo tworzyć Skills dla Claude Code: od architektury do testowania
> Kompleksowy przewodnik inżynierski dotyczący tworzenia Skills dla Claude Code: anatomia folderów i pliku SKILL.md, stopniowe ładowanie (progressive disclosure), różnice względem hooków oraz podejście oparte na ewaluacji (evaluation-driven).
## 1. Czym jest Skill i dlaczego to pełnoprawny artefakt programistyczny
**Skill (umiejętność)** w Claude Code to standaryzowany, modułowy pakiet wiedzy zawierający opis przepływu pracy (workflow), zestaw reguł domenowych, procedur lub skryptów wykonywalnych, które agent AI automatycznie ładuje do rozwiązania konkretnego typu zadań. Zamiast tego, aby inżynier za każdym razem ręcznie kopiował długie instrukcje do każdej nowej sesji, agent samodzielnie rozpoznaje intencję użytkownika i aktywuje odpowiedni Skill.
Główna różnica między Skill a tradycyjnym kodem programistycznym polega na tym, że decyzję o jego aktywacji podejmuje sam model językowy na podstawie semantycznego dopasowania opisu umiejętności do zapytania użytkownika. Ta decyzja ma charakter **probabilistyczny**: nie ma tu kompilatora ani ścisłego typowania, dlatego precyzja sformułowania metadanych bezpośrednio determinuje, czy umiejętność zostanie aktywowana we właściwym momencie.
```mermaid
flowchart TD
subgraph Invocation ["Активація навички"]
Prompt["Запит користувача"] --> Matcher{"Семантичне зіставлення (LLM)"}
Meta["Frontmatter name + description
(~100 токенів на старті)"] --> Matcher
Matcher -->|Збіг наміру| Load["Підвантаження SKILL.md у контекст"]
Matcher -->|Немає збігу| Normal["Стандартне виконання без навички"]
end
subgraph Execution ["Пайплайн виконання"]
Load --> Steps["Виконання покрокових інструкцій"]
Steps --> Scripts["Запуск локальних скриптів (bash/python)"]
Steps --> Refs["Читання довідкових файлів (references/)"]
Scripts & Refs --> Result["Фінальний артефакт / код"]
end
```
### Dlaczego Skill jest artefaktem inżynierskim, a nie zwykłym tekstem
1. **Wersjonowanie i modularność:** Umiejętność składa się ze standardowych plików repozytorium, jest przechowywana w git i rozwijana zgodnie z tymi samymi zasadami co kod aplikacji.
2. **Rozdzielenie interfejsu i implementacji:** Pole `description` w frontmatter pełni rolę publicznego interfejsu umiejętności, podczas gdy treść `SKILL.md` oraz dołączone skrypty stanowią jej wewnętrzną implementację.
3. **Kompozycyjność:** Umiejętność może wywoływać zewnętrzne narzędzia przez MCP, uruchamiać narzędzia konsolowe i delegować podzadania innym umiejętnościom lub subagentom.
4. **Podatność na regresje:** Niepoprawnie zmodyfikowany opis może prowadzić do „cichej odmowy” (skill przestaje się aktywować) lub halucynacji podczas wykonania kroków.
> [!NOTE]
> Specyfikacja **Agent Skills**, zaproponowana przez Anthropic, jest otwartym formatem. Umiejętności przygotowane zgodnie z tym standardem są kompatybilne nie tylko z Claude Code, ale także z innymi zaawansowanymi narzędziami automatyzacji rozwoju.
---
## 2. Struktura plików i katalogów: SKILL.md, skrypty i zasoby referencyjne
Umiejętność stanowi ustrukturyzowany folder w systemie plików, którego obowiązkowym rdzeniem jest plik `SKILL.md`. W zależności od złożoności zadania umiejętność może być uzupełniona o pomocnicze skrypty, poradniki i szablony.
### Poziomy przechowywania umiejętności w Claude Code
- **Globalne umiejętności (`~/.claude/skills/`):** Dostępne dla developera we wszystkich projektach na bieżącej maszynie. Idealne dla osobistych narzędzi, własnych szablonów commitów czy skryptów analitycznych.
- **Umiejętności projektowe (`.claude/skills/`):** Przechowywane bezpośrednio w repozytorium projektu i committowane do gita. Dostępne dla wszystkich członków zespołu, gwarantując jednolite standardy architektury i testowania.
### Zalecana struktura złożonej umiejętności
```text
.claude/skills/release-notes/
├── SKILL.md # Wymagane: metadane i instrukcje
├── changelog-style.md # Zasób: zasady formatowania listy zmian
└── scripts/
└── gather-prs.py # Wykonywalny skrypt: zbieranie scalonych PR przez API
```
Minimalna umiejętność może składać się wyłącznie z jednego pliku `SKILL.md`. Bardziej rozbudowane systemy pakuje się w katalog umiejętności wraz z własnymi skryptami automatyzacji i dokumentacją, co pozwala utrzymać logikę zwartą i samowystarczalną.
---
## 3. Zasady formatowania Frontmatter: name i description
Plik `SKILL.md` musi zaczynać się od bloku metadanych w formacie YAML Frontmatter. Jest to jedyna część umiejętności, którą Claude odczytuje podczas inicjalizacji sesji w celu zbudowania katalogu dostępnych akcji.
```yaml
---
name: release-notes
description: Drafts release notes from merged pull requests between two git tags. Use when cutting a release or updating the changelog.
---
```
### Formalne ograniczenia dotyczące nazwy (name)
- Długość nie większa niż **64 znaki**.
- Dozwolone są wyłącznie małe litery łacińskie, cyfry i myślniki (`[a-z0-9-]`).
- Zabronione jest używanie jakichkolwiek tagów XML/HTML.
- Zabronione jest używanie zarezerwowanych nazw firmowych (`claude`, `anthropic`).
### Formalne ograniczenia dotyczące opisu (description)
- Obowiązkowe pole niepuste.
- Długość nie większa niż **1024 znaki**.
- Zabronione jest używanie tagów XML.
- Musi jasno opisywać zarówno funkcjonalność umiejętności, jak i kontekstowe wyzwalacze (triggery) do jej aktywacji.
| Pole | Przykład dopuszczalny | Przykład niedopuszczalny | Powód zakazu |
| :--- | :--- | :--- | :--- |
| `name` | `db-migrate-helper` | `Claude-DB-Helper!` | Duże litery, znaki specjalne i zarezerwowane słowo `claude` |
| `name` | `deploy-staging` | `deploy_` | Zakazane znaki podkreślenia i nawiasy ostre |
| `description` | `Generates API documentation from Express routes. Use when updating docs.` | `A tool for API` | Zbyt krótki i niesprecyzowany opis, brak triggerów uruchomienia |
> [!WARNING]
> Jeśli umiejętność powinna być uruchamiana wyłącznie na jawną komendę użytkownika i nie powinna działać automatycznie, jej automatyczne wywołanie można ograniczyć, przekształcając ją w deterministyczną komendę slashową.
---
## 4. Stopniowe ładowanie (Progressive Disclosure) i okno kontekstowe
Skills nie są ładowane do okna kontekstowego modelu w całości podczas uruchamiania sesji. Claude Code wykorzystuje zasadę **stopniowego ładowania (Progressive Disclosure)**, podzieloną na trzy wyraźne poziomy.
```mermaid
flowchart LR
L1["Рівень 1: Метадані
(~100 токенів, читається завжди)"] -->|Тригер збігу| L2["Рівень 2: Тіло SKILL.md
(~1-3k токенів, читається за потреби)"]
L2 -->|Посилання у кроках| L3["Рівень 3: Ресурси та скрипти
(0 токенів до виклику або запуску)"]
```
### Trzy poziomy ładowania
1. **Poziom 1 — Metadane (Metadata):** Nazwy i opisy wszystkich dostępnych umiejętności są ładowane do kontekstu systemowego na początku sesji. Koszt wynosi około 100 tokenów na umiejętność. Pozwala to podłączyć dziesiątki umiejętności do projektu bez ryzyka wyczerpania limitu kontekstu.
2. **Poziom 2 — Treść pliku (Body):** Gdy model zdecyduje, że zapytanie użytkownika odpowiada opisowi umiejętności, odczytuje zawartość `SKILL.md`. Zalecana wielkość treści to do 500 linii, aby nie wypierać roboczej historii dialogu.
3. **Poziom 3 — Dołączone pliki i skrypty (Resources):** Pliki referencyjne (`references/`) są odczytywane tylko wtedy, gdy instrukcja bezpośrednio się do nich odnosi. Skrypty są zazwyczaj uruchamiane przez interpreter bash: ich kod w ogóle nie trafia do okna kontekstowego, zwracany jest jedynie finalny wynik wykonania.
---
## 5. Formułowanie description: tworzenie niezawodnych triggerów aktywacji
Ponieważ `description` jest głównym triggerem probabilistycznego zadziałania, należy poświęcić szczególną uwagę jego sformułowaniu.
### Zasady budowy efektywnego opisu
- **Wyłącznie trzecia osoba:** Piszesz opis w trzeciej osobie (`Generates`, `Performs`, `Audits`). Model postrzega opis jako specyfikację systemową narzędzia; zaimki pierwszej lub drugiej osoby (`I will`, `You can`) pogarszają jakość dopasowania.
- **Formuła „Co + Kiedy”:** Opis powinien jasno odpowiadać na dwa pytania: co dokładnie robi umiejętność i w jakich sytuacjach należy ją stosować.
- **Realne słowa kluczowe:** Uwzględniaj specyficzne terminy techniczne, nazwy plików lub komend, które użytkownik z pewnością wspomni w swoim zapytaniu.
:::tabs
@tab Słaby opis
```yaml
---
name: release-notes
description: Handles project releases and writes updates.
---
```
*Problem: Brak konkretnych triggerów kontekstowych. Model nie wie, jakie pliki czytać i kiedy dokładnie aktywować umiejętność.*
@tab Wzorcowy opis
```yaml
---
name: release-notes
description: Drafts release notes from merged pull requests between two git tags. Use when cutting a release, updating the changelog, or summarizing what changed in a version.
---
```
*Zaleta: Jasno określone encje wejściowe (git tags, pull requests) oraz scenariusze aktywacji (cutting a release, updating changelog).*
:::
---
## 6. Anatomia wzorcowego Skill: krok po kroku analiza pipeline'u release-notes
Przeanalizujmy praktyczną architekturę umiejętności automatyzacji dokumentacji wydaniowej `release-notes`.
### Składniki przepływu pracy
- **Parametry wejściowe:** Argumenty użytkownika (zakres tagów `v1.2.0..v1.3.0`), przewodnik stylowy `changelog-style.md`, pomocniczy skrypt `gather-prs.py`.
- **Sekwencja krokowa w `SKILL.md`:**
1. Określ zakres tagów wydaniowych w git.
2. Uruchom skrypt `python scripts/gather-prs.py` w celu uzyskania ustrukturyzowanej listy commitów.
3. Pogrupuj zmiany według kategorii (Features, Fixes, Performance, Breaking Changes).
4. Przygotuj draft zgodnie ze stylem w `changelog-style.md`.
5. Zapisz zaktualizowany blok w `CHANGELOG.md` i wyświetl krótkie podsumowanie.
- **Artefakty wyjściowe:** Zaktualizowany plik `CHANGELOG.md` oraz zwięzła wiadomość dla zespołu.
### Zasady architektoniczne dla treści pliku
1. **Nie powtarzaj oczywistości:** Załóż, że Claude jest już wykwalifikowanym inżynierem. Opisuj tylko specyfikę swojego projektu i surowe wymagania korporacyjne.
2. **Głębokość odniesień – tylko jeden poziom:** Pliki referencyjne nie powinny łańcuchowo wskazywać na inne pliki. Wszystkie materiały muszą być bezpośrednio przypisane do `SKILL.md`.
3. **Ścieżki cross-platformowe:** Zawsze używaj ukośników (`/`) we wszystkich ścieżkach do plików i konfiguracji.
---
## 7. Krajobraz customizacji: Skills, CLAUDE.md, Slash-komendy, MCP, hooki i pluginy
W Claude Code istnieje kilka mechanizmów sterowania zachowaniem agenta. Błędny wybór mechanizmu to najczęstsza przyczyna niestabilności systemu.
| Mechanizm | Kto inicjuje uruchomienie | Siła wpływu | Optymalny scenariusz użycia |
| :--- | :--- | :--- | :--- |
| **CLAUDE.md (Memory)** | Runtime (zawsze w kontekście) | Rekomendacyjna | Krótkie ogólne zasady projektu, stack technologiczny, podstawowe komendy |
| **Skill** | Model (semantycznie) lub człowiek | Rekomendacyjna | Złożone procedury domenowe, przepływy pracy z dołączonymi skryptami |
| **Slash-komenda** | Użytkownik (przez `/komenda`) | Rekomendacyjna | Zapisane interaktywne szablony promptów wywoływane ręcznie |
| **Subagent** | Model lub użytkownik | Izolowana | Delegowanie niezależnego, obszernego zadania do oddzielnego okna kontekstowego |
| **MCP Tool** | Model (przez Tool Call) | Wykonawcza | Bezpośrednia interakcja z zewnętrznymi bazami danych i chmurowymi API |
| **Hook** | Runtime (deterministycznie) | **Blokująca** | Sztywne sprawdzenia bezpieczeństwa, lintery przed commitem, walidacja działań |
| **Plugin** | Użytkownik (instalacja) | Kompleksowa | Pakietowe dystrybuowanie zestawu umiejętności, serwerów MCP i hooków dla zespołu |
> [!IMPORTANT]
> Tylko mechanizmy zarządzane bezpośrednio przez runtime (np. **hooki**) są zdolne do zapewnienia absolutnej gwarancji wykonania i blokowania niepożądanych działań. Tekstowa instrukcja wewnątrz Skill pozostaje rekomendacją, której model przestrzega probabilistycznie.
---
## 8. Skills kontra Hooks: balans między rekomendacjami a gwarancjami runtime
Początkujący często próbują używać Skills do zadań związanych z bezpieczeństwem lub wymuszeniem formatowania kodu. To błąd koncepcyjny: umiejętność nie gwarantuje wykonania, ona jedynie uczy model prawidłowego podejścia.
### Punkty cyklu życia wykonania
- **SessionStart (Hook):** Aktywuje się przy otwarciu sesji. Gwarantuje inicjalizację zmiennych środowiskowych lub wstępne sprawdzenie gałęzi git.
- **Rozumowanie modelu (Możliwe odczytanie Skill):** Model analizuje zadanie i podejmuje decyzję o załadowaniu treści `SKILL.md`.
- **PreToolUse (Hook, blokujący):** Wykonuje się bezpośrednio przed wywołaniem dowolnego narzędzia. Może sprawdzić komendę bash i zablokować jej wykonanie (kod zwrotu 2), jeśli narusza zasady bezpieczeństwa.
- **PostToolUse (Hook):** Analizuje wynik wykonania komendy lub modyfikacji pliku (np. automatycznie uruchamia Prettier po zapisaniu pliku).
- **Stop (Hook):** Aktywuje się po zakończeniu generowania odpowiedzi przez model.
```text
Złota zasada wyboru:
- Jeśli działanie wymaga elastycznego myślenia inżynierskiego i kontekstu ──► Twórz SKILL
- Jeśli działanie musi być wykonywane bezwarunkowo i bez wyjątków ──► Konfiguruj HOOK
```
---
## 9. Proces developmentu poprzez ewaluację (Evaluation-Driven Development)
Tworzenie niezawodnej umiejętności wymaga iteracyjnego testowania na rzeczywistych scenariuszach jeszcze przed napisaniem finalnej treści instrukcji.
### Cztery etapy tworzenia umiejętności
1. **Ustalenie poziomu bazowego (Baseline):** Uruchom Claude Code na typowych zadaniach roboczych bez umiejętności. Zanotuj, gdzie dokładnie model popełnia błędy, pomija kroki lub wymaga dodatkowych wyjaśnień.
2. **Tworzenie przypadków testowych (Eval Suite):** Przekształć zanotowane błędy na listę zadań kontrolnych z jasno zdefiniowanymi oczekiwanymi wynikami.
3. **Napisanie minimalnej treści (MVP):** Sformułuj minimalny zestaw instrukcji w `SKILL.md`, wystarczający do pomyślnego przejścia testów.
4. **Iteracyjne doskonalenie:** Dodawaj reguły i wyjątki tylko w odpowiedzi na konkretne porażki przypadków testowych, unikając rozdmuchiwania kontekstu.
### Workflow z dwoma instancjami modelu
Podczas projektowania umiejętności zaleca się korzystanie z dwóch równoległych terminali:
- **Instancja edytora:** Sesja, w której wspólnie z Claude formułujesz, uzupełniasz i strukturujesz tekst nowej umiejętności.
- **Instancja testera:** Czysta sesja, w której uruchamiasz testowe zapytania i sprawdzasz: czy umiejętność jest przechwytywana automatycznie, czy kroki są poprawnie interpretowane i czy pliki wynikowe są ważne.
---
## 10. Typowe wzorce projektowe i antywzorce przy tworzeniu Skills
Praktyczne doświadczenie społeczności wyodrębniło szereg sprawdzonych szablonów oraz typowych błędów, których należy unikać.
### Efektywne wzorce inżynierskie
- **Numerowane sekwencje deterministyczne:** Dla złożonych, wieloetapowych akcji zawsze strukturuj kroki w formie `1. ...`, `2. ...`, `3. ...`.
- **Wbudowane checklisty walidacji:** Dla krytycznych operacji dodaj checklistę, którą model powinien skopiować do odpowiedzi i odhaczać w miarę wykonania.
- **Pętle autowalidacji (Verify & Fix):** Ustaw regułę: „Uruchom linter -> napraw błędy -> sprawdź ponownie do czystego outputu”.
- **Planowanie przed działaniami destrukcyjnymi:** Dla operacji masowego usuwania lub nadpisywania plików wymagaj najpierw sformułowania planu zmian w tabeli markdown i poproszenia o potwierdzenie.
### Popularne antywzorce
- **Paraliż wyboru:** Opisywanie nadmiernej ilości alternatywnych bibliotek lub podejść bez wskazania domyślnego wariantu.
- **Nieogłoszone zależności systemowe:** Używanie zewnętrznych narzędzi CLI lub pakietów npm bez wcześniejszej instrukcji dotyczącej ich instalacji lub sprawdzenia obecności.
- **Backslashe w ścieżkach:** Używanie backslashów w stylu Windows (`src\utils\`), co powoduje awarie na Linux i macOS.
- **Niewyjaśnione magiczne liczby:** Używanie stałych lub timeoutów bez komentarza dotyczącego ich pochodzenia.
---
## 11. Bezpieczeństwo i audyt zewnętrznych Skills przed instalacją
Każda zewnętrzna umiejętność to wykonywalny kod w Twoim środowisku roboczym. Ponieważ Claude Code ma dostęp do systemu plików, terminala i sieci, niezweryfikowany Skill niesie poważne ryzyko bezpieczeństwa.
### Checklista audytu zewnętrznej umiejętności przed użyciem
- [ ] **Analiza treści `SKILL.md`:** Sprawdź tekst pod kątem ukrytych instrukcji z prompt injection, prób kradzieży plików `.env` lub wyłączania mechanizmów ochronnych.
- [ ] **Audyt dołączonych skryptów:** Uważnie przeanalizuj wszystkie pliki w katalogu `scripts/`. Upewnij się, że skrypty nie wykonują podejrzanych żądań sieciowych do zewnętrznych serwerów.
- [ ] **Sprawdzenie zewnętrznych URL-i:** Zwróć uwagę na wszelkie linki do pobierania zewnętrznych plików binarnych lub dynamicznych konfiguracji.
- [ ] **Testowanie w izolacji:** Pierwsze uruchomienie zewnętrznej umiejętności zawsze przeprowadzaj w testowym repozytorium lub piaskownicy bez dostępu do sekretów produkcyjnych.