Claude Code Skills: własne rozszerzenia z automatyczną aktywacją

Jak zbudować własny skill dla Claude Code? Należy utworzyć plik SKILL.md w katalogu ~/.claude/skills/<name>/ (osobisty) lub .claude/skills/<name>/ (na poziomie projektu), z frontmatterem YAML zawierającym pola name, description i allowed-tools, a po nim treść w markdownie z opisem wiedzy eksperckiej. Na podstawie opisu Claude rozumowaniem LLM ocenia, czy skill pasuje do zadania, i aktywuje go automatycznie. Skille projektowe udostępniane przez git nie wymagają od współpracowników żadnej konfiguracji.

Trzy sesje z rzędu wklejałem do Claude Code tę samą listę kontrolną bezpieczeństwa. Zawierała ona charakterystyczne dla naszego zespołu wzorce podatności — kontrole IDOR wynikające z projektu naszego API, reguły obsługi sesji dla naszego przepływu uwierzytelniania, reguły ujawniania danych dla naszych pól z PII. Za każdym razem Claude stosował je bezbłędnie. Za każdym razem musiałem pamiętać, żeby je wkleić.

Moment, w którym łapiemy się na ponownym tłumaczeniu tego samego kontekstu, jest momentem, w którym warto zbudować skill.

TL;DR

Skille to rozszerzenia wywoływane przez model — Claude sam je odnajduje i stosuje zależnie od kontekstu, bez jawnego wywołania ¹. Kluczem do niezawodnego skilla jest pole description: to rozumowaniem LLM, a nie dopasowaniem słów kluczowych, Claude decyduje, kiedy uruchomić dany skill ¹. Skille warto budować dla wiedzy dziedzinowej, która przydaje się w wielu sesjach (wzorce bezpieczeństwa, styl kodu, reguły biznesowe). Nie warto ich budować do zadań jednorazowych — do tego służą polecenia slash.

Wymagania wstępne: znajomość systemu rozszerzeń Claude Code. Porównanie skilli, poleceń i subagentów znajdziesz w sekcji Skills w przewodniku.

Kiedy warto zbudować skill

Nie każdy powtarzany prompt zasługuje na skill. Ramy decyzyjne wyglądają tak:

Skille to wiedza, którą Claude ma zawsze pod ręką. Polecenia slash to akcje uruchamiane jawnie. Przy wyborze między nimi warto zadać sobie pytanie: „Czy Claude ma stosować to automatycznie, czy raczej sam chcę decydować, kiedy to uruchomić?”.

Częsty błąd: budowanie skilla do czegoś, co robi się raz w tygodniu. Zbudowałem kiedyś skill git-rebase-helper, który włączał się przy każdym prompcie związanym z git — przy rebase’ach, merge’ach, cherry-pickach, a nawet przy git status. Opis był zbyt ogólny, w 80 % sesji skill niepotrzebnie obciążał kontekst i rywalizował z innymi skillami o dwuprocentowy budżet kontekstu ¹. Rozwiązaniem okazało się usunięcie skilla i sięgnięcie po polecenie slash: /rebase, gdy naprawdę było potrzebne. Skille mają kodować stabilną wiedzę dziedzinową, a nie sporadyczne procedury.

Tutorial: budowa skilla do przeglądu kodu

Krok 1: utworzenie katalogu

Skille mogą znajdować się w czterech miejscach, od najszerszego do najwęższego zasięgu ¹:

Na potrzeby tego tutoriala utworzymy skill osobisty:

mkdir -p ~/.claude/skills/code-reviewer

Krok 2: napisanie pliku SKILL.md z frontmatterem

Każdy skill potrzebuje pliku SKILL.md złożonego z dwóch części: frontmattera YAML (między znacznikami ---), który mówi Claude’owi, kiedy użyć skilla, oraz treści w markdownie z instrukcjami, którymi Claude kieruje się po wywołaniu skilla ¹.

---
name: code-reviewer
description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.
allowed-tools: Read, Grep, Glob
---

# Code Review Expertise

## Security Checks
When reviewing code, verify:

### Input Validation
- All user input sanitized before database operations
- Parameterized queries (no string interpolation in SQL)
- Output encoding for rendered HTML content

### Authentication
- Session tokens validated on every protected endpoint
- Permission checks before data mutations
- No hardcoded credentials or API keys in source

### Data Exposure
- PII masked in log output and error messages
- API responses don't leak internal IDs or stack traces
- Sensitive fields excluded from serialization defaults

