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 zaprzestać kopiowania plików i zacząć korzystać z zależności. Należy utrzymywać jedno repozytorium umiejętności, oznaczać je tagami 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 weryfikować każdą aktualizację wersji w taki sam sposób, jak aktualizację zależności.
Proces ten składa się z czterech części: 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ższa treść wyjaśnia powody istnienia każdego z tych elementów, funkcjonalności dostarczane w narzędziach z 2026 roku oraz sposób zbudowania całości na własnym serwerze git bez korzystania z zewnętrznych usług.
Umiejętność agenta to folder zawierający plik SKILL.md oraz wszelkie skrypty i pliki referencyjne, których wymaga. Jeśli ta jednostka jest nowa, najpierw należy zapoznać się z czym jest umiejętność agenta i jak działa SKILL.md. Niniejsza strona dotyczy łańcucha dostaw związanego z tą jednostką.
Gdzie przechowywane są 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, ale nie w projektach innych osób..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 aktywna.
Środkowa opcja jest najbardziej użyteczna dla zespołu, ponieważ jest zatwierdzana w repozytorium i dostępna dla każdego, kto je sklonuje. To jednak tutaj pojawiają się problemy. Umiejętność w .claude/skills/ należy do jednego repozytorium. Jeśli posiadasz osiem repozytoriów, umiejętność jest kopiowana osiem razy.
Nagłówek (frontmatter) nie oferuje w tym zakresie ż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 żadnego zapisu informującego o tym, która kopia jest nowsza. Jest to zrozumiałe, ponieważ umiejętność jest dokumentem, a nie pakietem. Oznacza to jednak, że wersjonowanie musi odbywać się na poziomie warstwy otaczającej plik, a zarządzanie tą warstwą należy do Twoich obowiązków.
Problem pierwszy: osiem kopii, które po cichu stają się niespójne
Kopiowanie i wklejanie działa pierwszego dnia. Zawodzi sześćdziesiątego dnia. Ktoś poprawia błędną instrukcję w repozytorium payments i nie wprowadza zmian w 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ść jest tekstem. Nieaktualna instrukcja generuje pewną siebie, błędną odpowiedź, co jest najbardziej kosztownym rodzajem błędu. Żaden element agenta 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 przypięcia 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ą to, co w danej chwili znajduje się na szczycie gałęzi.
Oznacza to, że dwóch programistów pracujących na tym samym commicie tej samej aplikacji może wykonywać różne instrukcje, ponieważ przeprowadzili synchronizację w różnych dniach. Oznacza to również brak możliwości odpowiedzi 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 aktualnym działaniu umiejętności
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 przestrzegane są długie instrukcje. Narzędzie wiersza poleceń wywoływane przez umiejętność zmienia nazwę flagi. Adres URL w pliku referencyjnym zaczyna zwracać błąd 404, a agent pracuje 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 gorsza 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) instaluje umiejętności (skills) z repozytorium git do katalogu oczekiwanego przez agenta. Narzędzie obsługuje strukturę plików dla 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. Otwarta prośba w tym projekcie (issue 283) dotyczy polecenia skills install, które reinstaluje wszystkie śledzone umiejętności z pliku blokady, co pozwala na uzyskanie identycznego zestawu na drugiej maszynie. Należy traktować to zgłoszenie 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. Deklarowanym celem jest uczynienie umiejętności „śledzonymi, testowalnymi i weryfikowalnymi”. 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 w języku Rust, na podwójnej licencji MIT lub Apache 2.0, w wersji 0.2.2 na dzień 29 lipca 2026. Należy instalować 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, dzięki czemu proces budowania pozostaje stabilny. skillspec --version powinno wyświetlić 0.2.2. Inna wartość oznacza, że w zmiennej PATH wcześniejszy priorytet ma starszy plik binarny.
Praktyka dostawców (Vendor practice). Google opisało sposób budowania umiejętności w google/skills w artykule na temat sposobów budowania, testowania i skalowania umiejętności agentów. Po odrzuceniu kwestii skali, mechanizm ten stanowi standardową ciągłą integrację (CI). Każda umiejętność przechodzi przez lintery sprawdzające metadane frontmatter, liczbę linii, strukturę katalogów oraz nazewnictwo przed scaleniem. Narzędzie sprawdzające linki przerywa budowanie w przypadku każdego adresu URL zwracającego błąd 404, co pozwala wykryć wiarygodnie brzmiące 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 wyznaczonego 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 jeden schemat, a standardowe narzędzie git zapewnia pełną jego obsługę.
- Jedno źródło prawdy. Umiejętność ma dokładnie jedno miejsce przechowywania, a każde repozytorium odwołuje się do tego miejsca zamiast przechowywać kopię.
- Przypięta wersja dla każdego repozytorium. Każdy projekt rejestruje dokładną wersję, z której korzysta, więc aktualizacja stanowi commit w tym projekcie, opatrzony autorem i datą.
- Test dymny dla każdej umiejętności. Jeden uruchamialny test potwierdzający, że umiejętność nadal generuje oczekiwany rezultat.
- Ścieżka przeglądu. Zmiana we współdzielonej umiejętności przechodzi przez proces przeglądu, a każdy odbiorca widzi różnice (diff) przed ich 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 serwera git
Jedno repozytorium przechowuje umiejętności. Nie zawiera ono żadnych innych danych, 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) są oznaczane tagami. Należy używać tagów z adnotacją (annotated tags), ponieważ zawierają one wiadomość oraz datę. Treść wiadomości powinna wyjaśniać powód, dla którego użytkownik końcowy powinien wykonać aktualizację:
git tag -a v1.4.0 -m "api-review: require pagination on list endpoints"
git push origin v1.4.0Jeśli serwerem zdalnym jest Gitea, Forgejo, GitLab lub zwykłe repozytorium (bare repository) dostępne przez SSH na własnym VPS, poniższe zasady pozostają niezmienne. Wszystko opiera się na git oraz dowiązaniach symbolicznych (symlink).
Przypinanie wersji za pomocą git submodule
Podmoduł rejestruje jeden konkretny commit innego repozytorium wewnątrz Twojego repozytorium. Ten zapis stanowi przypięcie (pin). W każdym projekcie korzystającym z podmodułu:
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"Dowiązanie symboliczne (symlink) jest elementem, który umożliwia działanie tego mechanizmu. Wpis umiejętności (skill) 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 dane znajdują się w podmodule w wybranym przez Ciebie commicie.
Sprawdź przypięcie:
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)Wiodący znak - oznacza, że podmoduł nigdy nie został zainicjowany, więc .claude/skills/api-review wskazuje na pusty obiekt, a umiejętność nie ładuje się bez zgłaszania błędów. Napraw to za pomocą git submodule update --init. Wiodący znak + oznacza, że sprawdzony (checked-out) commit różni się od zapisanego, co oznacza, że dany programista korzysta z instrukcji, których nikt inny nie posiada. Nowe klony wymagają git clone --recurse-submodules, a ten wiersz powinien znaleźć się w pliku README, ponieważ zwykłe polecenie clone pozostawia vendor/agent-skills puste i nie wyświetla żadnego błędu.
Aktualizacja jest procesem celowym, co stanowi główny cel 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 to ścieżka przeglądu. Pokazuje on tę samą zmianę, którą zobaczą wszystkie inne repozytoria korzystające z tego modułu, i mieści się w ramach pull requesta.
Przypinanie wersji za pomocą 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 umiejętności:
{
"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ą 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 te parametry, a gdy oba są ustawione, to sha staje się wiążącym przypięciem. Zatem przypięcie do konkretnego commita powinno znaleźć się we wpisie 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 zainstalowanie marketplace, a wtyczka zostanie dla niego włączona bez konieczności korzystania ze strony wiki z instrukcjami. Umiejętności odpowiadają wtedy na /team-skills:api-review, ponieważ umiejętności wtyczek mają przestrzenie nazw oparte 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 monitu 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 z jednym celowym błędem. Asercja sprawdza, czy umiejętność wskazuje ten błąd. jq -e kończy działanie z kodem wyjścia innym niż zero, gdy filtr zwraca null, więc umiejętność, która przestaje wykrywać wprowadzony błąd, powoduje niepowodzenie skryptu. claude kończy działanie z kodem innym niż zero, gdy uruchomienie zakończy się niepowodzeniem, a set -euo pipefail zamienia każde z tych niepowodzeń w wynik negatywny testu.
Model zmienia brzmienie odpowiedzi między uruchomieniami, dlatego nigdy nie należy stosować asercji na całych zdaniach. Należy stosować asercję na identyfikatorze, który umiejętność powinna wyemitować, lub na polu schematu, o który poproszono, utrzymując środowisko testowe w małym rozmiarze, 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 ignorujący zasady użytkownika.
Współdzielona umiejętność jest instrukcją wykonywalną
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 ta 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 wynik zastępuje symbol zastępczy w tekście otrzymywanym przez model. Blok ograniczony trzema znakami odwrotnego apostrofu, po których następuje !, uruchamia w ten sam sposób kilka poleceń. 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 do obszaru roboczego dla danego 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 commitu, 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, nie może zostać nadpisane przez użytkownika. Umiejętności dołączone i zarządzane są wyłączone z tego ustawienia.
Ta sama ostrożność dotyczy tego, co umiejętność odczytuje. Umiejętność, która uruchamia env lub otwiera plik konfiguracyjny, pobiera wszystko, co znajdzie, do kontekstu modelu, co jest błędem opisanym w utrzymywanie sekretów poza uruchamianymi agentami. Umiejętność, która pobiera stronę lub uruchamia zapytanie, stanowi to samo zagrożenie skierowane na zewnątrz, ponieważ pobrany tekst trafia do kontekstu, wyglądając dokładnie tak samo, jak instrukcje, które zostały napisane. Jest to granica, o której warto przeczytać przed skierowaniem agenta na własną instancję SearXNG w celu wyszukiwania w sieci.
Co należy sprawdzić przy zmianie wersji
- Różnice (diff) w każdym ciele
SKILL.md, ponieważ ten tekst stanowi instrukcję, którą będzie wykonywał agent. - Każde podstawienie polecenia (command substitution), gdyż są one uruchamiane na maszynie lokalnej w momencie ładowania umiejętności.
- Każda zmiana w
allowed-tools, ponieważ ta linia nadaje uprawnienia do narzędzi bez dodatkowego monitu. - Testy uruchamiane za danym tagiem. Jeśli współdzielone repozytorium wykonuje własne testy typu smoke w ramach CI, tag, do którego przypięto wersję, powinien posiadać status pomyślnego przebiegu (green run).
Recenzent, który nie jest w stanie przeanalizować całego diffa w ciągu 10 minut, ma do czynienia z umiejętnością, która stała się zbyt rozbudowana. Należy ją podzielić. Ta sama zasada dotyczy dokumentacji repozytorium, z której korzystają agenci: trwałe reguły 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ąskie, konkretne procedury.
Gdy zmiana modelu lub narzędzia powoduje awarię 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, przez co 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 wyboru umiejętności w agencie zmienia sposób ich dobierania, przez co description, który wcześniej wygrywał dopasowanie, przestaje to robić.
Dlatego w tym układzie testy typu smoke test mają kluczowe znaczenie. Należy uruchamiać testy każdej umiejętności zgodnie z harmonogramem oraz przy każdym wypchnięciu zmian. Google z tego powodu uruchamia cotygodniowe zadania ewaluacyjne dla całej biblioteki, a cotygodniowe zadanie cron na małym VPS jest wystarczające dla zespołu posiadającego dziesięć umiejętności. Jest to jedyny sposób, aby dowiedzieć się o awarii, zanim dowie się o niej 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 odpornych na zmianę modelu to osobna dziedzina, omówiona w zapewnienie działania umiejętności na dowolnym modelu.
FAQ
Jak udostępnić jedną umiejętność agenta w wielu repozytoriach?
Umieść umiejętność w dedykowanym repozytorium git, oznaczaj wydania tagami i spraw, aby każdy projekt korzystający z niej odwoływał się do konkretnego taga zamiast kopiować plik. Działają dwa mechanizmy. Moduł git submodule rejestruje dokładny commit, a dowiązanie symboliczne (symlink) z .claude/skills/<name> do moduł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. Moduł git submodule z założenia przypina konkretny commit. Na rynku wtyczek Claude Code źródło wtyczki akceptuje ref dla gałęzi lub taga oraz sha dla konkretnego 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 pomię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 konkretnego 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 wykonywanie podstawień poleceń.
Czy współdzielona umiejętność będzie działać w agentach innych 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 miejscach, dlatego należy ich unikać w umiejętnościach przeznaczonych do szerokiego udostępniania.