Skills.sh, umiejętności agentów jako pliki

Skills.sh, umiejętności agentów jako pliki

Skills.sh to rejestr i narzędzie wiersza poleceń do rozdawania umiejętności dla asystentów programistycznych. Umiejętność to katalog z plikiem opisowym w markdownie, a instalacja sprowadza się do jednego polecenia, które kopiuje ją do Twojego projektu.

Narzędzie ukazało się dwudziestego stycznia 2026 roku, a jego pomysł polega na tym, żeby wiedza o tym, jak coś zrobić w konkretnym projekcie albo z konkretną biblioteką, przestała mieszkać w głowach i w pojedynczych rozmowach.

Czym właściwie jest umiejętność

Warto to rozstrzygnąć od razu, bo nazwa sugeruje coś bardziej złożonego, niż jest.

Umiejętność to plik tekstowy z nagłówkiem zawierającym nazwę i opis oraz z treścią mówiącą, jak wykonać określone zadanie. Nie ma tu kodu wykonywanego przez system, nie ma wtyczki i nie ma warstwy uruchomieniowej. Jest instrukcja, którą czyta model.

Konsekwencja jest podwójna i obie strony warto znać.

Zaleta polega na prostocie. Napisanie umiejętności to napisanie dokumentu, więc może to zrobić każdy, kto potrafi opisać procedurę. Nie trzeba znać niczyjego interfejsu programistycznego.

Wada polega na tym samym. Skoro to jest instrukcja czytana przez model, to jej instalacja oznacza wstawienie cudzego tekstu do kontekstu Twojego asystenta. Do tego wrócimy niżej, bo to jest najważniejsza rzecz w całym tekście.

Format i sposób działania

Umiejętność mieszka w katalogu z plikiem opisowym, do którego można dołożyć materiały pomocnicze: przykłady, szablony, fragmenty konfiguracji.

Nagłówek pliku zawiera dwie rzeczy obowiązkowe: nazwę i opis. Opis jest ważniejszy, niż wygląda, bo to on decyduje, kiedy asystent po tę umiejętność sięgnie.

---
name: migracje-bazy
description: Uzyj przy dodawaniu lub zmianie tabeli w bazie. Opisuje, jak
  wygenerowac migracje, jak ja nazwac i co sprawdzic przed scaleniem.
---

# Migracje bazy

1. Zmien model w prisma/schema.prisma
2. Uruchom pnpm prisma migrate dev --name opis-zmiany
3. Sprawdz wygenerowany SQL w prisma/migrations, szczegolnie DROP i NOT NULL
4. Dopisz migracje danych, jesli kolumna nie moze byc pusta

Zdanie mówiące wprost, w jakiej sytuacji umiejętność zastosować, działa lepiej niż samo stwierdzenie, czego dotyczy. Opis zaczynający się od „Użyj, gdy..." jest tu skuteczniejszy niż opis zaczynający się od „Dokumentacja...".

Instalacja odbywa się poleceniem uruchamianym bez instalowania czegokolwiek na stałe. Narzędzie pobiera umiejętność i zapisuje ją w miejscu, w którym Twój asystent szuka kontekstu, a miejsce to zależy od narzędzia.

.claude/skills/<nazwa>/SKILL.md
.agents/skills/<nazwa>/SKILL.md
.windsurf/skills/<nazwa>/SKILL.md

Format jest przy tym wszędzie ten sam, czyli plik SKILL.md z tym samym nagłówkiem, a różni się wyłącznie katalog docelowy. Sporo narzędzi, w tym Cursor, Codex i Gemini, dzieli zresztą jeden wspólny katalog. Domyślnie powstaje jedna kanoniczna kopia, a do katalogów poszczególnych narzędzi prowadzą dowiązania, więc poprawka w jednym miejscu widoczna jest wszędzie; osobny przełącznik wymusza niezależne kopie tam, gdzie dowiązania nie działają. To jest cała wartość tego narzędzia sprowadzona do jednego akapitu.

Ta ostatnia rzecz jest sednem pomysłu. Każdy asystent szuka dodatkowego kontekstu gdzie indziej, a to narzędzie zna te miejsca i rozkłada tam umiejętność za Ciebie. Ta sama umiejętność trafia tam, gdzie trzeba, niezależnie od tego, czy pracujesz w Cursorze, w Windsurfie, czy w narzędziu terminalowym.

