SSD Nodes Learn Hosting plans →
Przewodniki Matt ConnorAutor: Matt Connor

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ąć polegać na ich wspólnym źródle. Należy utrzymywać jedno repozytorium umiejętności, oznaczać je tagami i pozwolić każdemu projektowi przypiąć konkretną wersję. Następnie należy dodać testy typu smoke 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 elementów: współdzielonego źródła prawdy, przypiętej wersji dla każdego repozytorium, testu typu smoke dla każdej umiejętności oraz ścieżki weryfikacji. Poniższa treść wyjaśnia cel każdego z tych elementów, funkcjonalności narzędzi wydawanych w 2026 roku oraz sposób budowy całego systemu na własnym zdalnym serwerze git, bez udziału zewnętrznych hostów git czy rejestrów pakietów. Wyjątkiem są testy typu smoke. Uruchamiają one Claude Code, który wysyła każde żądanie do API modelu, więc ten krok nadal odbywa się poza serwerem.

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, należy najpierw 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 znajdują się umiejętności i dlaczego ich udostępnianie jest trudne

Claude Code wczytuje umiejętności między innymi z poniższych lokalizacji, a dokumentacja umiejętności wymienia każdą z tych ścieżek.

  • .claude/skills/<skill-name>/SKILL.md wewnątrz zarządzanego katalogu ustawień to lokalizacja korporacyjna. Jest wczytywana dla każdego użytkownika na maszynach, na których wdrożyła ją organizacja.
  • ~/.claude/skills/<skill-name>/SKILL.md to lokalizacja osobista. Jest wczytywana we wszystkich Twoich projektach i w żadnym innym.
  • .claude/skills/<skill-name>/SKILL.md to poziom projektu. Jest wczytywana dla każdego, kto pobierze to repozytorium.
  • <plugin>/skills/<skill-name>/SKILL.md jest dostarczana wewnątrz wtyczki. Jest wczytywana wszędzie tam, gdzie wtyczka jest włączona.

Claude Code wczytuje również umiejętności z zagnieżdżonych katalogów projektów, katalogów dostarczonych za pomocą --add-dir oraz umiejętności włączonych dla Twojego konta claude.ai.

Poziom projektu jest najbardziej użyteczny dla zespołu, ponieważ jest on zatwierdzony w repozytorium i każdy, kto je sklonuje, otrzymuje te umiejętności. To również tutaj zaczynają się problemy. Umiejętność w .claude/skills/ należy do jednego repozytorium. Jeśli posiadasz osiem repozytoriów, umiejętność musi zostać skopiowana osiem razy.

Frontmatter nie oferuje w tym zakresie żadnej pomocy. 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, name

Zwróć uwagę na to, czego brakuje: nie ma klucza version. Wersję można zapisać w metadata, ale specyfikacja nie definiuje żadnego mechanizmu przypinania zależności ani aktualizacji. Jest to uzasadnione, ponieważ umiejętność jest dokumentem, a nie pakietem. Oznacza to jednak, że wersjonowanie musi pochodzić z 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 wydane w 2026 roku

Obecnie pojawia się kilka odpowiedzi na te wyzwania, jednak brak jest zgody co do miejsca przechowywania wersji.

Pliki blokad (Lockfiles). Narzędzie wiersza poleceń skills od Vercel Labs (vercel-labs/skills, licencja MIT, wersja 1.7.2 na dzień 9 października 2026) instaluje umiejętności (skills) z repozytorium git do katalogu oczekiwanego przez agenta; narzędzie obsługuje układ plików dla ponad siedemdziesięciu agentów. npx skills add <repo> służy do instalacji, npx skills update do aktualizacji, a npx skills list wyświetla stan posiadanych zasobów. Narzędzie utrzymuje dwa pliki blokad. Globalny plik w ~/.agents/.skill-lock.json rejestruje instalacje użytkownika. Od wersji 1.4.1 (20 lutego 2026) instalacja w zakresie projektu tworzy również skills-lock.json w katalogu głównym projektu; kod źródłowy narzędzia wskazuje, że plik ten powinien być dodawany do systemu kontroli wersji. npx skills experimental_install przywraca umiejętności projektu na podstawie tego pliku. Zgłoszenie 283, postulujące komendę skills install do przywracania globalnego pliku blokad na innej maszynie, zostało zamknięte jako nieplanowane 5 listopada 2026; opiekun projektu wskazuje, że jest to tożsame z żądaniem zawartym w zgłoszeniu 549. Oba zgłoszenia należy traktować jako raport o stanie prac. Plik blokad dla projektu istnieje. W wydanej wersji 1.8.1 komenda przywracania jest nadal oznaczona w pomocy jako eksperymentalna, jednak npx skills install bez wskazania źródła również przywraca plik blokad projektu.

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, aby umiejętności były „możliwe do śledzenia, testowania i weryfikacji”. skillspec doctor <path> raportuje, w którym miejscu agent prawdopodobnie przerwie wątek. skillspec boundary map <path> wyświetla zawartość umiejętności, a skillspec boundary assess <path> raportuje zasięg jej działania, z uwzględnieniem oceny ryzyka. Jest to biblioteka Rust, dostępna na podwójnej licencji MIT lub Apache 2.0. Wersja 0.2.2 została opublikowana 29 lipca 2026 i na dzień 10 października 2026 pozostaje najnowszą wersją w serwisie crates.io. Należy instalować przypiętą wersję zamiast najnowszej:

