Skills, których mój agent nie widział

Miałem zainstalowane 84 skills i zakładałem, że wszystkie 84 działają. Pięć z nich nie działało. swiftui, testing-philosophy, typeset, web-performance oraz update-shortcuts-guide docierały do modelu jako same nazwy, bez dołączonego opisu, choć ich pliki na dysku zawierały całkowicie poprawne opisy. Do skilla bez opisu nie da się skierować routingu, ponieważ opis jest sygnałem routingu. Tych pięć nigdy nie mogło się uruchomić automatycznie i nic nigdzie mi tego nie zasygnalizowało. Żadnego błędu, żadnego ostrzeżenia, żadnej linii logu. Znalazłem je przypadkiem, a jedynym powodem, dla którego udało mi się udowodnić przyczynę, było to, że poprawka odwróciła zjawisko na moich oczach. {.answer-block}

W skrócie

• Opisy skills ładują się do kontekstu w każdej turze i dzielą jeden stały budżet znaków. Po jego przekroczeniu opisy znikają po cichu.¹²
• Miałem zainstalowane 84 skills, z czego 82 miały opis, łącznie 21,848 znaków. Pięć dotarło z obecną nazwą i brakującym opisem. Na dysku każdy z tych pięciu liczył od 206 do 336 znaków.
• Żaden atrybut pliku nie tłumaczył, które pięć zostało usuniętych. Długość opisu, rozmiar pliku, format YAML, rozbieżność między name a katalogiem oraz data modyfikacji nakładały się w obu grupach, usuniętej i zachowanej.
• Przepisałem 74 opisy, schodząc do 9,885 znaków łącznie. Wszystkie pięć skills pojawiło się ponownie w trakcie sesji, w tej samej rozmowie, z nienaruszonymi opisami. Hipoteza, interwencja, potwierdzenie.
• Dokładny budżet nie jest udokumentowany i pozostaje przedmiotem sporu. Anthropic ma otwarte zgłoszenia mówiące, że ułamek liczony jest względem stałej bazy 200K i pomija rozszerzenie kontekstu do 1M.³⁴
• Reguła przepisywania, dzięki której wszystko się zmieściło: jedynym zadaniem opisu jest odpowiedź na pytanie, kiedy należy to wywołać. Procedura, filozofia i ścieżki plików należą do treści, która ładuje się dopiero przy wywołaniu.

Awaria bez komunikatu o błędzie

Większość błędów w harnessie sama się zgłasza. Hook kończy się kodem różnym od zera, serwer MCP odmawia startu, wywołanie narzędzia zwraca ślad stosu. Budżet opisów nie robi nic takiego. Po cichu podaje modelowi listę krótszą niż ta na dysku, a każdy późniejszy objaw wygląda na problem modelu, a nie na problem hydrauliki.

Zauważyłem to, czytając własne okno kontekstu, a nie system plików. Przeglądając listę skills, pięć pozycji miało nazwę i nic po niej. Każda inna pozycja miała nazwę i zdanie. Sięgnąłem do plików:

swiftui                    HAS  322 chars on disk -> DROPPED in context
testing-philosophy         HAS  291 chars on disk -> DROPPED in context
typeset                    HAS  248 chars on disk -> DROPPED in context
web-performance            HAS  206 chars on disk -> DROPPED in context
update-shortcuts-guide     HAS  336 chars on disk -> DROPPED in context

Konsekwencja jest gorsza niż powolny albo błędny skill. Agent decyduje o wywołaniu skilla, czytając jego opis. Usunięcie opisu nie pogarsza routingu, tylko go likwiduje. Skill jest zainstalowany, poprawny i nieosiągalny. swiftui to mój skill ze wzorcami iOS 26, co oznacza, że każda uruchomiona przeze mnie sesja Swift leciała bez niego.

Anthropic ma otwarte zgłoszenia opisujące tę samą awarię, w tym jedno zatytułowane „Skill description budget silently truncates routing information, causing skill routing failures”.² To zachowanie jest więc znanym błędem, a nie lokalną wadą konfiguracji. Dobrze było się o tym dowiedzieć i nie pomogło mi to znaleźć, które z moich skills ucierpiały.

Odrzucanie łatwych odpowiedzi

Kuszące było zgadnięcie mechanizmu i naprawienie go. Najpierw jednak spróbowałem obalić własne przypuszczenia, bo „pięć skills jest zepsutych” i „pięć skills jest zepsutych z tego powodu” to bardzo różne twierdzenia.