Obsługiwanych narzędzi jest kilkadziesiąt: tabela w repozytorium projektu wymienia siedemdziesiąt sześć identyfikatorów i to ona jest źródłem rozstrzygającym, bo listy w innych materiałach bywają krótsze. Przed decyzją sprawdź w niej swoje narzędzie, bo tabela podaje przy okazji ścieżkę, pod którą umiejętność wyląduje.

Do czego to się nadaje

Trzy zastosowania mają sens, a poza nimi to jest rozwiązanie szukające problemu.

Pierwsze to konwencje projektu, których nie widać w kodzie. Sposób nazywania, wzorzec obsługi błędów, reguła mówiąca, że warstwa usług nie sięga do bazy bezpośrednio. Model wyciąga wnioski z tego, co widzi, więc konwencja, od której odstępowano przez dwa lata, zostanie odczytana jako obie wersje naraz.

Drugie to procedury powtarzalne. Jak dodać nowy typ zadania, jak wygenerować migrację, jak wypuścić wersję. To są rzeczy, które w zespole zna jedna osoba i tłumaczy je za każdym razem od nowa. Materiał na taką umiejętność bierze się zwykle z pracy bieżącej: polecenie, po którym asystent trafił za pierwszym razem, opłaca się zapisać, bo odtworzenie go z pamięci dwa tygodnie później zwykle się nie udaje. To jeden z nawyków opisanych w Get Shit Done, gdzie zadanie dobiera się tak, żeby wynik dało się przejrzeć w kwadrans, bo kod powstający szybciej, niż da się go przeczytać, jest długiem, a nie postępem.

Trzecie to biblioteki zmieniające się szybko. Model zna stan sprzed swojego progu wiedzy, więc umiejętność opisująca bieżący sposób użycia narzędzia bywa różnicą między kodem działającym a wycofanym.

Poza tymi trzema przypadkami wartość maleje. Umiejętność powtarzająca to, co jest w dokumentacji biblioteki, dokłada tekstu do kontekstu bez żadnego zysku, a kontekst jest zasobem ograniczonym.

Bezpieczeństwo, czyli rzecz najważniejsza

Skoro umiejętność jest instrukcją, którą czyta model, to instalowanie jej z nieznanego źródła jest instalowaniem cudzego promptu do własnego narzędzia.

To brzmi łagodnie i takie nie jest. Asystent programistyczny ma dostęp do Twojego repozytorium, uruchamia polecenia i wprowadza zmiany. Instrukcja mówiąca mu, żeby przy okazji dopisał coś do pliku konfiguracyjnego albo wysłał zawartość zmiennej środowiskowej pod wskazany adres, wygląda w pliku markdown zupełnie zwyczajnie.

Różnica wobec zwykłego pakietu jest taka, że tam kod da się przeczytać i zwykle ktoś to robi, a tu treść jest prozą, którą łatwo przewinąć bez czytania. Do tego dochodzi to, że instrukcja nie musi być jawna: fragment ukryty w materiale pomocniczym albo sformułowany jako część procedury działa tak samo.

Praktyczne zasady są trzy i warto je traktować poważnie.

Czytaj przed instalacją. To jest plik tekstowy, więc przeczytanie go zajmuje minutę, i ta minuta jest tu głównym zabezpieczeniem. Rejestr prowadzi wprawdzie osobną zakładkę z wynikami audytów zbieranymi z trzech zewnętrznych usług, ale sprawdzona jest tam garstka pozycji z samej czołówki, a przy reszcie widnieje status oczekujący. Dostawca sam zastrzega, że jakości ani bezpieczeństwa każdej pozycji nie gwarantuje. Warto też sprawdzić, co dokładnie pojawiło się w repozytorium, zamiast ufać, że instalator dodał tylko to, co obiecał.

git status --porcelain
git diff --cached -- '*/SKILL.md' '*.mdc'
grep -rInE "curl|wget|base64|process\.env|ANTHROPIC|AWS_|_TOKEN" .claude/skills/

Ostatnie polecenie nie wykryje wszystkiego, bo instrukcja napisana prozą nie musi zawierać żadnego z tych słów. Wyłapuje natomiast przypadki najbardziej jaskrawe, a te zdarzają się częściej niż wyrafinowane.

Instaluj ze źródeł, które rozpoznajesz. Umiejętność od autora biblioteki, której używasz, to co innego niż umiejętność z konta założonego w zeszłym tygodniu.

Traktuj to jak zależność w przeglądzie kodu. Umiejętność wchodząca do repozytorium powinna przechodzić przegląd jak każdy inny plik, bo wpływa na to, co asystent zrobi z Twoim projektem.

Skala rejestru i co z niej wynika

