Kurs Claude Code - Lekcja 16: Skills, własne komendy /slash

Wyobraź sobie że wpisujesz /deploy-staging i Claude Code sam pobiera aktualny diff, sprawdza testy, buduje Docker image i wysyła na serwer. Albo /review-pr 1234 i agent natychmiast ściąga kod z GitHub, analizuje i zwraca rzeczowy komentarz. To nie magia - to Skills, jeden z najpotężniejszych mechanizmów personalizacji Claude Code, o którym większość deweloperów jeszcze nie wie.

Skills vs CLAUDE.md vs Hooks - gdzie jest różnica?

Zanim zbudujesz pierwszy skill, warto zrozumieć ekosystem. Claude Code ma kilka mechanizmów rozszerzeń które wyglądają podobnie ale mają inny zakres zastosowań:

Kluczowa zasada: stała wiedza o projekcie to CLAUDE.md. Procedura wywoływana sytuacyjnie to Skill. A rzecz, która ma się uruchamiać automatycznie przy zdarzeniu, to Hook.

Gdzie żyją Skills - struktura katalogów

Skills to katalogi w .claude/skills/. Każdy skill to osobny podkatalog z obowiązkowym plikiem SKILL.md i opcjonalnymi plikami pomocniczymi:

Claude Code odkrywa skills automatycznie - skanuje katalog .claude/skills/ w bieżącym projekcie, katalogach nadrzędnych (aż do roota repo) i globalnym ~/.claude/skills/. Zmiany w SKILL.md wchodzą w życie w bieżącej sesji bez restartu.

Anatomia SKILL.md - frontmatter i treść

Plik SKILL.md ma dwie części: frontmatter (metadane w formacie YAML między ---) i treść (instrukcje dla Claude, format Markdown). Zobaczmy kompletny przykład z opisem każdego pola:

---
# FRONTMATTER - metadane skilla (format YAML)

name: fix-github-issue          # nazwa w menu /skills (domyślnie: nazwa katalogu)
description: Naprawia zgłoszenie (issue) z GitHub.  # kluczowe: Claude używa do automatycznego uruchamiania
  Użyj gdy użytkownik podaje numer zgłoszenia, pyta o błąd lub prośbę o nową funkcję.
when_to_use: Przy zgłoszeniach błędów, prośbach o nowe funkcje, pracy w oparciu o zgłoszenia.

argument-hint: [numer-issue] [branch]   # podpowiedź w autocomplete po wpisaniu /
arguments: [issue_num, branch]      # mapowanie nazwanych zmiennych

allowed-tools: Bash(git *) Bash(gh *) # te narzędzia nie pytają o zgodę

model: sonnet                     # opcjonalne: nadpisanie modelu dla tego skilla
effort: high                      # low | medium | high | xhigh | max
---

# Treść skilla - instrukcje dla Claude w Markdown

## Napraw zgłoszenie #$issue_num

Działaj automatycznie bez pytania o potwierdzenie każdego kroku.

### Krok 1: Pobierz szczegóły z GitHub

!'gh issue view $issue_num --json title,body,labels,assignees'

### Krok 2: Sprawdź powiązane pliki

Przeanalizuj powyższe zgłoszenie. Zidentyfikuj źródło problemu i pliki do zmiany.

### Krok 3: Zaimplementuj poprawkę i utwórz PR

1. 'git checkout -b fix/issue-$issue_num'
2. Dokonaj minimalnych zmian naprawiających problem
3. Dodaj/zaktualizuj testy
4. 'git add -A && git commit -m "Fix: zgłoszenie #$issue_num"'
5. 'git push -u origin fix/issue-$issue_num'
6. 'gh pr create --fill'

Wszystkie pola frontmatteru - ściąga

Jak wywołać skill - trzy sposoby

1. Ręcznie przez /nazwa-skilla

Najprostszy sposób - wpisz ukośnik i nazwę skilla w promptcie. Podpowiedzi autocomplete pokazują dostępne skills z ich argument-hint:

# Bez argumentów
/fix-github-issue

# Z argumentami
/fix-github-issue 1234
/fix-github-issue 1234 main
/deploy-staging
/review-pr 567

