Pisanie własnych skilli w Claude Code

W poprzednim poście o skill'ach pisałem które warto mieć. Teraz pokażę jak napisać własny od zera. Spoiler: to plik markdown z frontmatter. Nic więcej.

Czym jest skill

Skill to definicja slash commanda (/moja-akcja). Składa się z:

nazwy
opisu (kiedy go odpalać)
system prompta dla agenta gdy go odpalisz
opcjonalnie: tools whitelist, model override, scripts

Plik leży w ~/.claude/skills/{name}.md (globalnie) albo w .claude/skills/{name}.md (per-projekt).

Anatomia skilla

Minimalny przykład:

---
name: zarchiwizuj-tydzien
description: Archiwizuj wszystkie zamknięte taski Vikunja z ostatniego tygodnia
allowed-tools:
  - mcp__vikunja__*
---
 
Twoim zadaniem jest:
1. Zlokalizować wszystkie taski w statusie "done" zamknięte w ostatnich 7 dniach
2. Dla każdego — ustawić label "archived" i przesunąć do projektu "Archive"
3. Wyświetlić podsumowanie: ile, w jakich projektach
 
Nie usuwaj żadnych tasków. Nigdy.

/zarchiwizuj-tydzien w terminalu uruchamia ten prompt z whitelist tylko Vikunja MCP. Bezpieczne i wąskie.

Skill #1: code review konkretnego pliku

---
name: review-plik
description: Code review konkretnego pliku, fokus na readability i error handling
arguments:
  - name: plik
    description: Ścieżka do pliku do reviewu
    required: true
---
 
Przeczytaj plik {{plik}} i wykonaj review patrząc na:
 
1. **Czytelność**: nazwy zmiennych, długość funkcji, struktura
2. **Error handling**: czy są silent failures, czy błędy są propagowane
3. **Bezpieczeństwo**: SQL injection, command injection, XSS
4. **Konsystencja**: czy pasuje do reszty repo
 
Pisz krótko. Każdy issue z linijką (path:line). Nie sugeruj "drobiazgów" stylu — to robi linter.

Użycie: /review-plik src/auth/login.ts. Dostaję uporządkowany feedback w 30 sekund.

Skill #2: szybki commit

---
name: szybki-commit
description: Zacommituj wszystkie zmiany z auto-generowanym message
allowed-tools:
  - Bash
---
 
1. Uruchom `git status` i `git diff --cached` (po add'zie)
2. Wygeneruj zwięzły, opisowy commit message (max 72 znaki tytuł, body opcjonalne)
3. Zacommituj BEZ pytania o potwierdzenie wiadomości
4. Zwróć tylko hash i message
 
Format message: `<type>: <opis>`
Typy: feat, fix, refactor, docs, chore, style, test

/szybki-commit po edycji = jeden klawisz, commit gotowy.

Skill #3: deploy demo

---
name: deploy-demo
description: Zbuduj i zdeployuj demo na forge PC
arguments:
  - name: slug
    description: Slug demo (folder name)
    required: true
allowed-tools:
  - Bash
---
 
Wykonaj kolejno:
 
1. SSH do forge: `ssh [email protected]`
2. `cd /home/kkaletka/demo-{{slug}}`
3. `docker compose up -d --build`
4. Sprawdź `curl localhost:$(cat .port)` — powinno zwrócić 200
5. Update Cloudflare ingress jeśli nowa subdomena
6. Telegram notify gdy gotowe
 
Jeśli któryś krok padnie — STOP, raportuj błąd, nie kontynuuj.

/deploy-demo misiura zamiast 6 manualnych komend.

Pułapki przy pisaniu skilli

1. Za szeroka description. Jeśli description brzmi "wykonuj różne zadania", agent będzie odpalał skill na wszystko. Reguła: opis = jeden konkretny scenariusz.

2. Brak allowed-tools. Domyślnie skill ma dostęp do wszystkich narzędzi. Dla skilla "uporządkuj taski" nie ma powodu żeby miał Bash ani edycję plików. Whitelist'uj minimalnie.

3. Założenie że agent pamięta kontekst. Skill startuje świeżą sesję. Wszystko czego potrzebuje, musi być w prompcie albo agent sam to zbierze. "Zachowaj poprzedni stan" nie działa.

4. Argumenty bez walidacji. Jeśli skill bierze slug jako argument i go używa w bashu, agent może wpuścić tam command injection. Zawsze pisz w prompcie " musi pasować do regex [a-z0-9-]+, jeśli nie, odrzuć".

Gdzie umieszczać

Globalne (~/.claude/skills/): skille uniwersalne, review, commit, deploy template'owy
Per-projekt (.claude/skills/): specyficzne dla projektu, /deploy-blog, /run-tests-watch

Per-projekt jest częściej lepsze. Dzielisz się skillami z projektem (commit do repo), nikt nie musi konfigurować ręcznie.

Co mam u siebie

Aktualnie ~12 skilli aktywnych. Najczęściej używane:

/szybki-commit
/review-plik
/deploy-demo
/zarchiwizuj-tydzien
/audit-deps (npm audit + pip-audit z agregacją)

Każdy < 50 linii markdown. Razem to ~500 linii i daje mi może 3 godziny tygodniowo.

Skill to najtańszy mechanizm rozszerzania Claude Code. Plik markdown, kilka minut. Jeśli powtarzasz coś częściej niż 3 razy w tygodniu, napisz skill. Próg wejścia jest tak niski że wymówka "nie mam czasu" nie obroni się.