Liczby podawane dla tego rejestru robią wrażenie: setki tysięcy pozycji w pierwszym półroczu istnienia, a najpopularniejsze umiejętności liczone w milionach instalacji. Traktuj je jako rząd wielkości, bo pochodzą z zestawień zewnętrznych, a nie z audytu.

Ważniejsze od samych liczb jest to, co z takiej skali wynika przy wybieraniu.

Po pierwsze, większość pozycji nie została przez nikogo przejrzana. Rejestr o niskim progu wejścia zapełnia się szybko, a stosunek rzeczy przemyślanych do wygenerowanych na szybko jest tu podobny jak w każdym otwartym katalogu.

Po drugie, liczba instalacji nie jest miarą jakości, tylko widoczności. Umiejętność wypromowana wcześnie zbiera instalacje przez miesiące, także od osób, które zainstalowały ją i nigdy nie użyły.

Po trzecie, duplikaty są normą. Kilkanaście umiejętności opisujących tę samą bibliotekę różni się szczegółami i datą, a wybór najlepszej wymaga przeczytania ich, czyli dokładnie tego, co i tak trzeba zrobić przed instalacją.

Praktyczna droga wygląda tak: szukaj umiejętności wydanych przez autorów narzędzia, którego dotyczą, a przy pozostałych czytaj treść i sprawdzaj datę. Umiejętność opisująca bibliotekę zmieniającą się co kwartał, napisana rok temu, jest gorsza niż jej brak, bo model uzna ją za wiarygodne źródło.

Umiejętności w zespole

Największa wartość tego mechanizmu pojawia się wtedy, gdy przestaje być prywatnym zbiorem jednej osoby.

Wspólny zestaw umiejętności dla zespołu sprawia, że wszyscy pracują na tych samych regułach. Bez tego każda osoba dostaje kod w swoim stylu, bo każda ma inny zestaw kontekstu, i projekt rozjeżdża się szybciej, niż ktokolwiek zauważy.

Sensowna praktyka polega na trzymaniu umiejętności zespołowych w repozytorium projektu, tak żeby przychodziły razem z kodem. Osoba dołączająca do projektu dostaje je automatycznie, a zmiana reguły przechodzi przez przegląd jak każda inna zmiana.

Żeby to działało, katalog z umiejętnościami musi być śledzony przez system kontroli wersji, a nie wykluczony razem z resztą ustawień narzędzia. To rozróżnienie warto zapisać wprost.

.claude/settings.local.json
.claude/cache/
!.claude/skills/

Wykrzyknik w trzeciej linii jest tu całą treścią. Bez niego wpis wykluczający katalog narzędzia zabiera ze sobą także umiejętności, a wtedy każda osoba w zespole ma własny, niewidoczny dla innych zestaw.

Warto też ustalić, kto je pisze i kiedy. Reguła dopisywana po drugim wystąpieniu tego samego problemu jest tania i skuteczna, a próba opisania wszystkiego z góry kończy się dokumentem, którego nikt nie czyta i który po pół roku wprowadza w błąd.

Ostatnia rzecz dotyczy przeglądów. Umiejętność wchodząca do repozytorium powinna być czytana tak samo uważnie jak kod, i to nie tylko ze względu na bezpieczeństwo. Reguła sformułowana niejasno prowadzi model w złą stronę systematycznie, a znalezienie przyczyny zajmuje więcej czasu niż napisanie jej porządnie za pierwszym razem.

Skills.sh kontra alternatywy

Rozróżnienie między pierwszym a drugim wierszem jest tu najważniejsze i często mylone. Umiejętność mówi modelowi, jak coś zrobić. Serwer zgodny z protokołem narzędziowym daje modelowi możliwość wykonania czegoś: odpytania bazy, wysłania wiadomości, odczytania pliku. Jedno to wiedza, drugie to zdolność.

Trzeci wiersz warto rozważyć, zanim sięgniesz po rejestr. Reguła dotycząca wyłącznie Twojego projektu nie musi być pakietem. Plik z wytycznymi leżący w repozytorium działa tak samo, przechodzi przegląd razem z kodem i nie wymaga niczego instalować.

Wartość rejestru pojawia się przy wiedzy przenoszalnej między projektami: sposób pracy z konkretną biblioteką, procedura, którą Twoja firma stosuje w dziesięciu repozytoriach. Tam pakiet jest właściwą formą.

Pisanie własnych umiejętności

Kilka rzeczy odróżnia umiejętność użyteczną od takiej, która zaśmieca kontekst.