2. Automatyczne uruchomienie przez opis skilla

Jeśli description skilla pasuje do zapytania użytkownika - Claude załaduje go automatycznie bez wpisywania /. To wymaga przemyślanego opisu:

# Skill z opisem: "Naprawia błędy i zgłoszenia z GitHub. Użyj gdy użytkownik pyta o błąd."

# Te zapytania uruchamiają skill automatycznie:
"Jest błąd w zgłoszeniu #1234, napraw to"
"Mamy zgłoszenie #89 do zamknięcia"
"Coś się sypie w module logowania, sprawdź zgłoszenie #56"

# Te NIE uruchamiają skilla (za mało słów kluczowych):
"Napisz testy do UserService"
"Zrefaktoryzuj ten kod"

Wskazówka: Jeśli skill uruchamia się za często - zawęź opis. Jeśli za rzadko - dodaj synonimy do when_to_use. Możesz też wyłączyć automatyczne uruchamianie przez disable-model-invocation: true i zostawić tylko ręczne wywołanie.

3. Listowanie dostępnych skills

# Lista wszystkich dostępnych skills
/skills

# Wynik:
Available skills:
fix-github-issue   Naprawia zgłoszenie z GitHub. Użyj gdy użytkownik podaje numer zgłoszenia...
deploy-staging     Wdraża aplikację na środowisko staging. Tylko ręczne wywołanie.
review-pr          Przegląd kodu pull requesta. Pobiera zmiany z GitHub i analizuje.
summarize-changes  Podsumowanie niezacommitowanych zmian.

Wstrzykiwanie żywych danych - aktualne dane w skillach

To jest mechanizm który sprawia że skills są naprawdę potężne. Specjalna składnia wewnątrz pliku SKILL.md (pokazujemy ją w listingu poniżej) powoduje że zanim Claude zobaczy skill, Claude Code wykonuje wskazane polecenie powłoki i wstawia jego wynik w to miejsce.

---
name: review-pr
description: Przegląd kodu pull requesta z GitHub
allowed-tools: Bash(gh *)
---

## Review PR #$0

### Pobrane z GitHub (żywe dane):

**Diff:**
!'gh pr diff $0'

**Informacje:**
!'gh pr view $0 --json title,author,body,labels'

**Lista zmienionych plików:**
!'gh pr diff $0 --name-only'

---

Przejrzyj powyższy diff. Oceń:
1. Poprawność logiki biznesowej
2. Obsługę błędów i przypadków brzegowych
3. Jakość kodu (czytelność, duplikacje)
4. Brakujące testy
5. Potencjalne problemy z bezpieczeństwem

Zwróć listę konkretnych uwag z numerami linii.

Gdy użytkownik wpisze /review-pr 234, Claude Code najpierw wykona gh pr diff 234, gh pr view 234 --json ... i gh pr diff 234 --name-only, wstawi wyniki, a dopiero potem cały skill (z aktualnym diffem!) trafi do kontekstu Claude.

Wielolinijkowe wstrzykiwanie danych

Dla wielu poleceń możesz użyć bloku kodu z wykrzyknikiem:

---
name: project-status
description: Aktualny status projektu - gałęzie, testy, build
---

## Status projektu (aktualne dane)

```!
echo "=== GIT STATUS ==="
git status --short
echo ""
echo "=== OSTATNIE COMMITY ==="
git log --oneline -10
echo ""
echo "=== BRANCH INFO ==="
git branch -v
echo ""
echo "=== WYNIKI TESTÓW ==="
npm test --silent 2>&1 | tail -20
```

Na podstawie powyższego stanu projektu odpowiedz co warto teraz zrobić
i czy są jakieś alarmy wymagające natychmiastowej uwagi.

Dostępne zmienne środowiskowe przy wstrzykiwaniu