Gdyby jakaś właściwość na poziomie pliku wskazywała skilla do usunięcia, grupa usunięta powinna różnić się od zachowanej w czymś mierzalnym. Porównałem je:

| Właściwość | Usunięte (5) | Zachowane (77) | |—|—| | Średnia długość opisu | 280 znaków | 266 znaków | | Średni rozmiar pliku | 9,106 bajtów | 7,608 bajtów | | Opis YAML w formie skalara blokowego | 2 z 5 | 30 z 77 | | name inne niż katalog | 1 z 5 | 4 z 77 | | Data modyfikacji | od stycznia do lipca | od stycznia do lipca |

Nic ich nie rozdzielało. Usunięte opisy nie były najdłuższe, pliki nie wyróżniały się rozmiarem, styl YAML był mieszany w obu grupach, a daty modyfikacji obejmowały ten sam przedział. Pozycja alfabetyczna również zawiodła: skills sortowane po swiftui zachowały swoje opisy.

W tym momencie uczciwe stanowisko brzmiało tak: mam powtarzalny objaw i żadnego mechanizmu. Tak też to zapisałem i zamiast teorii zacząłem szukać testu.

Test

Jeśli liczy się suma całkowita, to jej obniżenie powinno przywrócić usunięte opisy, niezależnie od tego, które pliki zostaną skrócone. Taka prognoza jest falsyfikowalna i tania.

Przepisałem 74 opisy, sprowadzając sumę z 21,848 znaków do 9,885. Pięć wcześniej niewidocznych skills wróciło z dołączonymi opisami, w tej samej sesji, bez restartu.

To cały eksperyment. Jedna prognoza, jedna interwencja, jedno potwierdzenie. Usuwanie zależy od rozmiaru zbiorczego, a nie od jakiejkolwiek właściwości pojedynczego pliku, i właśnie dlatego żaden atrybut pojedynczego pliku nie mógł odróżnić obu grup.

Błąd, który nie zostawia śladu, wciąż zostawia kontrfaktyczne porównanie. Jeśli przyczyny nie da się znaleźć przez oględziny awarii, warto zmienić jedną zmienną i sprawdzić, czy awaria podąża za nią.

Chcę być precyzyjny co do tego, czego nie ustaliłem. Nie znam dokładnego budżetu i nie zamierzam publikować liczby, której nie potrafię udokumentować. Oficjalna dokumentacja pomija ten limit.⁵ Pomiary społeczności umieszczają praktyczny pułap w okolicach 15,500 do 16,000 znaków i wskazują około 109 znaków narzutu na pozycję, pochodzącego ze znaczników XML, nazwy skilla i pola lokalizacji, czego surowe liczenie znaków opisu w ogóle nie obejmuje.⁶ Przy 84 skills sam ten narzut daje około 9,156 znaków. Równocześnie współpracownicy Anthropic zgłaszają, że ułamek budżetu liczony jest względem stałej bazy 200K i pomija rozszerzenie kontekstu do 1M, więc dwie sesje na tej samej maszynie mogą otrzymać różne budżety.³⁴

Moje pierwsze podejście do opisania tego odkrycia głosiło, że moja konfiguracja przekracza budżet o 119%. Pomnożyłem niezweryfikowane założenie (1% okna 1M) przez realny pomiar i uzyskałem pewną siebie liczbę, pod którą nic nie stało. Zaobserwowane fakty się bronią: 21,848 znaków usunęło pięć opisów, a 9,885 nie usunęło żadnego. Procent się nie obronił i nigdy nie powinien był zostać napisany.

Jedynym zadaniem opisu jest routing

Wycięcie 12,000 znaków brzmi destrukcyjnie. Takie nie było, bo większość tego, co żyło w tych opisach, nigdy nie wykonywała pracy routingu.

Oto, co reklamował mój skill jiro, w 686 znakach:

Filozofia rzemiosła shokunin dla jakości kodu i zawodowej dumy. Aktywuje się przy wdrażaniu funkcji, refaktoryzacji kodu, pisaniu testów, przeglądaniu pracy oraz przy dowolnych nietrywialnych zmianach w FastAPI/Python, Swift/SwiftUI, frontendach HTMX i kodzie infrastruktury. Osadza trzy podstawowe filozofie: Shokunin (doskonałość w niewidocznych detalach), Omotenashi (służba przez rzemiosło), Rick Rubin (twórcze przewodzenie i destylacja). Centralny punkt decyzyjny: Evidence Gate (wytwórz dowód jakości, a nie odczucia na jej temat). Używać przy: budowaniu funkcji, refaktoryzacji, testowaniu, przeglądaniu kodu, naprawianiu błędów oraz każdej pracy, w której przed zgłoszeniem ukończenia wymagany jest dowód jakości.