Warto zwrócić uwagę na allowed-tools: Read, Grep, Glob — to ogranicza skill do operacji tylko do odczytu. Recenzent kodu może przeglądać pliki, ale nie może ich zmieniać. Ograniczenia narzędzi zapobiegają niezamierzonym efektom ubocznym skilli.

Inne przydatne pola frontmattera, poza name, description i allowed-tools ¹:

Jedno zastrzeżenie z oficjalnej dokumentacji: context: fork „ma sens wyłącznie dla skilli z jawnymi instrukcjami, które zyskują na izolacji” ¹. Warto sięgać po nie w skillach analitycznych (przegląd kodu, audyt bezpieczeństwa), gdzie potrzebny jest czysty kontekst — a nie w skillach wiedzowych, które mają wtapiać się w główną rozmowę.

Krok 3: dodanie materiałów pomocniczych

Skille mogą odwoływać się do dodatkowych plików w tym samym katalogu ¹:

~/.claude/skills/code-reviewer/
├── SKILL.md                    # Required: frontmatter + core expertise
├── SECURITY_PATTERNS.md        # Referenced: detailed vulnerability patterns
└── PERFORMANCE_CHECKLIST.md    # Referenced: optimization guidelines

Odwołania z pliku SKILL.md tworzy się linkami względnymi:

See [SECURITY_PATTERNS.md](SECURITY_PATTERNS.md) for OWASP Top 10 checks.
See [PERFORMANCE_CHECKLIST.md](PERFORMANCE_CHECKLIST.md) for query optimization.

Gdy skill się aktywuje, Claude czyta te pliki na żądanie, korzystając ze standardowych narzędzi do odczytu plików ¹. Plik SKILL.md warto utrzymywać poniżej 500 wierszy, a szczegółowy materiał referencyjny przenosić do plików pomocniczych ³ — krótsze pliki skilli zmniejszają narzut wstrzykiwania kontekstu i pomagają Claude’owi skupić się na bieżącym zadaniu.

Krok 4: test aktywacji

Skill włącza się przy kolejnym uruchomieniu sesji Claude Code. Test wygląda tak:

# Ask Claude to review code — should trigger the skill automatically
claude "Review the authentication middleware in app/security/"

Załadowanie skilla można sprawdzić na dwa sposoby ¹:

# In an interactive session, ask Claude directly:
> What skills are available?

# Or check the context budget for excluded skills:
> /context

Jeśli skill się nie aktywuje, przyczyną prawie zawsze jest pole description. Zobacz krok 5.

Krok 5: krok kluczowy — napisanie opisu

Pole description to najważniejszy wiersz całego skilla. Pod maską dzieje się to: przy starcie sesji Claude Code wyciąga z każdego skilla pola name i description i wstrzykuje je do kontekstu Claude’a. Gdy wysyłasz wiadomość, o trafności skilla Claude rozstrzyga rozumowaniem modelu językowego — nie regeksem, nie dopasowaniem słów kluczowych, nie podobieństwem embeddingów. Oficjalna dokumentacja mówi: „Claude porównuje zadanie z opisami skilli, aby zdecydować, które są istotne. Jeśli opisy są ogólnikowe lub się pokrywają, Claude może wczytać niewłaściwy skill — albo pominąć ten, który by pomógł” ¹.

Niezależna analiza kodu źródłowego Claude Code potwierdza ten mechanizm: opisy skilli trafiają do sekcji available_skills w promptcie systemowym, a model wybiera pasujące skille w chwili wywołania, zwykłym rozumieniem języka ⁴. Dopasowanie oparte na LLM ma istotne konsekwencje dla tego, jak pisać opisy.

Zły opis:

description: Helps with code

Claude nie ma pojęcia, kiedy to uruchomić. „Helps with code” pasuje do wszystkiego i do niczego — a skoro dopasowanie opiera się na rozumowaniu LLM, ogólnikowe opisy dają nieprzewidywalną aktywację.

Lepszy opis:

description: Review code for bugs and issues

Wciąż zbyt ogólny. Jakie błędy? Jakie problemy? Kiedy Claude ma sięgnąć po to zamiast po własną, wbudowaną analizę?

Skuteczny opis:

description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.

Ten opis działa, bo zawiera: - Co robi: przegląd kodu pod kątem konkretnych rodzajów problemów - Kiedy go użyć: przy analizie zmian, PR-ów i jakości kodu - Frazy wyzwalające: review, audit, check — słowa, które użytkownik wpisuje naturalnie