cargo install skillspec --version 0.2.2 --locked
skillspec --version

Od czasu wydania Cargo 1.100 w dniu 12 listopada 2026, cargo install domyślnie korzysta z dołączonego pliku blokad, a --locked jest operacją pustą (no-op). skillspec --version powinno wypisać 0.2.2. Inna liczba oznacza, że w zmiennej PATH pierwszeństwo ma starszy plik binarny.

Praktyki dostawców. 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 kwestii skali, mechanizm okazuje się standardową ciągłą integracją (CI). Każda umiejętność przechodzi przez lintery sprawdzające metadane frontmatter, liczbę linii, układ katalogów i nazewnictwo przed scaleniem. Weryfikator linków przerywa budowanie w przypadku każdego adresu URL zwracającego błąd 404, co pozwala wykryć nieistniejące linki wygenerowane przez agenta. Autorzy muszą dostarczyć zestaw promptów ewaluacyjnych oraz rubrykę oceniania 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 zobowiązany do naprawy 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ę.

  1. Jedno źródło prawdy. Umiejętność ma dokładnie jedną lokalizację, a każde repozytorium odwołuje się do niej zamiast przechowywać kopię.
  2. 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ą.
  3. Test dymny dla każdej umiejętności. Jeden uruchamialny test potwierdzający, że umiejętność nadal generuje oczekiwany wynik.
  4. Ś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.md

Wydania (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.0

Jeś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 status

Poprawny 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ą 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, a w Claude Code v2.1.324 lub nowszym, pełny mały skrót commit SHA; nie akceptuje ono oddzielnego pola sha. Źródło wtyczki wewnątrz katalogu akceptuje oba te parametry, a gdy oba są ustawione, sha stanowi wiążące przypięcie. Przypnij katalog poprzez ref w źródle marketplace, a wtyczkę poprzez sha wewnątrz wpisu w katalogu. Nazwy typów również się różnią. Wewnątrz katalogu url oznacza repozytorium git do sklonowania. W źródle marketplace url oznacza bezpośredni link do pliku marketplace.json, natomiast repozytorium git to git.

Każde repozytorium korzystające z wtyczek deklaruje marketplace w swoim zatwierdzonym pliku .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "acme-agents": {
      "source": {
        "source": "git",
        "url": "https://git.example.com/team/agent-skills.git",
        "ref": "v1.4.0"
      }
    }
  },
  "enabledPlugins": {
    "team-skills@acme-agents": true
  }
}

Claude Code rejestruje marketplace dla członka zespołu, gdy ten zaakceptuje okno dialogowe zaufania obszaru roboczego dla folderu projektu, bez konieczności korzystania ze strony wiki z instrukcjami. Wpis w katalogu wskazuje na adres URL git, a nie na ścieżkę relatywną, więc sama wtyczka nie instaluje się wyłącznie na podstawie ustawień repozytorium. Każdy członek zespołu uruchamia raz claude plugin install team-skills@acme-agents --scope project; do tego momentu Claude Code zgłasza, że wtyczka jest włączona w ustawieniach projektu, ale nie jest zainstalowana. Umiejętności odpowiadają następnie 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 i zaktualizowaniu przypięć w katalogu oraz repozytoriach korzystających z wtyczek, użytkownicy odświeżają je 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łana przez użytkownika umiejętność działa w tym środowisku: umieść /skill-name w ciągu znaków promptu, a zostanie on rozwinięty 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/null

fixtures/orders-api.md to krótki plik z jednym celowym błędem. Asercja zakłada, że umiejętność wskaże ten błąd z nazwy. jq -e kończy działanie z kodem niezerowym, gdy filtr wygeneruje null, więc umiejętność, która przestaje wykrywać zasiany błąd, powoduje niepowodzenie skryptu. claude kończy działanie z kodem niezerowym w przypadku niepowodzenia uruchomienia, 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 claude -p ładuje ten sam kontekst, co sesja interaktywna, w tym hooki, wtyczki i CLAUDE.md z maszyny, na której jest uruchamiany, więc osobista konfiguracja członka zespołu może zmienić wynik. Tryb bare pomija automatyczne wykrywanie z wyjątkiem umiejętności w .claude/skills/ w katalogu dostarczonym jawnie za pomocą --add-dir; pomija on umiejętność projektową, którą tutaj testujesz, więc załaduj ją jawnie. Tryb bare nie odczytuje również loginu subskrypcji, więc najpierw ustaw 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 json

Wtyczka załadowana za pomocą --plugin-dir pobiera swoją nazwę z .claude-plugin/plugin.json, a bez tego manifestu jest nazywana na podstawie swojego katalogu. Zatwierdź plugin.json z "name": "team-skills" obok katalogu w repozytorium umiejętności, w przeciwnym razie powyższe polecenie musi wywołać /agent-skills:api-review.

