Custom Claude Code skills — kompletny tutorial krok po kroku

Skills w Claude Code 2.x to lekki mechanizm pakowania wielokrotnie używanych workflow w jeden plik markdown z front-matterem. Nie wymaga MCP, nie wymaga sub-agenta — to po prostu szablon, który Claude "wie, jak wykonać". W tym tutorialu pokażemy, jak zbudować custom skill od zera, jak go testować i jak dzielić w zespole. Z gotowym przykładem skilla do code review PHP.

Czym jest skill, a czym nie jest

Skill to plik .md z metadanymi (frontmatter) opisujący zadanie i sposób jego wykonania. Claude czyta dostępne skille przy starcie sesji i wybiera odpowiedni na podstawie pola description. To nie to samo co:

• Sub-agent — osobna instancja modelu z własnym kontekstem
• MCP server — zewnętrzny proces dostarczający tools/resources
• Slash command — krótka komenda do wywoływania ręcznego

Skill jest "thin abstraction" — opis tego, jak parent-agent ma się zachować w danej sytuacji. Tani, prosty, łatwy do współdzielenia.

Anatomia skilla

---
name: php-code-review
description: |
  Wywołaj mnie, gdy uzytkownik prosi o code review pliku PHP.
  Stosuje sie do projektow uzywajacych raw PDO + PSR-12.
allowed_tools: [Read, Grep, Bash]
---

# Skill: PHP Code Review

## Krok 1
Przeczytaj plik wskazany przez uzytkownika narzedziem Read.

## Krok 2
Sprawdz nastepujace klasy bledow:
1. SQL injection — wszystkie zapytania musza uzywac prepared statements
2. CSRF — kazdy POST handler musi miec csrf_check()
3. PSR-12 — wciecia 4 spacje, nazwy zmiennych snake_case
4. Helpers — czy nie reimplementuje funkcji z helpers.php

## Krok 3
Zwroc raport w formacie:

```
## BLOKUJACE (X)
- [line N] opis problemu + sugestia fix

## OSTRZEZENIA (X)
- [line N] opis

## SUGESTIE (X)
- [line N] opis
```

## Krok 4
Jezeli zero BLOKUJACYCH — zaproponuj git add + commit message po polsku.

Gdzie umieścić skill

Trzy lokalizacje, w kolejności priorytetu:

1. .claude/skills/<name>.md — repo-level, commitujemy do repo
2. ~/.claude/skills/<name>.md — user-level, dla jednego dewelopera
3. /etc/claude/skills/<name>.md — system-level (rzadko)

Dla zespołów najlepsza opcja to repo-level — wchodzi w PR-y, jest review'owana razem z kodem.

Testowanie skilla

Najlepiej testować z konkretnym promptem, który zwykle wywołuje dany skill. Cykl:

1. Napisz skill
2. Zrestartuj sesję Claude Code (skille ładują się przy starcie)
3. Wprowadź typowy prompt
4. Sprawdź, czy Claude poprawnie wybrał skill (transcript pokazuje "Using skill: ...")
5. Iteruj opis i kroki

Najczęstsze błędy

• Zbyt szeroki description — skill odpala się "wszędzie", przeszkadza w normalnej pracy.
• Zbyt długie kroki — powyżej 12 punktów Claude gubi konsystencję. Lepiej rozbić na 2 skille.
• Brak przykładów outputu — bez fragmentu "zwróć w formacie X" wyniki są nierówne.
• Tools niezgodne z zadaniem — np. allowed_tools bez Bash, a w krokach prosimy o uruchomienie testów.

Skille produkcyjne w naszych projektach

Następny krok

Mamy pakiet 11 gotowych skilli dla projektów PHP/MySQL — wrzucamy do repo klienta jako część wdrożenia. Umówmy się — pokażemy działający setup w 30 minut.