Jedno ograniczenie, o którym trzeba wiedzieć: wszystkie opisy skilli dzielą wspólny budżet kontekstu, który „skaluje się dynamicznie do 2 % okna kontekstu, z wartością zapasową 16 000 znaków” ¹. Przy wielu skillach każdy opis warto trzymać zwięźle — rozwlekły opis odbiera miejsce pozostałym. Budżet można nadpisać zmienną środowiskową SLASH_COMMAND_TOOL_CHAR_BUDGET ², ale lepszym rozwiązaniem są krótsze i precyzyjniejsze opisy.

Warto testować różne opisy. Wystarczy otworzyć świeżą sesję, poprosić Claude’a o przegląd kodu i sprawdzić, czy skill się włącza. Jeśli nie — trzeba dodać kolejne frazy wyzwalające. Jeśli włącza się wtedy, gdy nie powinien — opis wymaga uszczegółowienia.

Krok 6: iteracja na podstawie użycia

Po tygodniu korzystania okaże się, gdzie są luki: - Wzorce, które skill powinien sprawdzać, a tego nie robi — trzeba dopisać je do SKILL.md - Fałszywe aktywacje przy niezwiązanych zadaniach — należy zawęzić opis albo dodać disable-model-invocation: true i wymagać jawnego wywołania /code-reviewer - Brakujący kontekst — warto dołożyć pliki z materiałami pomocniczymi - Zbyt ciasne lub zbyt luźne ograniczenia narzędzi — trzeba dostroić allowed-tools

Skille są dokumentami żywymi. Pierwsza wersja nigdy nie jest ostatnią.

Zaawansowane: skille jako biblioteka promptów

Poza pojedynczymi skillami o jednym przeznaczeniu ta struktura katalogów sprawdza się jako uporządkowana biblioteka promptów:

~/.claude/skills/
├── code-reviewer/          # Activates on: review, audit, check
├── api-designer/           # Activates on: design API, endpoint, schema
├── sql-analyst/            # Activates on: query, database, migration
├── deploy-checker/         # Activates on: deploy, release, production
└── incident-responder/     # Activates on: error, failure, outage, debug

Każdy skill koduje inną część wiedzy zespołu. Razem tworzą bazę wiedzy, z której Claude czerpie automatycznie, zależnie od kontekstu. Młodszy programista dostaje wskazówki na poziomie seniora, nawet o nie nie prosząc.

Uwaga o liczbie skilli: im więcej skilli, tym więcej opisów rywalizuje o budżet kontekstu ¹. Jeśli skille przestają się włączać, warto uruchomić /context i sprawdzić, czy któryś nie został pominięty. Lepiej mieć kilka dobrze opisanych skilli niż wiele ogólnikowych.

Udostępnianie skilli zespołowi

Skille osobiste (~/.claude/skills/) należą wyłącznie do Ciebie. Nadają się do osobistych preferencji, eksperymentalnych wzorców i wiedzy właściwej tylko dla Twojego sposobu pracy.

Skille projektowe (.claude/skills/ w katalogu głównym repozytorium) udostępnia się przez git ¹:

# Create project-level skill
mkdir -p .claude/skills/domain-expert
# ... write SKILL.md ...

# Commit and push
git add .claude/skills/
git commit -m "feat: add domain-expert skill for payment processing rules"
git push

Gdy współpracownicy zrobią pull, otrzymują skill automatycznie. Bez instalacji, bez konfiguracji. Dystrybucja przez git to najskuteczniejszy sposób ujednolicenia wiedzy w zespole.

Wskazówki dla skilli współdzielonych: - Skille projektowe warto ograniczać do wiedzy dziedzinowej (reguły biznesowe, wzorce architektoniczne) - Skille osobiste warto zostawić dla preferencji roboczych (formatowanie, styl commitów) - W komentarzu na początku pliku SKILL.md warto udokumentować, po co ten skill powstał - Zmiany w skillach należy recenzować w PR-ach jak każdy inny kod

Najważniejsze wnioski