Około 500 z tych znaków wyjaśnia, co skill zawiera. Nic z tego nie pomaga zdecydować, czy go otworzyć. Zamiennik ma 126 znaków:

Standardy rzemiosła i dowodów dla jakości kodu. Używać przy wdrażaniu, refaktoryzacji, testowaniu, przeglądaniu i naprawianiu błędów.

Te same słowa wyzwalające, to samo zachowanie routingu, jedna piąta kosztu. Filozofia nie zniknęła; żyje w treści, która ładuje się dopiero wtedy, gdy skill faktycznie się uruchamia. Płacenie za nią w każdej turze nie dawało nic.

Wzorzec powtórzył się w całym zestawie. Dziewięć skills update-*-guide niosło 3,024 znaki niemal identycznego szablonowego tekstu o skanowaniu źródeł, synchronizowaniu kopii i uruchamianiu tłumaczeń. Po sprowadzeniu do około 115 znaków każdy z nich wciąż routuje poprawnie, bo tym, co je odróżnia, jest to, który przewodnik aktualizują, a nie wspólny pipeline.

Pracę wykonały trzy reguły:

1. Zachować wyzwalacz, wyciąć wyjaśnienie. Nazwy, polecenia slash i słowa, które użytkownik faktycznie wpisałby, zostają. Opisy wewnętrznej procedury odchodzą.
2. Ścieżki plików należą do treści. Ścieżka nie pomoże modelowi zdecydować, kiedy coś wywołać.
3. Wspólny szablonowy tekst to czysty narzut. Jeśli dziewięć skills mówi to samo zdanie, to zdanie nie odróżnia żadnego z nich.

Drugi podatek: opisy, które działają, choć nikt ich nie wywołał

Przycinanie odsłoniło subtelniejszy koszt. Jedenaście moich opisów, łącznie 3,808 znaków, niosło język rozkazujący: ALWAYS, NEVER, MUST, PROACTIVELY, BEFORE. distribute mówił NEVER. no-shortcuts mówił ALWAYS. git-custody mówił BEFORE.

Te słowa siedzą w kontekście w każdej turze, niezależnie od tego, czy skill kiedykolwiek się uruchomi. Czyta się je jak instrukcje, ponieważ są napisane jak instrukcje, a model nie ma wiarygodnego sposobu, by traktować opis jak bezwładny tekst katalogowy, a identycznie sformułowaną instrukcję systemową jak wiążącą.

Najnowsze prace nazywają ten efekt. „The Regression Tax”, zmierzony na około 6,000 przebiegów w dwóch benchmarkach automatyzacji biurowej i trzech stosach harnessów, identyfikuje osmozę opisów skills: skill zmienia zachowanie agenta wyłącznie przez swoją obecność w kontekście, nawet jeśli nigdy nie zostanie wywołany.¹ Główny wniosek pracy mówi, że najlepsze skills wygrywają dzięki mniejszej regresji, a nie większym zyskom, oraz że skills przeinwestowują w wskazówki proceduralne, a niedoinwestowują ugruntowanie i weryfikację.

Dowód produkcyjny pojawił się przed teorią. Anthropic wycofał automatyczną aktywację wbudowanych skills /verify i /code-review w wersji v2.1.215, pozostawiając wyłącznie wywołanie jawne.⁷ Dwa wydania później /deep-research też przestał wywoływać się sam.⁸ To ciężkie skills, których nieproszone uruchomienia kosztowały więcej, niż przynosiły: osmoza zaobserwowana w praktyce przez samego dostawcę i naprawiona przez usunięcie aktywacji, a nie przez przepisanie opisu.

Zbyt duży opis kosztuje więc podwójnie. Zjada budżet, którego inne skills potrzebują do routingu, i wywiera presję na zachowanie, o którą nikt nie prosił. Oba koszty przypadają na tury, w których skill nie wnosi nic.

Niewygodna część: treść też może nie rządzić

„Przenieś to do treści” to rada, której właśnie udzieliłem, i niesie ona założenie warte wypowiedzenia na głos: że procedura ładowana przez agenta przy wywołaniu naprawdę rządzi tym, co agent robi. Nowe prace benchmarkowe sugerują, że to założenie jest słabsze, niż brzmi.

