Tworzenie własnych umiejętności dla Claude Code: Kompletny poradnik

Trzy sesje z rzędu wklejałem tę samą listę kontrolną bezpieczeństwa do Claude Code. Lista zawierała specyficzne wzorce podatności naszego zespołu — kontrole IDOR unikalne dla naszego projektu API, zasady obsługi sesji dla naszego procesu uwierzytelniania, reguły ekspozycji danych dla naszych pól 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 przyłapujesz się na ponownym wyjaśnianiu tego samego kontekstu, to moment, w którym warto zbudować umiejętność.

TL;DR

Umiejętności to rozszerzenia wywoływane przez model — Claude odkrywa je i stosuje automatycznie na podstawie kontekstu, bez konieczności jawnego wywoływania ¹. Kluczem do niezawodnych umiejętności jest pole description: Claude używa rozumowania LLM (nie dopasowywania słów kluczowych), aby zdecydować, kiedy aktywować daną umiejętność ¹. Umiejętności warto tworzyć dla wiedzy domenowej, która ma zastosowanie między sesjami (wzorce bezpieczeństwa, styl kodu, reguły biznesowe). Nie należy tworzyć umiejętności dla jednorazowych zadań — zamiast tego lepiej użyć poleceń slash.

Wymagania wstępne: Znajomość systemu rozszerzeń Claude Code. Porównanie umiejętności, poleceń i subagentów znajduje się w sekcji dotyczącej umiejętności w przewodniku.

Kiedy tworzyć umiejętność

Nie każdy powtarzany prompt zasługuje na umiejętność. Schemat decyzyjny:

Umiejętności służą do wiedzy, którą Claude zawsze ma pod ręką. Polecenia slash służą do akcji, które jawnie wyzwalasz. Przy wyborze między nimi warto zadać sobie pytanie: „Czy Claude powinien stosować to automatycznie, czy to ja powinienem decydować, kiedy to uruchomić?”

Częsty błąd: tworzenie umiejętności dla czegoś, co robi się raz w tygodniu. Zbudowałem umiejętność git-rebase-helper, która aktywowała się przy każdym prompcie związanym z gitem — rebase’ach, merge’ach, cherry-pickach, nawet git status. Opis był zbyt szeroki, zaśmiecała kontekst w 80% sesji, gdzie nie była potrzebna, i konkurowała z innymi umiejętnościami o 2% budżetu kontekstu ¹. Rozwiązaniem było usunięcie umiejętności i użycie zamiast niej polecenia slash: /rebase, kiedy faktycznie tego potrzebowałem. Umiejętności powinny kodować stabilną wiedzę domenową, a nie okazjonalne procesy.

Poradnik: Zbuduj umiejętność code review

Krok 1: Utwórz katalog

Umiejętności mogą znajdować się w czterech lokalizacjach, od najszerszego do najwęższego zakresu ¹:

W tym poradniku tworzymy umiejętność osobistą:

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

Krok 2: Napisz SKILL.md z frontmatterem

Każda umiejętność wymaga pliku SKILL.md składającego się z dwóch części: frontmatter YAML (między znacznikami ---), który mówi Claude, kiedy używać umiejętności, oraz treść markdown z instrukcjami, które Claude stosuje, gdy umiejętność zostanie wywołana ¹.

---
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

Uwaga: allowed-tools: Read, Grep, Glob — to ogranicza umiejętność do operacji tylko do odczytu. Recenzent kodu może przeglądać pliki, ale nie może ich modyfikować. Ograniczenia narzędzi zapobiegają niezamierzonym efektom ubocznym umiejętności.

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

Jedno zastrzeżenie z oficjalnej dokumentacji: context: fork „ma sens tylko dla umiejętności z jawnymi instrukcjami, które korzystają z izolacji” ¹. Należy go używać w umiejętnościach analitycznych (code review, audyt bezpieczeństwa), gdzie potrzebny jest czysty kontekst, a nie w umiejętnościach wiedzy, które powinny wkomponować się w główną konwersację.

Krok 3: Dodaj zasoby wspierające

Umiejętności 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

Można się do nich odwołać z SKILL.md za pomocą względnych linków:

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

Claude odczytuje te pliki na żądanie, gdy umiejętność się aktywuje, używając standardowych narzędzi do odczytu plików ¹. Plik SKILL.md powinien mieć poniżej 500 linii, a szczegółowe materiały referencyjne warto przenieść do plików wspierających ³ — krótsze pliki umiejętności zmniejszają narzut wstrzykiwania kontekstu i pozwalają Claude skupić się na bieżącym zadaniu.

Krok 4: Przetestuj aktywację

Umiejętność aktywuje się przy następnym uruchomieniu sesji Claude Code. Aby ją przetestować:

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

Można zweryfikować załadowanie umiejętności jedną z dwóch metod ¹:

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

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

Jeśli umiejętność się nie aktywuje, problem prawie zawsze tkwi w polu description. Patrz krok 5.

Krok 5: Kluczowy krok — pisanie opisu

Pole description to najważniejsza linia w umiejętności. Oto co dzieje się pod spodem: na początku sesji Claude Code wyodrębnia name i description każdej umiejętności i wstrzykuje je do kontekstu Claude. Gdy wysyłasz wiadomość, Claude używa rozumowania modelu językowego — nie wyrażeń regularnych, nie dopasowywania słów kluczowych, nie podobieństwa embeddingów — aby zdecydować, czy jakakolwiek umiejętność jest istotna. Oficjalna dokumentacja stwierdza: „Claude dopasowuje zadanie do opisów umiejętności, aby zdecydować, które są istotne. Jeśli opisy są niejasne lub się nakładają, Claude może załadować niewłaściwą umiejętność — lub pominąć tę, która by pomogła” ¹.