# Zmienne dostępne w !'komenda' i w treści skilla:
$ARGUMENTS            # wszystkie argumenty jako jeden string
$0                    # pierwszy argument (skrót)
$1                    # drugi argument
$ARGUMENTS[0]         # pierwszy argument (alternatywnie)
$nazwa_zmiennej        # nazwana zmienna z pola arguments: [nazwa_zmiennej]
${CLAUDE_SESSION_ID}  # ID bieżącej sesji Claude Code
${CLAUDE_SKILL_DIR}   # absolutna ścieżka do katalogu skilla
${CLAUDE_EFFORT}      # aktualny poziom wysiłku (low/medium/high...)

Nazwane argumenty - parametryzowane skills

Zamiast odwoływać się do $0, $1, możesz zdefiniować nazwane zmienne. Zwiększa to czytelność skilla i pomaga Claude lepiej rozumieć kontekst:

---
name: migrate-component
description: Migruje komponent UI z jednego frameworka do drugiego
argument-hint: [komponent] [z-frameworka] [do-frameworka]
arguments: [component, fromFramework, toFramework]
---

## Migracja: $component ($fromFramework -> $toFramework)

Przeprowadź migrację komponentu '$component' z '$fromFramework' do '$toFramework'.

### Pliki do analizy:
!'find . -name "$component*" -not -path "*/node_modules/*"'

### Istniejący kod:
!'find . -name "$component*" -not -path "*/node_modules/*" | head -3 | xargs cat'

Zmień kod tak żeby:
1. Zachować identyczne API (props/events/slots)
2. Używać konwencji i idiomów $toFramework
3. Usunąć wszystkie importy $fromFramework
4. Zaktualizować testy

Nie zmieniaj logiki biznesowej komponentu.

Wywołanie:

/migrate-component SearchBar React Vue
# $component = SearchBar, $fromFramework = React, $toFramework = Vue

/migrate-component UserProfileCard Angular React
# $component = UserProfileCard, $fromFramework = Angular, $toFramework = React

Izolowany kontekst podagenta (context: fork)

Pole context: fork sprawia że skill uruchamia się w oddzielnym kontekście podagenta - bez historii bieżącej rozmowy. To świetne dla długich zadań badawczych, analizy kodu lub operacji które mają własny zakres, niezależny od rozmowy:

---
name: deep-research
description: Dogłębne zbadanie tematu w kodzie. Użyj gdy pytasz "jak działa X w tym projekcie?"
context: fork
agent: Explore           # Explore = tylko narzędzia tylko do odczytu, mniejszy kontekst
effort: high
---

Zbadaj dogłębnie: **$ARGUMENTS**

Kroki:
1. Znajdź wszystkie istotne pliki (Glob, Grep)
2. Przeczytaj kod od początku do końca
3. Śledź przepływ danych i zależności
4. Zidentyfikuj przypadki brzegowe i potencjalne problemy

Zwróć:
- Pełne wyjaśnienie jak to działa
- Ścieżki do kluczowych plików z numerami linii
- Niezrozumiałe fragmenty lub ryzyka
- Sugestie refaktoryzacji jeśli widzisz problemy

Dostępne typy agentów przy context: fork:

Wbudowane skills - co jest w pudełku

Claude Code dostarcza zestaw domyślnych skills dostępnych w każdym projekcie (można je wyłączyć przez disableBundledSkills: true w settings.json (dokładna nazwa klucza może różnić się między wersjami - sprawdź aktualną dokumentację)):

Skill nr 1: summarize-changes (codziennik pracy)

Jeden z najbardziej przydatnych skills do codziennego użytku - podsumowuje co zrobiłeś w danym dniu:

---
# ~/.claude/skills/summarize-changes/SKILL.md
name: summarize-changes
description: Podsumowuje niezacommitowane zmiany i ostatnie commity. Użyj na koniec dnia roboczego lub przed daily.
---

## Stan projektu

### Niezacommitowane zmiany:
!'git diff --stat HEAD 2>/dev/null || echo "Brak zmian"'

### Szczegóły zmian:
!'git diff HEAD 2>/dev/null | head -200'

### Ostatnie 5 commitów:
!'git log --oneline -5'

---

Na podstawie powyższych danych:

1. Napisz **zwięzłe podsumowanie** (5-10 zdań) co zostało zrobione
2. Wypisz **lista ukończonych zadań** (bullet points)
3. Zaznacz **otwarte kwestie** i decyzje wymagające uwagi
4. Zaproponuj **commit message** dla niezacommitowanych zmian (conventional commits)

Styl: zrozumiały dla menedżera, bez żargonu technicznego.

Skill nr 2: deploy-staging (wdrożenie z kontrolą wstępną)

Skill który nigdy nie uruchomi się przez przypadek - disable-model-invocation: true zapewnia że tylko Ty możesz go wywołać:

---
# .claude/skills/deploy-staging/SKILL.md
name: deploy-staging
description: Deploy aplikacji na środowisko staging
disable-model-invocation: true   # TYLKO ręczne wywołanie /deploy-staging
allowed-tools: Bash(docker *) Bash(kubectl *) Bash(git *)
argument-hint: [wersja]
---

## Wdrożenie na Staging

### Kontrola wstępna:
!'git status --short'
!'git log --oneline -3'

Aktualna gałąź: !'git rev-parse --abbrev-ref HEAD'
Ostatni tag: !'git describe --tags --abbrev=0 2>/dev/null || echo "brak tagów"'

---

Wykonaj deploy:

1. **Sprawdź zmiany:** czy powyższe niezacommitowane zmiany to problem?
   - Jeśli tak - STOP i poinformuj użytkownika
   - Jeśli nie - kontynuuj

2. **Uruchom testy:**
```bash
npm run test -- --ci
```

3. **Zbuduj obraz Docker:**
```bash
docker build -t myapp:staging-$0 .
docker push registry.mycompany.com/myapp:staging-$0
```

4. **Deploy na Kubernetes:**
```bash
kubectl set image deployment/myapp-staging myapp=registry.mycompany.com/myapp:staging-$0 -n staging
kubectl rollout status deployment/myapp-staging -n staging
```

5. **Weryfikuj:**
```bash
kubectl get pods -n staging
curl -f https://staging.myapp.com/health
```

Raportuj wynik każdego kroku. Przy błędzie - STOP i podaj szczegóły.

Skill nr 3: generate-migration (migracje bazy danych)

Skill który automatycznie generuje migracje na podstawie analizy aktualnego schematu:

---
# .claude/skills/generate-migration/SKILL.md
name: generate-migration
description: Generuje migrację bazy danych. Użyj gdy dodajesz/zmieniasz model Django/SQLAlchemy/Prisma.
argument-hint: [opis-zmiany]
allowed-tools: Bash(python *) Bash(psql *)
---

## Generuj migrację: $ARGUMENTS

### Aktualny stan modeli:
!'find . -name "models.py" -not -path "*/venv/*" | head -5 | xargs grep -l "class " 2>/dev/null'

### Historia ostatnich migracji:
!'find . -path "*/migrations/*.py" -not -name "__init__.py" | sort | tail -5'

### Schemat aktualnych tabel:
!'python manage.py showmigrations --list 2>/dev/null | tail -20 || echo "Nie Django"'

---

Wygeneruj migrację dla: **$ARGUMENTS**

Kroki:
1. Przeanalizuj istniejące modele i migracje
2. Zaproponuj zmianę w modelu (pokaż diff)
3. Wygeneruj migrację: 'python manage.py makemigrations --name "$ARGUMENTS"'
4. Sprawdź wygenerowany plik migracji
5. Zaproponuj wycofanie migracji (plik odwrotnej migracji)
6. Pokaż SQL który zostanie wykonany: 'python manage.py sqlmigrate  '

Uwagi do bezpieczeństwa:
- Przy dodaniu NOT NULL bez wartości domyślnej - ostrzeż o potrzebie uzupełnienia danych
- Przy zmianie nazwy kolumny - zaproponuj migrację w 3 krokach (dodaj + skopiuj + usuń)
- Przy DROP - zaproponuj usuwanie logiczne zamiast trwałego skasowania

Skill nr 4: explain-code (z izolowanym podagentem)

Skill który używa context: fork i agenta Explore do pełnej analizy wskazanego fragmentu - bez zaśmiecania bieżącej rozmowy:

---
name: explain-code
description: Dogłębne wyjaśnienie jak działa wskazany fragment kodu. Użyj gdy pytasz "jak działa X"
argument-hint: [funkcja-klasa-plik]
context: fork
agent: Explore
effort: high
---

Przeprowadź dogłębną analizę: **$ARGUMENTS**

1. Znajdź wskazany komponent/funkcję/klasę w kodzie
2. Przeczytaj CAŁY plik - nie tylko wskazany fragment
3. Śledź zależności - co importuje, co wywołuje, co go wywołuje
4. Sprawdź testy jeśli istnieją
5. Sprawdź historię git jeśli istotna: !'git log --oneline --follow -5 -- "$ARGUMENTS" 2>/dev/null'

Odpowiedź sformatuj jako:
- **Co robi** (1 zdanie)
- **Jak to działa** (algorytm krok po kroku)
- **Zależności** (co potrzebuje, co zwraca)
- **Przypadki brzegowe** (co może pójść nie tak)
- **Sugestie** (co można poprawić)

Podawaj konkretne ścieżki plików i numery linii.

Skill nr 5: setup-project (inicjalizacja projektu z instrukcją)

Skill który nowy developer wpisuje raz po sklonowaniu repo - instaluje wszystko i konfiguruje środowisko:

---
# .claude/skills/setup-project/SKILL.md
name: setup-project
description: Pełna konfiguracja środowiska deweloperskiego. Uruchom po sklonowaniu repo.
disable-model-invocation: true
allowed-tools: Bash(npm *) Bash(pip *) Bash(cp *) Bash(mkdir *)
---

## Setup środowiska deweloperskiego

### Sprawdź wymagania:
!'node --version 2>/dev/null || echo "Node.js nie zainstalowany"'
!'python3 --version 2>/dev/null || echo "Python3 nie zainstalowany"'
!'docker --version 2>/dev/null || echo "Docker nie zainstalowany"'

### Aktualna zawartość .env:
!'ls -la .env* 2>/dev/null || echo "Brak pliku .env"'

---

Skonfiguruj środowisko krok po kroku:

1. **Sprawdź powyższe wymagania** - jeśli brakuje narzędzi -> poinformuj i zatrzymaj

2. **Zainstaluj zależności:**
```bash
npm install
pip install -r requirements.txt  # jeśli istnieje
```

3. **Skopiuj .env.example -> .env** (jeśli nie istnieje):
```bash
[ ! -f .env ] && cp .env.example .env && echo "Skopiowano .env.example -> .env"
```

4. **Uruchom bazy danych przez Docker Compose:**
```bash
docker compose up -d postgres redis
```

5. **Uruchom migracje:**
```bash
python manage.py migrate  # lub: npm run migrate
```

6. **Sprawdź czy wszystko działa:**
```bash
npm run health-check 2>/dev/null || python manage.py check
```

Zgłoś wynik każdego kroku. Na koniec podaj URL do lokalnej aplikacji.

Cykl życia skilla w kontekście

Ważna techniczna kwestia: skill który wywołasz zostaje w kontekście do końca sesji (lub do auto-kompresji). Warto to rozumieć żeby uniknąć niespodzianek:

• Skill NIE jest re-odczytywany w kolejnych turnach - załadowany skill to stały tekst w historii rozmowy
• Wszystkie wywołane skills dzielą budżet 25 000 tokenów - przy dużych skillach z wieloma dynamic injection możesz szybko go wyczerpać
• Przy auto-kompresji - pierwsze 5000 tokenów każdego skilla jest zachowywanych. Jeśli skill przestał „działać” po kompresji - wywołaj go ponownie przez /nazwa-skilla
• Pliki reference.md i inne pliki pomocnicze w katalogu skilla NIE ładują się automatycznie - skill musi je jawnie przywołać lub Claude musi je otworzyć. To celowe - pozwala mieć obszerne dokumentacje bez kosztu tokenów

Gdzie szukać gotowych skills - ekosystem

Nie musisz tworzyć wszystkiego od zera. Rośnie społeczność dzieląca się skills:

Typowe błędy i jak je naprawić