HANDBOOK.md przetestował dokładnie to. Sześćdziesiąt pięć zadań, dokumenty polityk liczące od 20 do 124 stron, agenci pracujący z pocztą, czatem, kalendarzami i handlem w symulowanych firmach oraz 824 programistyczne kryteria oceny. Najlepsza z trzydziestu konfiguracji modeli zdała 36.2% prób, a większość czołowych konfiguracji zeszła poniżej 25%.⁹

Nazwane tryby porażki są tu najistotniejsze. Agenci pozwalają, by prawdopodobnie brzmiące żądanie ze środowiska przebiło obowiązującą politykę. Wykonują wymagane sprawdzenie, a następnie działają wbrew jego wynikowi. Gubią szczegóły reguł na długich horyzontach. Żadna z tych porażek nie jest porażką wyszukiwania; dokument był dostępny przez cały czas.

Uczciwa wersja mojej reguły jest więc węższa niż „opisy routują, treść wyjaśnia”. Wyniesienie procedury z opisu nadal jest słuszne, bo odzyskuje budżet potrzebny innym skills do routingu i powstrzymuje niewywołany tekst przed sterowaniem zachowaniem. Oba te zyski są realne i żaden nie zależy od tego, czy treść dobrze rządzi. Czego to nie daje, to pewności, że przeniesiona procedura zostanie wykonana. Podręcznik na 124 strony i treść SKILL.md licząca 3,000 słów leżą na tej samej krzywej.

Praktyczny wniosek: długość treści warto traktować jak koszt, a nie jak darmowe miejsce parkingowe. Jeśli jakaś reguła naprawdę musi obowiązywać, opis jest dla niej złym miejscem, a długa treść tylko odrobinę lepszym. Egzekwowanie należy do czegoś deterministycznego (hook, reguła uprawnień, test), a nie do prozy, którą model ma pamiętać, robiąc przy tym coś innego.

Audyt własnej konfiguracji

Warto zacząć wewnątrz sesji. Polecenie /context raportuje, czy jakieś skills zostały wykluczone.⁵ Jeśli zgłosi wykluczenia, problem jest potwierdzony i diagnoza dobiega końca.

Powód, dla którego sam nie zacząłem od tego miejsca, jest pouczający: moje pięć skills nie było wykluczonych, docierały z nienaruszoną nazwą i usuniętym opisem, a to awaria cichsza niż brakująca pozycja i może nie ujawniać się tak samo. Mimo wszystko należy zweryfikować to względem systemu plików. Sprawdzenie nie wymaga narzędzi poza powłoką:

python3 - <<'PY'
import os, re, glob
rows = []
for f in glob.glob(os.path.expanduser('~/.claude/skills/*/SKILL.md')):
    name = os.path.basename(os.path.dirname(f))
    fm = re.match(r'^---\s*\n(.*?)\n---\s*\n', open(f, encoding='utf-8', errors='replace').read(), re.S)
    if not fm:
        continue
    d = re.search(r'^description:\s*(.*?)(?=\n[a-zA-Z_-]+:|\Z)', fm.group(1), re.S | re.M)
    if not d:
        continue
    desc = ' '.join(d.group(1).split()).strip('"\'').lstrip('|').strip()
    rows.append((len(desc), name))
rows.sort(reverse=True)
print(f'{len(rows)} skills, {sum(r[0] for r in rows)} description chars')
for length, name in rows[:15]:
    print(f'  {length:4d}  {name}')
PY

Następnie należy porównać wynik z tym, co model faktycznie otrzymał. Różnica między jednym a drugim to całe odkrycie. Jeśli skill pojawia się w kontekście z nazwą i bez zdania po niej, ten skill jest zainstalowany i nieosiągalny.

Z audytu wynikają trzy nawyki:

Budżetować każdy nowy skill, nie tylko te długie. Narzut na pozycję towarzyszy każdemu skillowi niezależnie od długości opisu, więc dziesiąty skill o 90 znakach kosztuje więcej niż 90 znaków.

Ponownie przeliczać po dodaniu skills. Nie da się podać bezpiecznego marginesu, ponieważ pułap nie jest udokumentowany i według zgłoszeń zmienia się w zależności od sposobu liczenia ułamka.³⁴ Empiryczne sprawdzenie bije wyliczoną wartość zapasu opartą na założeniu, a to dokładnie ten błąd, który popełniłem.

Zrobić kopię przed przycinaniem. Większość moich katalogów ze skills nie była śledzona przez git, a siedem było dowiązaniami symbolicznymi do katalogu, który w ogóle nie był repozytorium, więc git add odrzucił je komunikatem „beyond a symbolic link”. Najpierw zapisałem każdy oryginalny opis do pliku JSON. Kontrola wersji, której się nie zweryfikowało, nie jest kopią zapasową.

