Skill token-discipline dla Claude Code: uczciwy benchmark

Spędzamy dni na mierzeniu cudzych skilli Claude i w telemetrii wciąż wracał ten sam wzorzec: sesje nie drożały przez to, że Claude pisał długie odpowiedzi. Drożały przez to, co Claude czytał. Całe pliki otwierane po to, żeby znaleźć jedną funkcję. Pliki odczytywane ponownie zaraz po udanej edycji, „tak na wszelki wypadek". 16 000-rekordowy JSON wciągnięty do kontekstu, jakby to był wpis na blogu.

Zbudowaliśmy więc skill, który atakuje właśnie tę stronę rachunku, opublikowaliśmy go na licencji MIT i zrobiliśmy to, czego wymagamy od każdego skilla na naszej liście: przetestowaliśmy go względem baseline'u w kontrolowanych przebiegach i opublikowaliśmy wyniki — łącznie z tymi, które mu nie schlebiają.

Skill nazywa się token-discipline. Jest darmowy: github.com/Skillproofdev/token-discipline.

Luka we wszystkich przetestowanych skillach tokenowych

Zanim napisaliśmy pierwszą linijkę, przejrzeliśmy osiem opublikowanych skilli i protokołów do oszczędzania tokenów — od zestawu reguł ograniczających verbosity outputu z 5800 gwiazdkami, który dominuje w tej niszy, przez skille „awaryjne", uruchamiane przy 40% zapełnienia kontekstu, po protokoły obiecujące 76–93% oszczędności bez żadnego mechanizmu w tle i bez telemetrii, którą dałoby się znaleźć.

Niemal wszystkie mają ten sam martwy punkt: optymalizują output. Wywalają preambułę, skracają odpowiedzi, przestają powtarzać plan. To realna oszczędność, ale to mniejsza połowa rachunku. W sesjach agentowych — czyli gdy Claude Code realnie pracuje w repozytorium — dominuje input: każdy odczyt pliku, każdy wynik wyszukiwania, każdy output narzędzia trafia do kontekstu i jest wysyłany ponownie przy każdym kolejnym zapytaniu.

Trzy techniki po stronie inputu nie pojawiły się jako twarda reguła w żadnym z ośmiu:

1. Najpierw szukaj, potem czytaj. Najpierw zlokalizuj za pomocą grep/glob, potem odczytaj tylko trafiony fragment. Nigdy nie otwieraj całego pliku, żeby coś w nim znaleźć.
2. Grupuj niezależne wywołania narzędzi. Jeśli trzy odczyty od siebie nie zależą, powinny trafić do jednej wiadomości. Każda dodatkowa tura to ponowna opłata za tokeny myślenia i narracji między wywołaniami.
3. Ufaj stanowi, który już masz. Po własnej udanej edycji nie czytaj pliku ponownie, żeby to zweryfikować — narzędzie do edycji głośno zgłasza błąd, gdy coś pójdzie nie tak. Ponowne odczyty są od zmian z zewnątrz, nie od twoich własnych.

Ta trójka stała się rdzeniem skilla. Wokół niej jest jeszcze sześć reguł: czytaj fragmenty zamiast całych plików, odpytuj duże JSON-y i logi przez python albo jq zamiast je otwierać, podsumowuj długie outputy i je odrzucaj, deleguj szerokie przeszukiwanie do subagentów, dbaj o to, żeby kontekst był przyjazny cache'owi (nietknięty stabilny prefiks — własny blog inżynieryjny Anthropic nazywa prompt caching pojedynczym czynnikiem kosztowym o najwyższej dźwigni), i tak, zwięzły output też. Dziewięć reguł, każda sformułowana jako twarda zasada z podaną alternatywą, więc przestrzeganie jej nigdy nie kosztuje poprawności.

Jak to benchmarkowaliśmy

Ten sam protokół co w naszej serii Skill Bench: ten sam model, ten sam prompt, jedna zmienna. Każde zadanie uruchamialiśmy dwa razy — jeden agent Claude Sonnet bez skilla, drugi, który najpierw czytał SKILL.md i miał polecenie ściśle się go trzymać. Suma tokenów agenta ze skillem zawiera koszt przeczytania samego skilla. Poligonem był nasz własny kod: strona na Astro z około 9000 linii szablonów plus zbiór danych JSON na 16 682 rekordy — na tyle duży, że niezdyscyplinowane czytanie realnie boli.