Skill nie pojawia się po wpisaniu /

# Sprawdź strukturę katalogów
ls -la .claude/skills/
# Każdy skill musi być w podkatalogu z SKILL.md
# OK   .claude/skills/fix-issue/SKILL.md
# ZLE  .claude/skills/fix-issue.md  (zły format)

# Sprawdź czy SKILL.md ma poprawny frontmatter
head -10 .claude/skills/fix-issue/SKILL.md
# Pierwsze znaki muszą być: ---

Skill uruchamia się zbyt często (lub wcale)

description: Pomaga z kodem.
Użyj gdy użytkownik pyta o kod.

description: Naprawia błędy z GitHub Issues.
Użyj gdy użytkownik podaje numer zgłoszenia,
pyta o konkretne zgłoszenie lub raport o błędzie.

Dynamic injection zwraca pusty wynik

# Sprawdź czy komenda działa poza Claude Code
gh pr diff 234   # czy gh jest zalogowane?
git log --oneline -5  # czy jesteś w repo?

# Skill z obsługą błędu:
### Diff PR:
!'gh pr diff $0 2>/dev/null || echo "Nie można pobrać diff. Sprawdź czy gh jest zalogowane."'

context: fork nie zwraca wyników

# Problem: pure reference docs nie mają "akcji" do wykonania
---
context: fork
---
# Dokumentacja API

Oto lista endpointów...  (Claude nie wie, co „zrobić” z tą informacją w forku)

# Rozwiązanie: dodaj konkretną akcję / pytanie
---
context: fork
agent: Explore
---
Zbadaj $ARGUMENTS w kodzie i odpowiedz na pytanie: jak to działa?
# teraz podagent ma konkretne zadanie do wykonania

Kiedy tworzyć skill, a kiedy nie

Quick start - stwórz pierwszy skill w 3 minutach

# 1. Utwórz katalog skills
mkdir -p .claude/skills/summarize-changes

# 2. Utwórz SKILL.md
cat > .claude/skills/summarize-changes/SKILL.md << 'EOF'
---
name: summarize-changes
description: Podsumowuje niezacommitowane zmiany. Użyj na koniec dnia pracy.
---

## Niezacommitowane zmiany:
!'git diff --stat HEAD 2>/dev/null || echo "Brak zmian"'

## Szczegóły:
!'git diff HEAD 2>/dev/null | head -100'

Napisz zwięzłe podsumowanie co zostało zrobione i zaproponuj commit message.
EOF

# 3. Gotowe! Wpisz w Claude Code:
/summarize-changes

Chcesz opanować Claude Code z trenerem?

Skills, hooks, podagenty, MCP i równoległe przepływy - w praktyce, na warsztacie z praktykiem JSystems. Szkolenie ma termin gwarantowany, więc odbędzie się na pewno.

Szkolenie Claude Code z terminem gwarantowanym -->

Podsumowanie

Skills to mechanizm który pozwala zamienić Claude Code z inteligentnego asystenta w dopasowane do Twojego projektu narzędzie z własnym zestawem komend. Kluczowe punkty do zapamiętania:

• Plik SKILL.md w katalogu .claude/skills/nazwa/ - nagłówek metadanych (frontmatter) w formacie YAML + treść w formacie Markdown
• Wywołanie: /nazwa-skilla [argumenty] lub automatyczne uruchomienie przez opis w polu description
• Wstrzykiwanie żywych danych - polecenie z terminala wykonuje się, a jego wynik trafia do skilla, zanim Claude go zobaczy
• Nazwane argumenty - arguments: [zmienna1, zmienna2] zamiast pozycyjnych $0, $1
• context: fork - izolowany podagent dla długich zadań analitycznych lub procesów wdrożeniowych
• disable-model-invocation: true - obowiązkowe dla skills wdrożeniowych, które nie mogą uruchomić się przez przypadek
• allowed-tools - narzędzia które nie pytają o zgodę gdy skill jest aktywny (np. Bash(git *))

Zacznij od jednego skilla - najlepiej takiego który rozwiązuje ból z którym spotykasz się codziennie. Reszta przyjdzie naturalnie.

✕