Najważniejsze wnioski

• Skill bez opisu nie jest osłabiony, jest nieosiągalny. Opis niesie całą decyzję routingu.
• Awaria jest cicha z założenia. Żadnego błędu, ostrzeżenia ani logu. Najpierw /context i ostrzeżenia o wykluczeniach, potem porównanie listy z kontekstu z systemem plików, bo usunięty opis jest cichszy niż brakująca pozycja.
• Usuwanie napędza rozmiar zbiorczy, a nie właściwości pojedynczych plików. Żaden atrybut pojedynczego pliku nie przewidywał, które skills stracą opisy.
• Kiedy oględziny zawodzą, trzeba interweniować. Nie potrafiłem znaleźć mechanizmu, badając samą awarię. Zmiana sumy i obserwacja, jak awaria się odwraca, udowodniła go w jednym kroku.
• Opisy routują; treść wyjaśnia. Wszystko, co w opisie nie pomaga zdecydować, kiedy wywołać, jest opłacane w każdej turze i nic nie przynosi.
• Tryb rozkazujący w opisach działa na odbiorcę bez wywołania. ALWAYS i NEVER sterują zachowaniem prosto z katalogu, i właśnie to jest zmierzony efekt osmozy.¹
• Nie należy publikować procentu, którego nie da się udokumentować. Moje własne pierwsze podejście pomnożyło realny pomiar przez zgadnięty budżet i dało pewną siebie, błędną liczbę.

Często zadawane pytania

Dlaczego mój skill w Claude Code się nie aktywuje?

Warto sprawdzić, czy model w ogóle widzi jego opis. Opisy skills ładują się do kontekstu w każdej turze i dzielą stały budżet znaków, a jego przekroczenie po cichu usuwa opisy, bez błędu, bez ostrzeżenia i bez linii logu. Pięć z moich 84 skills docierało do modelu jako same nazwy, choć ich pliki na dysku miały całkowicie poprawne opisy. Do skilla bez opisu nie da się skierować routingu.¹²

Jaki jest budżet opisów skills w Claude Code?

Dokładny budżet nie jest udokumentowany i pozostaje przedmiotem sporu, a ja nie zamierzam publikować liczby, której nie potrafię udokumentować. To, co zmierzyłem: 21,848 znaków opisów usunęło pięć opisów, a 9,885 znaków nie usunęło żadnego. Pomiary społeczności umieszczają praktyczny pułap w okolicach 15,500 do 16,000 znaków przy około 109 znakach narzutu na pozycję, a współpracownicy Anthropic zgłaszają, że ułamek budżetu liczony jest względem stałej bazy 200K.³⁴⁶

Jak sprawdzić, które skills straciły swoje opisy?

Zacząć wewnątrz sesji od /context, które raportuje, czy jakieś skills zostały wykluczone. Potem i tak zweryfikować to względem systemu plików, bo moje pięć nie było wykluczonych: docierały z nienaruszoną nazwą i usuniętym opisem, a to awaria cichsza niż brakująca pozycja. Wystarczy zsumować znaki opisów z frontmattera plików SKILL.md i porównać tę listę z tym, co faktycznie pokazuje kontekst.⁵

Co należy do opisu skilla, a co do jego treści?

Jedynym zadaniem opisu jest odpowiedź na pytanie, kiedy skill ma zostać wywołany. Zostawić słowa wyzwalające, nazwy i polecenia slash, które użytkownik faktycznie wpisałby, a procedurę, filozofię i ścieżki plików przenieść do treści, która ładuje się dopiero przy wywołaniu. Mój opis jiro zszedł z 686 znaków do 126 przy tym samym zachowaniu routingu, bo około 500 z tych znaków wyjaśniało jedynie, co skill zawiera.

Czy opisy skills wpływają na zachowanie nawet wtedy, gdy skill nigdy się nie uruchamia?

Tak, i to jest drugi podatek. Jedenaście moich opisów niosło ALWAYS, NEVER, MUST, PROACTIVELY i BEFORE, słowa, które siedzą w kontekście w każdej turze i czyta się je jak instrukcje, bo są napisane jak instrukcje. „The Regression Tax” nazywa ten efekt osmozą opisów skills: skill zmienia zachowanie agenta wyłącznie przez swoją obecność w kontekście, nawet jeśli nigdy nie zostanie wywołany.¹

Źródła