Autor: Współdzielenie umiejętności agenta między repozytoriami
Uniknij dryfu kodu przy kopiowaniu plików między projektami. Dowiedz się, jak traktować umiejętności agenta jako zależności z wersjonowaniem, testami i wspólnym repozytorium.
Jak współdzielić umiejętności agenta między repozytoriami
Aby współdzielić umiejętności agenta między repozytoriami, należy zrezygnować z kopiowania plików na rzecz zależności. Należy utrzymywać jedno repozytorium umiejętności, tagować je i pozwolić każdemu projektowi na przypięcie konkretnego tagu. Następnie należy dodać testy typu smoke test dla każdej umiejętności i traktować każdą aktualizację wersji tak samo, jak aktualizację zależności.
Proces ten składa się z czterech elementów: współdzielonego źródła prawdy, przypiętej wersji dla każdego repozytorium, testu typu smoke test dla każdej umiejętności oraz ścieżki weryfikacji. Poniżej wyjaśniono przyczyny istnienia każdego z tych elementów, funkcje narzędzi wydawanych w 2026 roku oraz sposób budowy całego systemu na własnym zdalnym serwerze git bez udziału zewnętrznych usług.
Umiejętność agenta to folder zawierający plik SKILL.md oraz wszelkie niezbędne skrypty i pliki referencyjne. Jeśli ta jednostka jest nowa, należy najpierw zapoznać się z definicją umiejętności agenta i działaniem pliku SKILL.md. Niniejsza strona dotyczy łańcucha dostaw związanego z tą jednostką.
Gdzie znajdują się umiejętności i dlaczego ich udostępnianie jest trudne
Claude Code wczytuje umiejętności z trzech lokalizacji, a dokumentacja umiejętności wskazuje każdą z tych ścieżek.
~/.claude/skills/<skill-name>/SKILL.mdma charakter osobisty. Jest wczytywana we wszystkich Twoich projektach i nie jest dostępna dla nikogo innego..claude/skills/<skill-name>/SKILL.mddotyczy poziomu projektu. Jest wczytywana dla każdego, kto pobierze to repozytorium.<plugin>/skills/<skill-name>/SKILL.mdjest dostarczana wewnątrz wtyczki. Jest wczytywana wszędzie tam, gdzie dana wtyczka jest włączona.
Środkowa opcja jest najbardziej użyteczna dla zespołu, ponieważ jest zatwierdzona w repozytorium i otrzymuje ją każdy, kto je sklonuje. To również tutaj pojawiają się problemy. Umiejętność w .claude/skills/ należy do jednego repozytorium. Jeśli posiadasz osiem repozytoriów, umiejętność zostaje skopiowana osiem razy.
Metadane (frontmatter) nie oferują żadnego wsparcia. Specyfikacja Agent Skills dopuszcza sześć kluczy, a ścieżki dystrybucji, które to wymuszają, wyświetlają listę w przypadku użycia innego klucza:
Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, nameZwróć uwagę na to, czego brakuje: nie ma klucza version. Wewnątrz pliku nie ma zapisu informującego o tym, która kopia jest nowsza. Jest to uzasadnione, ponieważ umiejętność jest dokumentem, a nie pakietem. Oznacza to jednak, że wersjonowanie musi odbywać się na poziomie warstwy otaczającej plik, a ta warstwa jest Twoim zadaniem.
Problem pierwszy: osiem kopii, które po cichu się rozbiegają
Kopiowanie i wklejanie działa pierwszego dnia. Zawodzi sześćdziesiątego dnia. Ktoś poprawia błędną instrukcję w repozytorium payments i nie zmienia pozostałych siedmiu. Ktoś inny dodaje regułę dotyczącą stronicowania w orders. Teraz ta sama nazwa umiejętności generuje dwie różne recenzje w zależności od tego, w którym katalogu agent został uruchomiony, a żaden z programistów o tym nie wie.
Awaria przebiega w sposób cichy, ponieważ nie występuje stan błędu. Umiejętność to tekst. Nieaktualna instrukcja generuje pewną siebie, błędną odpowiedź, co jest najbardziej kosztownym rodzajem błędu. Nic w agencie nie porównuje Twojej kopii z innymi, więc jedynym sygnałem jest zauważenie przez człowieka, że dwa repozytoria są ze sobą sprzeczne.
Problem drugi: brak przypisania wersji
Nawet jeśli zespół przechowuje umiejętności w jednym miejscu, standardową metodą udostępniania jest kopiowanie: skrypt instalacyjny, linia curl w dokumentacji wdrożeniowej lub alias powłoki synchronizujący folder. Wszystkie te metody instalują wersję znajdującą się w danym momencie na szczycie gałęzi.
Oznacza to, że dwóch programistów pracujących na tym samym commicie tej samej aplikacji może korzystać z różnych instrukcji, ponieważ wykonali synchronizację w różnych dniach. Oznacza to również, że nie można odpowiedzieć na kluczowe pytanie po nieudanym uruchomieniu agenta: która wersja umiejętności wygenerowała ten wynik? Bez zarejestrowanej rewizji uruchomienie nie jest powtarzalne, przez co zgłoszenie błędu nie nadaje się do analizy.
Problem trzeci: brak wiedzy o tym, czy umiejętność nadal działa
Umiejętność nie posiada kompilatora. Składa się z instrukcji skierowanych do modelu, dlatego może przestać działać, mimo że plik pozostaje identyczny pod względem bajtów. Aktualizacja modelu zmienia sposób, w jaki instrukcje są interpretowane. Narzędzie wiersza poleceń wywoływane przez umiejętność może zmienić nazwę flagi. Adres URL w pliku referencyjnym może zacząć zwracać błąd 404, a agent zacznie pracować w oparciu o stronę błędu.
W żadnym z tych przypadków nie występuje głośna awaria. Agent nadal udziela odpowiedzi. Odpowiedź jest po prostu gorszej jakości niż w poprzednim miesiącu, co jest trudne do zauważenia przy analizie pojedynczych pull requestów.
Problemy rozwiązywane przez narzędzia wydawane w 2026 roku
Obecnie pojawia się kilka rozwiązań, jednak brak jest konsensusu co do miejsca przechowywania wersji.
Pliki blokad (Lockfiles). Narzędzie wiersza poleceń skills od Vercel Labs (vercel-labs/skills, licencja MIT, wersja 1.5.22 na dzień 5 sierpnia 2026 r.) instaluje umiejętności (skills) z repozytorium git do katalogu oczekiwanego przez agenta; narzędzie obsługuje strukturę ponad siedemdziesięciu agentów. npx skills add <repo> instaluje, npx skills update aktualizuje, a npx skills list wyświetla zainstalowane elementy. Rejestr zainstalowanych składników jest przechowywany raz na użytkownika, a nie raz na repozytorium. Otwarte zgłoszenie w tym projekcie (issue 283) postuluje dodanie polecenia skills install, które reinstaluje wszystkie śledzone umiejętności z pliku blokady, aby zapewnić identyczny zestaw na drugim komputerze. Zgłoszenie to należy traktować jako raport o stanie prac. Koncepcja pliku blokady została ustalona, natomiast część dotycząca konfiguracji per-projekt jest w trakcie tworzenia.
Specyfikacje i testy. SkillSpec przyjmuje inne podejście. Traktuje SKILL.md jako kontrakt do weryfikacji, a nie tekst do zaufania, stawiając sobie za cel sprawienie, by umiejętności były „śledzalne, testowalne i weryfikowalne”. skillspec doctor <path> raportuje miejsca, w których agent prawdopodobnie przerwie wątek. skillspec boundary map <path> raportuje zasięg umiejętności, a skillspec boundary assess <path> szereguje te wyniki według ryzyka. Jest to biblioteka Rust, na podwójnej licencji MIT lub Apache 2.0, w wersji 0.2.2 na dzień 29 lipca 2026 r. Należy zainstalować przypiętą wersję zamiast najnowszej:
cargo install skillspec --version 0.2.2 --locked
skillspec --version--locked buduje projekt z wersjami zależności, z którymi biblioteka została opublikowana, co zapobiega dryfowaniu kompilacji. skillspec --version powinno wypisać 0.2.2. Inna liczba oznacza, że w zmiennej PATH znajduje się starszy plik binarny, który ma pierwszeństwo.
Praktyka vendoringu. Google opisało sposób budowania umiejętności w google/skills w artykule na temat budowania, testowania i skalowania umiejętności agentów. Po odrzuceniu skali, mechanizm okazuje się standardową ciągłą integracją (CI). Każda umiejętność przechodzi przez lintery sprawdzające metadane frontmatter, liczbę linii, strukturę katalogów i nazewnictwo przed scaleniem. Weryfikator linków przerywa budowanie w przypadku każdego adresu URL zwracającego 404, co pozwala wykryć prawdopodobne linki wygenerowane przez agenta. Autorzy muszą dostarczyć zestaw promptów ewaluacyjnych oraz rubrykę punktacji wraz z umiejętnością. Zaplanowane zadania ewaluacyjne są uruchamiane co tydzień dla całej biblioteki w celu wykrycia regresji, a każda umiejętność posiada przypisanego właściciela, który jest odpowiedzialny za naprawę w przypadku spadku jakości.
Wzorzec wspólny dla wszystkich trzech odpowiedzi
Nie trzeba wybierać jednego z tych rozwiązań. U ich podstaw leży pojedynczy schemat, a standardowe narzędzie git zapewnia pełną jego obsługę.
- Jedno źródło prawdy. Umiejętność ma dokładnie jedną lokalizację, a każde repozytorium odwołuje się do niej zamiast przechowywać kopię.
- Przypięta wersja dla każdego repozytorium. Każdy projekt rejestruje dokładną wersję, z której korzysta, dzięki czemu aktualizacja jest zatwierdzeniem (commit) w tym projekcie, opatrzonym autorem i datą.
- Test dymny dla każdej umiejętności. Jeden uruchamialny test potwierdzający, że umiejętność nadal generuje oczekiwany wynik.
- Ścieżka przeglądu. Zmiana we współdzielonej umiejętności przechodzi przez proces przeglądu, a każdy odbiorca widzi różnicę (diff) przed jej zaakceptowaniem.
Tak wygląda struktura zależności. Umiejętności stały się współdzielonym artefaktem szybciej, niż rozwinęły się narzędzia do ich obsługi, dlatego narzędzia, którym już ufasz, są najbezpieczniejszym wyborem.
Struktura dla małego zespołu korzystającego z własnego zdalnego repozytorium git
Jedno repozytorium przechowuje umiejętności. Nie zawiera ono niczego innego, dzięki czemu jego historia stanowi dziennik zmian instrukcji.
agent-skills/
skills/
api-review/
SKILL.md
release-notes/
SKILL.md
tests/
api-review.sh
release-notes.sh
CHANGELOG.mdWydania (releases) to tagi. Należy używać tagów opisowych (annotated tags), ponieważ zawierają one wiadomość oraz datę. Treść wiadomości powinna wyjaśniać powód, dla którego użytkownik końcowy powinien zaktualizować wersję:
git tag -a v1.4.0 -m "api-review: require pagination on list endpoints"
git push origin v1.4.0Jeśli zdalnym repozytorium jest Gitea, Forgejo, GitLab lub zwykłe repozytorium (bare repository) dostępne przez SSH na własnym VPS, poniższe zasady pozostają niezmienne. Wszystko tutaj opiera się na git oraz dowiązaniach symbolicznych (symlink).
Przypinanie wersji za pomocą git submodule
Moduł podrzędny (submodule) zapisuje konkretny commit innego repozytorium wewnątrz bieżącego repozytorium. Ten zapis stanowi przypięcie (pin). W każdym projekcie korzystającym z tego rozwiązania:
git submodule add https://git.example.com/team/agent-skills.git vendor/agent-skills
git -C vendor/agent-skills fetch --tags
git -C vendor/agent-skills checkout v1.4.0
mkdir -p .claude/skills
ln -s ../../vendor/agent-skills/skills/api-review .claude/skills/api-review
git add .gitmodules vendor/agent-skills .claude/skills/api-review
git commit -m "Pin shared agent skills to v1.4.0"Działanie tego mechanizmu opiera się na dowiązaniu symbolicznym (symlink). Wpis umiejętności na poziomie projektu może być dowiązaniem do katalogu w innej lokalizacji na dysku, a Claude Code podąża za nim i odczytuje SKILL.md z obiektu docelowego. Dzięki temu umiejętność ładuje się jako standardowa umiejętność projektu, podczas gdy jej pliki znajdują się w module podrzędnym w wybranej wersji (commit).
Weryfikacja przypięcia:
git submodule statusPoprawny wiersz zaczyna się od spacji, po której następuje commit, ścieżka oraz najbliższy tag:
4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602 vendor/agent-skills (v1.4.0)Znak - na początku oznacza, że moduł podrzędny nie został zainicjowany, przez co .claude/skills/api-review wskazuje na pusty katalog, a umiejętność nie ładuje się bez zgłaszania błędów. Należy to naprawić za pomocą git submodule update --init. Znak + oznacza, że sprawdzony commit różni się od zapisanego, co oznacza, że dany programista korzysta z instrukcji, których nie mają inni. Nowe klony wymagają git clone --recurse-submodules; informacja ta powinna znaleźć się w pliku README, ponieważ zwykłe polecenie clone pozostawia vendor/agent-skills puste i nie generuje żadnego błędu.
Aktualizacja jest procesem celowym, co stanowi główną zaletę tego rozwiązania:
git -C vendor/agent-skills fetch --tags
git -C vendor/agent-skills diff v1.4.0 v1.5.0 -- skills/
git -C vendor/agent-skills checkout v1.5.0
git add vendor/agent-skills
git commit -m "Bump shared agent skills to v1.5.0"Wiersz diff wskazuje ścieżkę przeglądu. Pokazuje on tę samą zmianę, którą zobaczą wszystkie inne repozytoria korzystające z modułu, i jest w pełni widoczny w ramach pull request.
Przypinanie wersji za pomocą zewnętrznego marketplace wtyczek
Jeśli nie chcesz wymagać od każdego programisty nauki obsługi submodułów, system wtyczek Claude Code zajmie się dystrybucją za Ciebie, współpracując z własnym, zdalnym repozytorium. Umieść katalog w .claude-plugin/marketplace.json w repozytorium z umiejętnościami (skills):
{
"name": "acme-agents",
"owner": { "name": "Platform team", "email": "platform@example.com" },
"plugins": [
{
"name": "team-skills",
"description": "Shared review and release skills",
"version": "1.4.0",
"source": {
"source": "url",
"url": "https://git.example.com/team/agent-skills.git",
"ref": "v1.4.0",
"sha": "4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602"
}
}
]
}W grę wchodzą tutaj dwa różne źródła, a ich mylenie jest częstym błędem. Źródło marketplace, czyli miejsce, z którego pobierany jest sam katalog, akceptuje ref dla gałęzi lub tagu i nie akceptuje sha. Źródło wtyczki wewnątrz katalogu akceptuje oba parametry, a w przypadku ustawienia obu, to sha staje się wiążącym przypięciem. Zatem przypięcie do konkretnego commita należy umieścić we wpisie w katalogu.
Każde repozytorium korzystające z wtyczek deklaruje marketplace w swoim zatwierdzonym pliku .claude/settings.json:
{
"extraKnownMarketplaces": {
"acme-agents": {
"source": {
"source": "url",
"url": "https://git.example.com/team/agent-skills.git",
"ref": "v1.4.0"
}
}
},
"enabledPlugins": {
"team-skills@acme-agents": true
}
}Członek zespołu, który ufa folderowi projektu, otrzyma monit o instalację marketplace, a wtyczka zostanie dla niego włączona bez konieczności korzystania ze strony wiki z instrukcją. Umiejętności odpowiadają następnie na /team-skills:api-review, ponieważ umiejętności wtyczek posiadają przestrzeń nazw opartą na nazwie wtyczki i nie mogą kolidować z umiejętnością projektu o tej samej nazwie. Po wypchnięciu nowego tagu, użytkownicy odświeżają stan za pomocą /plugin marketplace update acme-agents, a następnie uruchamiają /reload-plugins, jeśli podsumowanie instalacji tego wymaga.
Tworzenie testu dymnego dla jednej umiejętności
Test dymny to skrypt uruchamiający agenta na środowisku testowym z celowo wprowadzonym błędem oraz jedną asercją. Claude Code działa w trybie nieinteraktywnym z użyciem -p, a wywoływana przez użytkownika umiejętność działa w tym środowisku: umieszczenie /skill-name w ciągu znaków promptu powoduje jego rozwinięcie przed rozpoczęciem uruchomienia.
#!/usr/bin/env bash
set -euo pipefail
claude -p "/api-review Read fixtures/orders-api.md and list the rule ids it breaks." \
--allowedTools "Read" \
--output-format json \
--json-schema '{"type":"object","properties":{"rule_ids":{"type":"array","items":{"type":"string"}}},"required":["rule_ids"]}' \
| jq -e '.structured_output.rule_ids | index("pagination-required")' > /dev/nullfixtures/orders-api.md to krótki plik zawierający jeden celowy błąd. Asercja zakłada, że umiejętność zidentyfikuje ten błąd. jq -e kończy działanie z kodem wyjścia różnym od zera, gdy filtr generuje null, więc umiejętność, która przestaje wykrywać wprowadzony błąd, powoduje niepowodzenie skryptu. claude kończy działanie z kodem wyjścia różnym od zera w przypadku niepowodzenia uruchomienia, a set -euo pipefail przekształca każde z tych niepowodzeń w wynik negatywny testu.
Model zmienia brzmienie odpowiedzi pomiędzy uruchomieniami, dlatego nigdy nie należy stosować asercji na całych zdaniach. Należy stosować asercje na identyfikatorze, który umiejętność powinna wyemitować, lub na polu schematu, o który poproszono, oraz utrzymywać mały rozmiar środowiska testowego, aby koszt uruchomienia pozostał niski.
W środowisku CI należy dodać --bare. Bez tego parametru claude -p ładuje ten sam kontekst, co sesja interaktywna, w tym hooki, wtyczki oraz CLAUDE.md z maszyny, na której jest uruchamiany, co oznacza, że osobista konfiguracja członka zespołu może wpłynąć na wynik. Tryb bare pomija automatyczne wykrywanie, co oznacza również pominięcie testowanej umiejętności, dlatego należy ją załadować jawnie. Tryb bare nie odczytuje również danych logowania subskrypcji, dlatego należy najpierw ustawić ANTHROPIC_API_KEY w środowisku:
claude --bare -p "/team-skills:api-review Read fixtures/orders-api.md and list the rule ids it breaks." \
--plugin-dir vendor/agent-skills \
--allowedTools "Read" \
--output-format jsonDzięki --output-format stream-json pierwsze zdarzenie uruchomienia raportuje, które wtyczki zostały załadowane, i zawiera tablicę plugin_errors dla tych, które nie zostały załadowane. Należy przerwać zadanie CI, jeśli tablica plugin_errors nie jest pusta. Pozwala to wykryć przypięcie do wersji, która już nie istnieje, co w przeciwnym razie wyglądałoby jak agent cicho ignorujący zasady wewnętrzne.
Współdzielona umiejętność to wykonywalna instrukcja
Dwie funkcje sprawiają, że jest to dosłowne, a obie mają znaczenie, gdy plik pochodzi z innego zespołu.
Po pierwsze, SKILL.md może uruchamiać polecenia powłoki, zanim model cokolwiek odczyta. Linia taka jak poniższa w treści jest przetwarzaniem wstępnym:
- Current branch: !`git rev-parse --abbrev-ref HEAD`Polecenie uruchamia się na maszynie ładującej umiejętność, a jego wyjście zastępuje symbol zastępczy w tekście otrzymywanym przez model. Zablokowany blok otwarty trzema znakami odwrotnego apostrofu, po których następuje !, uruchamia kilka poleceń w ten sam sposób. Nikt nie zatwierdza tego w czasie wykonywania. Odczytanie współdzielonej umiejętności oznacza odczytanie jej podstawień poleceń.
Po drugie, frontmatter może wstępnie zatwierdzać narzędzia. allowed-tools przyznaje wymienione narzędzia bez monitu o uprawnienia dla tury, która wywołała umiejętność. W przypadku umiejętności projektowej to uprawnienie wchodzi w życie, gdy użytkownik zaakceptuje okno dialogowe zaufania obszaru roboczego dla folderu. Dokumentacja Claude Code jasno określa konsekwencje: należy przejrzeć umiejętności projektowe przed obdarzeniem zaufaniem repozytorium, ponieważ umiejętność może samodzielnie przyznać sobie szeroki dostęp do narzędzi.
Dlatego aktualizację umiejętności należy traktować dokładnie tak samo, jak aktualizację zależności. Należy przypinać wersje do konkretnego commita, gdziekolwiek mechanizm na to pozwala, ponieważ tag może zostać przeniesiony, a branch zmienia się z definicji. Na zabezpieczonej maszynie ustawienie "disableSkillShellExecution": true zastępuje każde podstawienie polecenia dosłownym tekstem [shell command execution disabled by policy] zamiast jego uruchamiania, a zastosowane poprzez zarządzane ustawienia, użytkownik nie może go nadpisać. Umiejętności dołączone i zarządzane są wyłączone z tego ustawienia.
Ta sama ostrożność dotyczy tego, co odczytuje umiejętność. Umiejętność, która uruchamia env lub otwiera plik konfiguracyjny, pobiera wszystko, co znajdzie, do kontekstu modelu, co stanowi błąd opisany w utrzymywanie sekretów poza uruchamianymi agentami. Umiejętność, która pobiera stronę lub uruchamia zapytanie, jest tym samym narażeniem skierowanym na zewnątrz, ponieważ pobrany tekst trafia do kontekstu, wyglądając dokładnie tak samo jak instrukcje, które napisałeś. Jest to granica, o której warto przeczytać, zanim skierujesz agenta na własną instancję SearXNG w celu wyszukiwania w sieci.
Co należy sprawdzić przy zmianie wersji
- Różnice (diff) w każdym elemencie
SKILL.md, ponieważ ten tekst stanowi instrukcję, którą będzie wykonywał agent. - Każde podstawienie polecenia (command substitution), ponieważ są one uruchamiane na maszynie w momencie ładowania umiejętności.
- Każdą zmianę w
allowed-tools, ponieważ ta linia przyznaje narzędzia bez dodatkowego monitu. - Testy uruchamiane w ramach danego tagu. Jeśli współdzielone repozytorium wykonuje własne testy typu smoke w CI, tag, do którego przypinasz wersję, powinien posiadać status pomyślnego wykonania (green run).
Recenzent, który nie jest w stanie przeczytać całego diffa w dziesięć minut, analizuje umiejętność, która stała się zbyt rozbudowana. Należy ją podzielić. Ten sam argument dotyczy dokumentów w repozytorium, które czytają agenci: trwałe zasady należy przechowywać w plikach opisanych w podziale na AGENTS.md i HUMAN.md, a uzasadnienia architektoniczne w pliku DESIGN.md przygotowanym dla agentów, pozostawiając umiejętności jako wąsko zdefiniowane procedury.
Gdy zmiana modelu lub narzędzia powoduje błąd umiejętności
Wiele elementów zmienia się wewnątrz umiejętności bez ingerencji użytkownika. Aktualizacja modelu zmienia niezawodność wykonywania długich instrukcji, więc umiejętność polegająca na dotarciu modelu do dziewiątego kroku może przestać go osiągać. Narzędzie wiersza poleceń zmienia nazwę flagi, więc agent uruchamia starą flagę, odczytuje błąd i improwizuje. Odwołany adres URL zaczyna zwracać błąd 404. Mechanizm sterujący agenta zmienia sposób wyboru umiejętności, więc description, który wcześniej wygrywał dopasowanie, przestaje to robić. Gdy procedura zaczyna kończyć się przedwcześnie, żadna zmiana wersji tego nie naprawi, a same instrukcje wymagają struktury wymuszającej wykonanie ostatnich kroków, co stanowi podstawę metody the unlazy skill and its Depth Tree method.
Dlatego w tym układzie testy typu smoke test mają kluczowe znaczenie. Należy uruchamiać test każdej umiejętności zgodnie z harmonogramem oraz przy każdym wypchnięciu zmian. Z tego powodu Google uruchamia cotygodniowe zadania ewaluacyjne dla całej biblioteki, a cotygodniowe zadanie cron na małym VPS wystarczy dla zespołu posiadającego dziesięć umiejętności. Jest to jedyny sposób, aby dowiedzieć się o awarii, zanim zrobi to programista.
Przenośność również pomaga. Specyfikacja Agent Skills ogranicza metadane do sześciu kluczy, dzięki czemu umiejętność napisana zgodnie z tą specyfikacją ładuje się w narzędziach innych niż to, dla którego została stworzona, podczas gdy każdy dodany klucz specyficzny dla danego mechanizmu jest zakładem na jednego dostawcę. Pisanie umiejętności, które przetrwają zmianę modelu, jest odrębną dyscypliną, omówioną w making a skill work on any model.
FAQ
Jak współdzielić umiejętność agenta między wieloma repozytoriami?
Umieść umiejętność w dedykowanym repozytorium git, oznaczaj w nim wydania (tags) i spraw, aby każdy projekt korzystający z tej umiejętności odwoływał się do konkretnego tagu zamiast kopiować plik. Działają dwa mechanizmy. Podmoduł git (git submodule) rejestruje dokładny commit, a dowiązanie symboliczne (symlink) z .claude/skills/<name> do podmodułu sprawia, że jest on ładowany jako standardowa umiejętność projektu. Rynek wtyczek (plugin marketplace) wykonuje to samo zadanie poprzez /plugin, z przypięciem zadeklarowanym w pliku .claude/settings.json projektu korzystającego. Oba rozwiązania zapisują wersję w historii git, co pozwala ustalić, jakie instrukcje wygenerowały konkretne uruchomienie agenta.
Czy można przypiąć umiejętność agenta do konkretnej wersji?
Nie z poziomu SKILL.md, ponieważ ten frontmatter nie posiada klucza version. Przypięcie musi pochodzić z warstwy otaczającej plik. Podmoduł git z założenia przypina dokładny commit. W rynku wtyczek Claude Code źródło wtyczki akceptuje ref dla gałęzi lub tagu oraz sha dla dokładnego commita, przy czym sha ma pierwszeństwo, gdy oba są obecne. Samo źródło rynku akceptuje wyłącznie ref. Preferuj przypięcie do commita, ponieważ tag może zostać zmieniony po jego zweryfikowaniu.
Co powinien sprawdzać test dymny (smoke test) umiejętności?
Sprawdzaj elementy stabilne. Uruchom umiejętność w trybie nieinteraktywnym przeciwko zestawowi danych (fixture) zawierającemu znany błąd, a następnie sprawdź, czy w wyjściu pojawia się konkretny identyfikator, na przykład identyfikator reguły, którą umiejętność powinna zgłosić. Żądanie wyjścia strukturalnego za pomocą --output-format json i --json-schema sprawia, że weryfikacja jest precyzyjna, a jq -e przerywa skrypt, gdy wartość jest nieobecna. Nigdy nie sprawdzaj pełnych zdań, ponieważ model zmienia sformułowania odpowiedzi między uruchomieniami.
Czy instalacja współdzielonej umiejętności z repozytorium innego zespołu jest bezpieczna?
Traktuj ją jak zależność kodu, ponieważ jest to wykonywalna instrukcja. SKILL.md może uruchamiać polecenia powłoki w czasie ładowania poprzez podstawienie polecenia !, a pole allowed-tools we frontmatterze może wstępnie zatwierdzać narzędzia bez pytania o zgodę. Analizuj różnice (diff) przy każdej aktualizacji, przypinaj do dokładnego commita zamiast do gałęzi i preferuj źródła kontrolowane przez własny zespół. Na zarządzanych maszynach ustawienie "disableSkillShellExecution": true całkowicie blokuje uruchamianie podstawień poleceń.
Czy współdzielona umiejętność zadziała w innych agentach niż Claude Code?
Zależy to od użytego frontmattera. Specyfikacja Agent Skills definiuje sześć kluczy: name, description, license, compatibility, metadata oraz allowed-tools. Umiejętność ograniczona do tych kluczy ładuje się w narzędziach implementujących specyfikację, a także w Claude Code bez żadnych zmian. Klucze specyficzne dla danego środowiska oraz funkcje treści wykraczające poza specyfikację są ignorowane lub odrzucane w innych narzędziach, dlatego należy ich unikać w umiejętnościach przeznaczonych do szerokiego udostępniania.