Pięć par zadań, dobranych tak, żeby objąć całe spektrum od trywialnych po naprawdę wieloetapowe:

Task	Baseline	With skill	Δ
Q&A po kodzie — 8 pytań z różnych podsystemów	88 419	71 636	−19.0%
Edycja wielu plików — 4 skoordynowane zmiany	68 219	54 637	−19.9%
Śledzenie kodu — jednorazowe zadanie	53 986	52 850	−2.1%
Przegląd audytowy — jednorazowe zadanie	44 691	44 705	+0.0%
Streszczenie dużego JSON-a — jednorazowe zadanie	42 726	45 164	+5.7%

Co naprawdę mówią te liczby

Przy realnej, wieloetapowej pracy skill oszczędza około 20%. Q&A po kodzie z ośmioma pytaniami to najbliższe temu, czym jest normalna sesja robocza — prześledź przepływ autoryzacji, wyjaśnij webhooka, znajdź logikę sortowania. Agent bazowy odpowiedział poprawnie, ale po drodze czytał hojnie i weryfikował bez potrzeby, redundantnie. Zdyscyplinowany agent odpowiedział na te same pytania, z tą samą trafnością (sprawdziliśmy każde odwołanie file:line z obu przebiegów), zużywając 16 783 tokenów mniej.

Ciekawszym wynikiem jest edycja wielu plików. Cztery skoordynowane zmiany w czterech plikach. Agent bazowy skończył, a potem — cytując jego własny raport — „zweryfikował, ponownie czytając edytowane fragmenty". Sam ten nawyk to jedna piąta rachunku. Agent ze skillem wprowadził te same cztery zmiany, pominął rytualne ponowne odczyty i zgłosił, że skończył. Porównaliśmy oba drzewa robocze (diff): edycje były w obu przypadkach równoważne i poprawne. Nic nie zostało stracone przez zaufanie, że narzędzie zgłosi błąd, gdy coś pójdzie nie tak — bo właśnie do tego służą narzędzia.

Przy trywialnych, jednorazowych zadaniach wychodzi na zero — i publikujemy to mimo wszystko. Zadanie streszczenia JSON-a ze skillem kosztowało w rzeczywistości 5.7% więcej. Dwa powody, oba pouczające. Po pierwsze, sam skill kosztuje jakieś 1400 tokenów do przeczytania, a zadanie kończące się w dwóch wywołaniach narzędzi nie ma na czym zamortyzować tego narzutu. Po drugie, model obecnej generacji już dobrze radzi sobie z łatwymi zadaniami: agent bazowy rzucił jedno spojrzenie na JSON z 16 682 rekordami i sięgnął po python zamiast go otwierać. Bez żadnego skilla. Dyscyplina się opłaca tam, gdzie możliwy jest brak dyscypliny — długie sesje, wiele plików, narastający kontekst — a nie tam, gdzie nie ma czego marnować.

Jeśli twoje sesje to głównie jednolinijkowe zadania, skill ma na to gotową odpowiedź: destylowany blok na 60 tokenów, który wklejasz do CLAUDE.md zamiast instalować cały skill. Działa cały czas, kosztuje mniej więcej tyle, co to zdanie, a jeden uniknięty odczyt całego pliku zwraca się z nawiązką. (Zbudowaliśmy kalkulator dokładnie tego stałego podatku — matematyka dla opisów wyzwalaczy działa też dla bloków reguł.)

Dziewięć reguł w skrócie

Pełny SKILL.md ma ~1400 tokenów i mieści się na jednym ekranie; a oto jego kształt:

1. Najpierw szukaj, potem czytaj. Najpierw grep, potem odczyt trafienia ±30 linii. Czytanie więcej niż ~200 linii wymaga powodu, który potrafisz podać w jednym zdaniu.
2. Czytaj wycinek, nie cały plik. Offset+limit dla wszystkiego, co długie; python/jq dla wszystkiego, co strukturalne. Duży JSON to baza danych, nie dokument.
3. Grupuj niezależne wywołania narzędzi. Jedna wiadomość, kilka wywołań, zawsze gdy outputy nie zasilają kolejnych inputów.
4. Ufaj stanowi, który już masz. Bez weryfikacyjnych odczytów po własnych edycjach; bez ponownego uruchamiania wyszukiwań, których wyniki są już w kontekście.
5. Nie cytuj kodu z powrotem. Odwołuj się przez file:line. Wklejaj tylko to, co człowiek musi zobaczyć, żeby podjąć decyzję.
6. Streszczaj, potem odrzucaj. Po długim outpucie narzędzia zachowaj 2–5 faktów i nigdy nie proś ponownie o ten sam log.
7. Deleguj ciężkie przeszukiwanie. Szerokie przeglądy trafiają do subagenta; ciężkie odczyty umierają w jego kontekście, nie w twoim.
8. Dbaj o to, żeby kontekst był przyjazny cache'owi. Nietknięty stabilny prefiks; dopisuj, nie przepisuj; pilnuj TTL cache'u.
9. Dyscyplina outputu. Najpierw odpowiedź, bez preambuły, bez esejów w diffach.