Niezależna analiza kodu źródłowego Claude Code potwierdza ten mechanizm: opisy umiejętności są wstrzykiwane do sekcji available_skills promptu systemowego, a model wykorzystuje standardowe rozumienie języka do wyboru odpowiednich umiejętności w momencie wywołania ⁴. Dopasowywanie oparte na LLM ma istotne konsekwencje dla sposobu pisania opisów.

Zły opis:

description: Helps with code

Claude nie wie, kiedy to aktywować. „Helps with code” pasuje do wszystkiego i do niczego — a ponieważ dopasowywanie opiera się na rozumowaniu LLM, niejasne opisy tworzą nieprzewidywalną aktywację.

Lepszy opis:

description: Review code for bugs and issues

Zbyt ogólnikowy. Jakie błędy? Jakie problemy? Kiedy Claude powinien użyć tego zamiast wbudowanej analizy?

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.

Skuteczny opis działa, ponieważ zawiera: - Co robi: Przegląd kodu pod kątem konkretnych typów problemów - Kiedy używać: Przeglądanie zmian, PR-ów, analiza jakości - Frazy wyzwalające: review, audit, check — słowa, które użytkownik naturalnie wpisuje

Jedno ograniczenie, które warto znać: wszystkie opisy umiejętności dzielą budżet kontekstu, który „skaluje się dynamicznie na poziomie 2% okna kontekstu, z rezerwą 16 000 znaków” ¹. Przy wielu umiejętnościach każdy opis powinien być zwięzły — rozwlekły opis konkuruje z innymi umiejętnościami o ograniczoną przestrzeń. Budżet można nadpisać za pomocą zmiennej środowiskowej SLASH_COMMAND_TOOL_CHAR_BUDGET ², ale lepszym rozwiązaniem są krótsze, bardziej precyzyjne opisy.

Testuj różne opisy. Rozpocznij nową sesję, poproś Claude o przegląd kodu i sprawdź, czy umiejętność się aktywuje. Jeśli nie, dodaj więcej fraz wyzwalających. Jeśli aktywuje się, gdy nie powinna, sprecyzuj opis.

Krok 6: Iteruj na podstawie użycia

Po tygodniu korzystania odkryjesz: - Wzorce, które umiejętność powinna sprawdzać, ale tego nie robi — dodaj je do SKILL.md - Fałszywe aktywacje przy niezwiązanych zadaniach — doprecyzuj opis lub dodaj disable-model-invocation: true i wymagaj jawnego wywołania /code-reviewer - Brakujący kontekst — dodaj pliki zasobów wspierających - Zbyt ciasne lub zbyt luźne ograniczenia narzędzi — dostosuj allowed-tools

Umiejętności to żywe dokumenty. Pierwsza wersja nigdy nie jest wersją ostateczną.

Zaawansowane: Umiejętności jako biblioteka promptów

Oprócz umiejętności jednocelowych, struktura katalogów działa jako zorganizowana 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żda umiejętność koduje inny aspekt wiedzy zespołu. Razem tworzą bazę wiedzy, z której Claude automatycznie czerpie na podstawie kontekstu. Młodszy programista otrzymuje wskazówki na poziomie seniora bez konieczności proszenia o nie.

Uwaga dotycząca liczby umiejętności: Więcej umiejętności oznacza więcej opisów konkurujących o budżet kontekstu ¹. Jeśli zauważysz, że umiejętności się nie aktywują, uruchom /context, aby sprawdzić, czy któreś nie są wykluczane. Lepiej mieć mniej dobrze opisanych umiejętności niż wiele niejasnych.

Udostępnianie umiejętności zespołowi

Umiejętności osobiste (~/.claude/skills/) są prywatne. Można ich używać do osobistych preferencji, eksperymentalnych wzorców lub wiedzy specyficznej dla własnego procesu pracy.

Umiejętności projektowe (.claude/skills/ w katalogu głównym repozytorium) są współdzielone 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

Kiedy członkowie zespołu pobiorą zmiany, automatycznie otrzymają umiejętność. Bez instalacji, bez konfiguracji. Dystrybucja przez git to najskuteczniejszy sposób na standaryzację wiedzy w zespole.

Wskazówki dotyczące współdzielonych umiejętności: - Umiejętności projektowe powinny skupiać się na wiedzy domenowej (reguły biznesowe, wzorce architektoniczne) - Umiejętności osobiste powinny dotyczyć preferencji procesowych (formatowanie, styl commitów) - Na początku SKILL.md warto udokumentować, dlaczego umiejętność istnieje - Zmiany w umiejętnościach powinny być przeglądane w PR-ach jak każdy inny kod

Kluczowe wnioski

• Zbuduj umiejętność, gdy przyłapiesz się na ponownym wyjaśnianiu kontekstu. Jeśli wklejasz tę samą listę kontrolną trzy razy, powinna stać się umiejętnością.
• Pole description decyduje o wszystkim. Claude używa rozumowania LLM, aby dopasować żądania do opisów ¹. Warto poświęcić więcej czasu na opis niż na treść umiejętności.
• Używaj allowed-tools, aby ograniczyć efekty uboczne. Umiejętności tylko do odczytu powinny być ograniczone do Read, Grep, Glob.
• Udostępniaj umiejętności projektowe przez git. Dystrybucja wiedzy zespołowej bez żadnej konfiguracji ¹.
• Nie przesadzaj z abstrakcją. Umiejętność dla każdego mikrowzorca tworzy obciążenie utrzymaniowe i konkuruje o budżet kontekstu. Umiejętności warto tworzyć dla wiedzy, która jest stabilna, wielokrotnego użytku i wystarczająco wartościowa, aby ją utrzymywać.

Źródła