Opis w nagłówku pisz jako warunek zastosowania, nie jako temat. Zdanie mówiące, w jakiej sytuacji po tę umiejętność sięgnąć, decyduje o tym, czy model użyje jej wtedy, kiedy trzeba.

Treść pisz jako procedurę, nie jako wykład. Model potrzebuje kroków i przykładów, a nie wprowadzenia historycznego. Krótki fragment kodu pokazujący poprawne użycie działa lepiej niż akapit opisujący to samo słowami.

Ograniczaj długość. Umiejętność zajmuje miejsce w kontekście przy każdym jej użyciu, więc dokument na dwa tysiące słów kosztuje przy każdym zadaniu. Warto podzielić go na kilka mniejszych, sięganych osobno.

Wpisuj wersje. Umiejętność opisująca bibliotekę bez podania, której wersji dotyczy, po pół roku wprowadza w błąd zamiast pomagać.

Testuj na prawdziwym zadaniu. Umiejętność, która wygląda dobrze i nie zmienia wyniku, jest kosztem, a nie zyskiem, i sprawdza się to wyłącznie przez porównanie z nią i bez niej.

Typowe błędy

Pierwszy to instalowanie umiejętności bez przeczytania jej treści. To jest instrukcja dla narzędzia mającego dostęp do Twojego repozytorium, więc minuta czytania jest tu jedynym zabezpieczeniem.

Drugi to instalowanie wszystkiego, co wygląda przydatnie. Każda umiejętność zajmuje kontekst, a model z dwudziestoma opisami do przejrzenia wybiera gorzej niż z trzema.

Trzeci to pakowanie reguł dotyczących jednego projektu. Plik z wytycznymi w repozytorium robi to samo, przechodzi przegląd razem z kodem i nie wymaga instalacji.

Czwarty to mylenie tego z protokołem narzędziowym. Umiejętność daje wiedzę, serwer narzędziowy daje zdolność wykonania, i jedno nie zastępuje drugiego.

Piąty to opis mówiący, czego umiejętność dotyczy, zamiast kiedy ją zastosować. Model nie sięgnie po nią we właściwym momencie, choć jest zainstalowana.

Szósty to brak wersji przy opisie biblioteki. Po kilku miesiącach umiejętność opisuje sposób użycia, który już nie obowiązuje, i pogarsza wynik zamiast go poprawiać.

Siódmy to ocenianie umiejętności po liczbie instalacji. Ta liczba mówi o widoczności, a nie o jakości, i wypromowana wcześnie pozycja zbiera ją także od osób, które nigdy jej nie użyły.

Ósmy to trzymanie umiejętności zespołowych poza repozytorium. Osoba dołączająca do projektu ich nie dostaje, a zmiana reguły nie przechodzi przez żaden przegląd, więc zespół pracuje na różnych zestawach kontekstu.

FAQ

Czym jest umiejętność w tym rozumieniu?

Katalogiem z plikiem markdown, którego nagłówek zawiera nazwę i opis, a treść mówi, jak wykonać określone zadanie. Nie ma tu kodu ani warstwy uruchomieniowej, jest instrukcja czytana przez model asystenta.

Które narzędzia to obsługują?

Siedemdziesiąt sześć identyfikatorów wymienionych w tabeli w repozytorium projektu, od asystentów terminalowych po osobne edytory. Listy w innych materiałach bywają krótsze, więc przed decyzją sprawdź tę tabelę: podaje też katalog, do którego trafi umiejętność.

Czy instalowanie umiejętności jest bezpieczne?

Wymaga tej samej ostrożności co instalowanie zależności, a właściwie większej. Umiejętność to instrukcja dla narzędzia mającego dostęp do Twojego repozytorium i uruchamiającego polecenia, więc czytaj treść przed instalacją i sięgaj po źródła, które rozpoznajesz.

Czym to różni się od serwerów MCP?

Rodzajem tego, co dostarczają. Umiejętność daje modelowi wiedzę o tym, jak coś zrobić. Serwer zgodny z tym protokołem daje możliwość wykonania czegoś, na przykład odpytania bazy. Jedno nie zastępuje drugiego i typowy projekt używa obu.

Kiedy wystarczy zwykły plik z wytycznymi?

Gdy reguła dotyczy wyłącznie tego projektu. Plik w repozytorium działa tak samo, przechodzi przegląd razem z kodem i nie wymaga instalacji. Rejestr ma sens przy wiedzy przenoszalnej między projektami.

Dokumentacja formatu stoi na stronie dostawcy, a kod narzędzia w repozytorium na GitHubie.