Claude Code skills: czym są i jak dodać własną umiejętność

• Na pierwszą umiejętność proponuję jedno zadanie: wyjaśnianie wskazanego pliku.
• Zapisz, co Claude ma zrobić i jak ma wyglądać odpowiedź.
• Sprawdź osobno wywołanie poleceniem oraz dobór umiejętności do zwykłego pytania.
• Oceniaj odpowiedź według zapisanych wymagań, zamiast poprzestawać na sprawdzeniu, czy polecenie działa.

Umiejętność może zawierać instrukcje i dodatkowe materiały. Według specyfikacji Agent Skills podstawą jest SKILL.md, a opcjonalne katalogi scripts/, references/ i assets/ służą odpowiednio do przechowywania skryptów, dokumentacji oraz zasobów, takich jak szablony. Skrypt to plik z poleceniami wykonywanymi przez program.

Claude poznaje nazwę i opis umiejętności, a pełne instrukcje wczytuje, gdy umiejętność staje się potrzebna. Takie stopniowe wczytywanie opisuje dokumentacja Anthropic. Opis pomaga więc rozpoznać zadanie, a dalsza treść określa sposób jego wykonania.

Schemat pokazuje wariant, w którym Claude sam dobiera umiejętność:

flowchart TD
    A[Prosisz o wyjaśnienie kodu] --> B[Claude sprawdza opisy]
    B --> C[Dobiera umiejętność]
    C --> D[Wczytuje SKILL.md]
    D --> E[Przygotowuje odpowiedź]

Proponuję zapisywać w umiejętnościach powtarzalne procedury: sposób wyjaśniania funkcji, sprawdzania zmian albo przygotowywania dokumentacji. Funkcja to nazwany fragment kodu wykonujący określone zadanie.

Stałe informacje o projekcie mają inne miejsce. Plik CLAUDE.md przekazuje Claude trwałe instrukcje, na przykład konwencje nazewnictwa i polecenia budowania projektu. Anthropic zaleca przenoszenie wieloetapowych procedur do umiejętności. Przykładowo informację „projekt używa Pythona” zostaw w instrukcjach projektu, a procedurę „wyjaśnij plik według ustalonego schematu” zapisz jako skill.

Claude Code obsługuje umiejętności osobiste i projektowe zapisane w lokalnych katalogach. W tabeli nazwa oznacza wybraną nazwę katalogu umiejętności.

Znak ~ oznacza katalog domowy użytkownika. Ścieżka zaczynająca się od .claude/ jest tutaj liczona od folderu projektu. Do ćwiczenia wybierzemy wariant osobisty.

Przykład przygotowano dla terminala Bash w Ubuntu 24.04 LTS. Terminal to okno do wpisywania poleceń, a Bash jest programem, który je interpretuje. Claude Code obsługuje Ubuntu od wersji 20.04 i wymaga połączenia z internetem.

Przygotuj:

• zainstalowany Claude Code i działające logowanie;
• folder projektu otwarty w terminalu;
• edytor tekstu, w którym zapiszesz pliki.

Instalację opisuje osobny poradnik Claude Code dla Windows, macOS i Linux. Jeśli pracujesz w Windows i chcesz korzystać ze środowiska Linux, skorzystaj z instrukcji WSL, czyli mechanizmu uruchamiania środowiska Linux w Windows.

W folderze projektu sprawdź instalację:

claude --version

Zgodnie z instrukcją uruchomienia Claude Code powinien pojawić się numer wersji. Jeśli terminal zgłasza command not found, wróć do poradnika instalacji przed dalszymi krokami.

1. Przygotuj plik do ćwiczenia

Zaczniemy od krótkiego programu w Pythonie, czyli języku programowania. Nie musisz go uruchamiać, aby poprosić Claude o wyjaśnienie. Jeśli plik o tej nazwie już istnieje, zachowaj jego zawartość i wybierz inną nazwę do ćwiczenia.

Utwórz w folderze projektu plik przyklad.py:

def cena_po_rabacie(cena, rabat_procent):
    return cena * (1 - rabat_procent / 100)

wynik = cena_po_rabacie(80, 15)
print(wynik)

Ten przykład pozwoli ocenić, czy odpowiedź wyjaśnia parametry funkcji, obliczenie rabatu oraz przekazanie wyniku do print.

2. Utwórz katalog umiejętności

Dokumentacja tworzenia pierwszej umiejętności prowadzi przez utworzenie katalogu, zapisanie SKILL.md i sprawdzenie wywołania. W terminalu, nadal z folderu projektu, wpisz:

mkdir -p ~/.claude/skills/wyjasnij-kod

Polecenie tworzy potrzebne katalogi. Nie usuwa plików ani nie nadpisuje ich zawartości; jeśli katalog już istnieje, pozostawia go na miejscu. Przy poprawnym wykonaniu zwykle nie zobaczysz komunikatu.

3. Zapisz kompletne instrukcje

SKILL.md zaczyna się nagłówkiem YAML, czyli danymi zapisanymi jako pola i wartości między znacznikami ---. Dalej umieszcza się instrukcje w Markdown, prostym formacie tekstowym z nagłówkami i listami. Taki układ pliku określa specyfikacja Agent Skills.