Dzięki --output-format stream-json zdarzenie system/init raportuje, które wtyczki zostały załadowane, i zawiera tablicę plugin_errors dla tych, które nie zostały załadowane. Otwiera ono strumień, chyba że zdarzenia startowe wystąpią wcześniej. Należy przerwać zadanie CI w przypadku niepustego plugin_errors. 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ść jest wykonywalną instrukcją

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 odczyta cokolwiek. 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 backtick, po których następuje !, uruchamia kilka poleceń w ten sam sposób. Nikt nie jest pytany o zgodę na żadną z tych czynności w czasie wykonywania. Claude Code sprawdza każde polecenie pod kątem reguł uprawnień. Poza trybem automatycznym, polecenie niedozwolone przez te reguły przerywa działanie umiejętności, chyba że umiejętność wstępnie zatwierdzi je za pomocą drugiej funkcji opisanej poniżej. Reguły odmowy i zapytania nadal nadpisują to wstępne zatwierdzenie. Czytanie współdzielonej umiejętności oznacza czytanie jej podstawień poleceń.

Po drugie, frontmatter może wstępnie zatwierdzać narzędzia. allowed-tools przyznaje wymienione narzędzia bez monitu o uprawnienia w turze, która wywołała umiejętność. Zaufanie do obszaru roboczego nie ogranicza tego przyznania: Claude Code stosuje allowed-tools umiejętności projektowej nawet w -p uruchomionym w folderze, któremu nikt nie zaufał. Dokumentacja Claude Code jasno określa konsekwencje: umiejętność może przyznać sobie szeroki dostęp do narzędzi, więc przed uruchomieniem Claude Code w repozytorium należy przejrzeć allowed-tools znajdujących się w nim umiejętności. Organizacja może zablokować to pole w umiejętnościach projektowych i osobistych, ustawiając allowManagedPermissionRulesOnly w ustawieniach zarządzanych, co wymaga Claude Code w wersji 2.1.282 lub nowszej.

Dlatego aktualizację umiejętności należy traktować dokładnie tak samo, jak aktualizację zależności. Należy przypinać wersje konkretnym commitem, wszędzie tam, gdzie mechanizm na to pozwala, ponieważ tag może zostać przeniesiony, a branch zmienia się z definicji. Na zabezpieczonej maszynie "disableSkillShellExecution": true w ustawieniach zastępuje każde podstawienie polecenia dosłownym tekstem [shell command execution disabled by policy] zamiast jego uruchomienia, a zastosowane poprzez ustawienia zarządzane 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 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 udostępnić jedną umiejętność agenta w kilku 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 (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, dzięki czemu można ustalić, które instrukcje wygenerowały dany przebieg 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 z założenia przypina dokładny commit. W rynku wtyczek Claude Code źródło wtyczki akceptuje ref dla gałęzi lub taga oraz sha dla dokładnego commita, przy czym sha ma pierwszeństwo, gdy oba są obecne. Samo źródło rynku akceptuje ref dla gałęzi, taga lub, w Claude Code w wersji 2.1.324 lub nowszej, pełnego zapisu SHA commita małymi literami. Preferuj przypięcie do commita, ponieważ tag może zostać przesunięty po jego zweryfikowaniu.

Co powinien sprawdzać test dymny (smoke test) umiejętności?

Sprawdzaj elementy stabilne. Uruchom umiejętność w trybie nieinteraktywnym względem zestawu danych testowych (fixture) zawierającego znany błąd, a następnie sprawdź, czy w danych wyjściowych pojawia się konkretny identyfikator, na przykład identyfikator reguły, którą umiejętność powinna zgłosić. Żądanie ustrukturyzowanego wyjścia za pomocą --output-format json i --json-schema sprawia, że sprawdzenie jest precyzyjne, a jq -e przerywa skrypt, gdy wartość jest nieobecna. Nigdy nie sprawdzaj całych zdań, ponieważ model zmienia sformułowania odpowiedzi między uruchomieniami.

Czy bezpieczne jest instalowanie współdzielonej umiejętności z repozytorium innego zespołu?

Traktuj to jak zależność kodu, ponieważ jest to wykonywalna instrukcja. SKILL.md może uruchamiać polecenia powłoki w czasie ładowania poprzez formę podstawiania poleceń !, a pole allowed-tools we frontmatterze może wstępnie zatwierdzać narzędzia bez pytania o zgodę. Czytaj różnice (diff) przy każdej aktualizacji, przypinaj do dokładnego commita zamiast do gałęzi i preferuj źródło kontrolowane przez własny zespół. Na zarządzanych maszynach "disableSkillShellExecution": true w ustawieniach blokuje uruchamianie podstawień poleceń w umiejętnościach użytkownika, projektu, wtyczek oraz dodatkowych katalogów; umiejętności dołączone i zarządzane są wyłączone z tego ograniczenia.

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 zmian. Klucze specyficzne dla danego środowiska oraz funkcje treści wykraczające poza specyfikację są ignorowane lub odrzucane w innych miejscach, więc unikaj ich w umiejętnościach, które mają być szeroko udostępniane.

Czy ten artykuł był przydatny?