• Skill warto zbudować w chwili, gdy łapiesz się na ponownym tłumaczeniu kontekstu. Jeśli wklejasz tę samą listę kontrolną trzeci raz, powinna być skillem.
• Pole description przesądza o wszystkim. Claude dopasowuje zapytania do opisów rozumowaniem LLM ¹. W opis warto włożyć więcej pracy niż w samą treść skilla.
• Efekty uboczne warto ograniczać przez allowed-tools. Skille tylko do odczytu powinny być zawężone do Read, Grep, Glob.
• Skille projektowe warto udostępniać przez git. Dystrybucja wiedzy w zespole bez żadnej konfiguracji ¹.
• Nie należy przesadzać z abstrakcją. Skill do każdego mikrowzorca tworzy koszt utrzymania i zjada budżet kontekstu. Skille warto budować dla wiedzy stabilnej, wielokrotnego użytku i na tyle cennej, by opłacało się ją utrzymywać.

Często zadawane pytania

Czym są skille w Claude Code?

Skille to rozszerzenia wywoływane przez model, przechowywane jako pliki markdown, które Claude sam odnajduje i stosuje zależnie od kontekstu. W odróżnieniu od poleceń slash, uruchamianych jawnie, skill włącza się wtedy, gdy rozumowanie LLM Claude’a rozpozna, że bieżące zadanie pasuje do opisu skilla. Skille kodują wiedzę dziedzinową — wzorce bezpieczeństwa, reguły stylu kodu, logikę biznesową — która przetrwa między sesjami i nie wymaga tłumaczenia kontekstu za każdym razem.

Jak utworzyć własny skill dla Claude Code?

Należy utworzyć katalog w ~/.claude/skills/<name>/ dla skilli osobistych albo w .claude/skills/<name>/ dla skilli projektowych. W środku trzeba umieścić plik SKILL.md z frontmatterem YAML (zawierającym name, description, a opcjonalnie allowed-tools), a po nim treść w markdownie z wiedzą, którą Claude ma stosować. Pole description jest kluczowe — to na jego podstawie Claude rozumowaniem LLM decyduje, kiedy włączyć skill. Pełny opis krok po kroku znajdziesz w tutorialu powyżej.

Czym różnią się skille Claude Code od poleceń slash?

Skille włączają się same, zależnie od kontekstu — o ich trafności Claude rozstrzyga rozumowaniem LLM na podstawie opisu skilla. Polecenia slash to akcje wywoływane przez użytkownika, uruchamiane jawnie wpisaniem /command-name. Skill warto zbudować wtedy, gdy Claude ma mieć tę wiedzę stale pod ręką (wiedza dziedzinowa, standardy jakości). Polecenie slash sprawdzi się wtedy, gdy sam chcesz decydować o momencie uruchomienia akcji (skrypty wdrożeniowe, jednorazowe procedury).

Czy skille Claude Code mogą wywoływać inne narzędzia?

Tak, ale to Ty decydujesz które, przez pole allowed-tools we frontmatterze. Skill tylko do odczytu, taki jak recenzent kodu, warto zawęzić do Read, Grep, Glob, żeby wykluczyć niezamierzone efekty uboczne. Gdy pole allowed-tools zostanie pominięte, skill może korzystać z każdego narzędzia dostępnego dla Claude’a. Skille mogą też definiować we frontmatterze własne hooki, aktywne wyłącznie w czasie działania skilla.

Dlaczego mój skill w Claude Code się nie aktywuje?

Najczęstszą przyczyną jest ogólnikowe lub zbyt szerokie pole description. O tym, czy skill pasuje do bieżącego zadania, Claude rozstrzyga rozumowaniem LLM, a nie dopasowaniem słów kluczowych. Jeśli w opisie widnieje „helps with code”, Claude nie odróżni tego przypadku od dowolnego innego zadania programistycznego. Opis musi być konkretny: powinien nazywać dokładne rodzaje problemów, scenariusze wyzwalające i czasowniki, które użytkownicy wpisują naturalnie. Warto też sprawdzić /context w sesji, czy skill nie został pominięty przez dwuprocentowy limit budżetu kontekstu. Gdy o miejsce rywalizuje wiele skilli, część z nich wypada.

Gdzie przechowywane są skille Claude Code i jak się je udostępnia?

Skille mieszkają w czterech miejscach o rosnącym zasięgu: osobistym (~/.claude/skills/<name>/SKILL.md), projektowym (.claude/skills/<name>/SKILL.md), pluginowym oraz firmowym (ustawienia zarządzane). Skille osobiste obowiązują we wszystkich Twoich projektach. Skille projektowe udostępnia się przez git — gdy współpracownicy zrobią pull, dostają skill automatycznie i bez żadnej konfiguracji. Wszystkie opisy skilli dzielą budżet kontekstu równy 2 % okna kontekstu, więc przy wielu skillach opisy warto trzymać zwięźle.

Źródła