W edytorze utwórz plik ~/.claude/skills/wyjasnij-kod/SKILL.md:

---
name: wyjasnij-kod
description: Wyjaśnia kod początkującym po polsku. Stosowana, gdy użytkownik prosi o wyjaśnienie pliku, funkcji lub przepływu danych.
---

## Zadanie

Wyjaśnij wskazany kod osobie rozpoczynającej naukę programowania.
Plik lub pytanie użytkownika: $ARGUMENTS

## Zasady

1. Jeśli nie wskazano kodu ani pliku, poproś o jego wskazanie.
2. Przeczytaj wskazany plik. Jeśli go nie ma, podaj ten problem.
3. Nie zmieniaj plików i nie uruchamiaj poleceń.
4. Odpowiadaj po polsku. Wyjaśniaj terminy przy pierwszym użyciu.
5. Oddziel informacje wynikające z kodu od przypuszczeń.

## Format odpowiedzi

- Cel: jedno zdanie o tym, co robi kod.
- Przebieg: numerowane kroki od danych wejściowych do wyniku.
- Przykład: konkretne dane wejściowe i wynik wynikający z kodu.
- Do sprawdzenia: miejsca, których nie można potwierdzić z pliku.
- Ćwiczenie: jedno pytanie pomagające zrozumieć kod.

name określa nazwę, a description opisuje zadanie i sytuację użycia. Zapis $ARGUMENTS jest zastępowany tekstem podanym po nazwie umiejętności, więc przekażemy nim nazwę pliku.

Zapisanie pliku pod istniejącą ścieżką może zastąpić wcześniejszą treść. Jeśli masz już taką umiejętność, zachowaj kopię przed zmianą.

4. Uruchom Claude Code i sprawdź dostępność

W terminalu z folderu projektu uruchom:

claude

Claude Code rozpoczyna sesję w bieżącym katalogu. Przy pierwszym uruchomieniu wykonaj wyświetlane kroki logowania.

Następne polecenie wpisz już w rozmowie z Claude, nie w Bash:

/skills

Polecenie /skills wyświetla dostępne umiejętności. Odszukaj wyjasnij-kod, a następnie zamknij listę klawiszem Esc.

5. Wywołaj umiejętność

W rozmowie z Claude wpisz:

/wyjasnij-kod przyklad.py

Oczekiwany wynik to wyjaśnienie według zapisanego schematu: cel, numerowany przebieg, przykład, miejsca do sprawdzenia i ćwiczenie. Dla tego pliku odpowiedź powinna pokazać, że rabat 15 procent od wartości 80 daje wynik 68.0.

Proponuję sprawdzić także zwykłe pytanie:

Wyjaśnij plik przyklad.py osobie, która dopiero zaczyna programować.

Oceń, czy Claude zastosował umiejętność i zachował wymagany format. Nie wymagaj identycznego brzmienia obu odpowiedzi.

Umiejętności nie ma na liście. Sprawdź dokładną ścieżkę i nazwę SKILL.md. Zalecam porównać zapisany katalog z poleceniem z kroku 2.

Polecenie działa, ale zwykłe pytanie nie uruchamia umiejętności. Dokumentacja rozwiązywania problemów zaleca sprawdzenie słów użytych w opisie, dostępności umiejętności i dopasowania pytania. Uszkodzony nagłówek YAML może też pozbawić umiejętność metadanych, mimo że bezpośrednie wywołanie nadal działa.

Odpowiedź jest zbyt ogólna. Proponuję dopisać wymaganie, które można sprawdzić, na przykład: „Przy każdej funkcji podaj dane wejściowe i zwracaną wartość”. Anthropic zaleca krótkie, konkretne instrukcje i sprawdzanie umiejętności w rzeczywistych zadaniach.

Czy trzeba umieć programować, żeby stworzyć skill?

Do naszego przykładu wystarczy edycja tekstu. Specyfikacja wymaga pliku SKILL.md, a skrypty są opcjonalne. Zacznij od opisania procedury prostymi zdaniami.

Czym skill różni się od CLAUDE.md?

CLAUDE.md służy do trwałych instrukcji projektu, a umiejętności do procedur potrzebnych przy określonych zadaniach. Proponuję oddzielić stałe konwencje od instrukcji konkretnej czynności.

Jak wyłączyć automatyczne uruchamianie umiejętności?

W nagłówku YAML dodaj disable-model-invocation: true. Według dokumentacji sterowania wywołaniem blokuje to samodzielne uruchamianie umiejętności przez Claude, pozostawiając wywołanie przez użytkownika.

Jak udostępnić własną umiejętność innym?

Zapisz ją w projektowym .claude/skills/wyjasnij-kod/SKILL.md i dodaj do repozytorium, czyli projektu z historią zmian przechowywaną przez Git. Dokumentacja wskazuje zapis w repozytorium jako sposób dzielenia się umiejętnością z zespołem.

Proponuję dodać własne wymaganie do wyjasnij-kod, na przykład wyjaśnianie każdej zmiennej, i ponownie sprawdzić odpowiedź. Jeśli chcesz przechowywać kolejne wersje umiejętności oraz udostępnić ją z projektem, przejdź do poradnika Git i GitHub od zera.