Do tego dochodzi punkt kontrolny samoaudytu (trzy pytania przed każdym większym ponownym odczytem) i wyraźna lista czego nie robić, bo token-skill, który każe agentowi pomijać niezbędną weryfikację, niczego nie oszczędza — tylko odracza dodatkową robotę. Jeśli prawdziwe polowanie na buga wymaga całego pliku, reguła mówi: przeczytaj go, podając powód.

Gdzie to się mieści w większym obrazie kosztów

Reguły takie jak te to zmienna połowa rachunku. Połowa stała — preambuła serwerów MCP na 30 000 tokenów, rozdęte pliki CLAUDE.md i opisy skilli działających cały czas, wysyłane dosłownie przy każdym zapytaniu — to inny problem z innymi rozwiązaniami, i zwykle większy zysk dla ciężkich użytkowników. Ten audyt opisaliśmy w tekście Jak zmniejszyć zużycie tokenów Claude; oba teksty się uzupełniają: napraw koszty stałe raz, a potem niech token-discipline utrzymuje koszty zmienne płaskie przez całą sesję.

A jeśli zastanawiasz się, czy skille w ogóle oszczędzają tokeny: nasza seria Skill Bench zmierzyła cztery popularne skille i okazało się, że w większości nie — kosztują dodatkowe tokeny, a w zamian kupują jakość i dyscyplinę. token-discipline zbudowaliśmy specjalnie po to, żeby był wyjątkiem, i nawet wtedy zarabia na siebie tylko przy pracy wieloetapowej. To uczciwa granica, a wolimy wyznaczyć ją sami, niż żebyś znalazł ją na swoim rachunku.

Instalacja

git clone https://github.com/Skillproofdev/token-discipline ~/.claude/skills/token-discipline

Zrestartuj Claude Code. Skill uruchamia się na frazy „reduce token usage", „work token-efficiently", skargi na limit kontekstu i pytania o koszty — albo zastosuj go w całej sesji przez blok CLAUDE.md, który jest w środku.

FAQ

Czy to zastępuje skille do verbosity outputu? Nie — zawiera ich rdzeń (Reguła 9) i dokłada stronę inputu, którą one pomijają. Jeśli już masz zestaw reguł na zwięzły output, token-discipline pokrywa się z nim na jednej regule z dziewięciu.

Czy przez to Claude będzie działał niedbale? Benchmark mówi, że nie: edycja wielu plików wyszła równoważnie i poprawnie po obu stronach, a lista „czego nie robić" w skillu wprost chroni weryfikację, która jest naprawdę potrzebna. Reguły zastępują odczyty rytualne, nie niezbędne.

Dlaczego sam skill jest taki krótki? Bo skill do oszczędzania tokenów, który kosztuje tysiące tokenów wczytania na sesję, byłby autoparodią. SKILL.md ma ~1400 tokenów, wczytywanych na żądanie; blok CLAUDE.md działający cały czas ma ~60.

Mam subskrypcję Pro/Max, nie API. Czy to ma znaczenie? Tak, w walucie limitów: te same tokeny, którymi rozlicza się użytkowników API, zjadają twój limit użycia. Dwadzieścia procent mniej tokenów w sesjach roboczych to proporcjonalnie więcej pracy, zanim uderzysz w sufit.

Czy benchmark był naciągany pod korzystny wynik? Pięć zadań zaprojektowaliśmy, zanim uruchomiliśmy którykolwiek z wariantów, i opublikowaliśmy oba wyniki, w których skill przegrał. Surowa telemetria — liczby tokenów i wywołań narzędzi dla każdego przebiegu — jest w README repozytorium.