Claude Code skills i pluginy: jeden zestaw w każdym repo

Skille w Claude Code to pliki SKILL.md z instrukcjami, które agent ładuje, gdy zadanie ich wymaga. Plugin pakuje skille, agentów i hooki w jedną całość, którą instaluje się w wielu repozytoriach. Nasze dostarczamy jako jeden plugin, wizrd (nasz wewnętrzny plugin i CLI dla Claude Code, niepubliczne), włączony w commitowanych ustawieniach repozytorium, a walidator w CI oblewa repozytorium, gdy skill jest zepsuty.

Ten układ wyrósł z bałaganu: kopie tych samych skilli w kilku repozytoriach, każda trochę inna. Poniżej opisujemy, jak działają skille i pluginy, jak ładujemy jeden plugin wszędzie i co się po drodze zepsuło.

Czym są skille i pluginy w Claude Code?

Skill to folder z jednym plikiem, SKILL.md. Na górze jest frontmatter z name i description, pod nim instrukcje. Dokumentacja Claude Code mówi to wprost: opisy skilli są ładowane do kontekstu, żeby Claude wiedział, co jest dostępne, a pełna treść skilla ładuje się dopiero przy użyciu. Skill można też uruchomić samemu jako /name.

Plugin to katalog ze skillami, agentami, hookami lub serwerami MCP, który Claude Code instaluje i ładuje jako jedną całość. Jego manifest leży w .claude-plugin/plugin.json. Skille z pluginu dostają przestrzeń nazw, więc nasz skill do review uruchamia się jako /wizrd:review i nigdy nie koliduje z własnym /review projektu.

Gdzie należy każdy element:

Najważniejsza jest ostatnia kolumna. Skill mówi agentowi, jak dobrze wykonać zadanie. Do niczego nie zmusza. To, co musi obowiązywać, trafia do hooka, reguły lintera albo CI.

Dlaczego wszystkie nasze skille włożyliśmy do jednego pluginu?

Nasze repozytorium firmowe zawiera wszystkie repozytoria klientów i usług jako submoduły. Sesja uruchomiona w repozytorium klienta nie widziała skilli firmy, bo Claude Code szuka skilli projektu tylko do korzenia repozytorium, w którym jest.

Skille były więc kopiowane. Kilka repozytoriów klientów miało własne wersje plan, execute i review. Gdy je porównaliśmy, każda kopia rozjechała się z pozostałymi. Nikt tego nie postanowił. Po prostu się stało, jedna mała poprawka za drugą, w jednym repozytorium, a w następnym już nie.

Rozwiązaniem nie była większa dyscyplina. Był nim jeden plugin, który ładuje się wszędzie. Od tego czasu sesja w repozytorium firmy, klienta czy usługi dostaje te same skille, agentów i hooki. Zmiana trafia jednym PR-em, a stare kopie usunęliśmy w towarzyszących PR-ach.

Jak jeden plugin ładuje się w każdym repozytorium?

Plugin potrzebuje domu, czyli marketplace. To po prostu plik .claude-plugin/marketplace.json, który wymienia pluginy i skąd pobrać każdy z nich. Nasz wymienia jeden plugin, czyli samo repozytorium:

{
  "name": "digitaliko",
  "plugins": [{ "name": "wizrd", "source": "./" }]
}

Repozytorium, które z niego korzysta, włącza plugin w swoim commitowanym .claude/settings.json. Na przykład gdy repo pluginu jest submodułem w plugins/wizrd:

{
  "enabledPlugins": { "wizrd@digitaliko": true },
  "extraKnownMarketplaces": {
    "digitaliko": { "source": { "source": "directory", "path": "plugins/wizrd" } }
  }
}

Kolejność, którą powtórzylibyśmy:

Hooki wędrują tak samo. Nasz plugin zawiera powitanie w SessionStart i dwa hooki PreToolUse na Bash: jeden blokuje przypisywanie autorstwa AI w commitach i PR-ach, drugi blokuje pushe, których operator nie może robić. Ich ścieżki zaczynają się od ${CLAUDE_PLUGIN_ROOT}, więc działają w każdym repozytorium. Dlaczego to ważne, opisujemy w artykule Hooki Claude Code, które po cichu nic nie robią.

Czego potrzebuje skill, żeby działał w zespole?

Mniej, niż początkowo myśleliśmy. Prawdziwy frontmatter z naszego pluginu, ze skróconym opisem:

---
name: issue
description: Create GitHub issues at the right level following the canonical labels and issue-body spec. Triggers on /wizrd:issue, gh issue, file issue, create issue, log a task.
allowed-tools: Bash, Read
audience: both
---

Ciężar niosą trzy pola:

• description z prawdziwymi słowami kluczowymi. Na podstawie tej linii model decyduje, czy załadować skill. „Pomaga z issue” ładuje się losowo. Słowa, które ludzie naprawdę wpisują, ładują go wtedy, kiedy trzeba.
• audience: human, agent albo both. To nasze własne pole, nie pole Claude Code. Skill, który agent uruchamia sam, nigdy nie może czekać na człowieka. Nasz walidator ostrzega, gdy skill oznaczony jako agent lub both zadaje pytanie w okienku albo czeka na zatwierdzenie. Agent pyta wtedy na GitHubie.
• Jasne nazwy. Dwa nasze skille różniły się kiedyś jedną literą i robiły przeciwne rzeczy. Zmieniliśmy im nazwy.

Przez jakiś czas wymagaliśmy też stałych sekcji w każdym skillu: playbooka, bramki jakości, uprawnień decyzyjnych. Głównie powtarzały treść. Zrezygnowaliśmy z tego wymogu i przycięliśmy skille do instrukcji, które zmieniają zachowanie. Teraz walidator wymaga tylko name, description i audience.

Co się po drodze zepsuło?

Większość po cichu. Rzeczy przechodziły, choć już niczego nie sprawdzały.

• Zmiana nazwy, która na zawsze przechodziłaby przez CI. Gdy plugin dał nam przestrzeń nazw, stary prefiks w nazwie każdego skilla stał się zbędny, więc go usunęliśmy. Nasza kontrola odwołań do usuniętych skilli miała ten prefiks wpisany na sztywno w wyrażeniu regularnym. Gdybyśmy jej nie poprawili, po zmianie nazwy niczego by nie znajdowała i świeciłaby na zielono na zawsze.
• Walidator uznawał żywe skille za nieaktualne. Budował listę skilli z lokalnego folderu. Po przeniesieniu do pluginu repozytorium klienta, które wspominało plan albo review, nie miało lokalnie czego dopasować, i jego CI zrobiło się czerwone. Rozwiązaniem było czytanie także skilli z samego pluginu.
• Skille, których nikt nie używał. Niektóre skille od miesięcy się nie uruchamiały. Każdy wciąż siedział w kontekście w każdej turze, bo nazwy i opisy skilli z pluginu ładują się zawsze. Usunęliśmy je. Trzy warianty jednego skilla stały się jednym skillem z trybami, a nasz własny skill do pisania skilli ustąpił wbudowanemu skill-creatorowi.

Większość tych poprawek to były usunięcia. To wzorzec, który widzimy stale: wspólny plugin uwidacznia to, co zbędne, bo teraz każdy nosi to w każdej sesji.

Osobiste czy wspólne: które skille należą do pluginu?

Nie każdy skill musi być wspólny. To, jak jedna osoba lubi pracować, może zostać w jej własnym ~/.claude/skills/. To, od czego zależy cały zespół, należy do pluginu: planowanie, review, zakładanie issue, kroki, przez które przechodzi wydanie dla klienta.

Nasz plugin jest wewnętrzny, więc nie da się go zainstalować. Nasz publiczny Claude Code production starter nie ma skilli. Zawiera warstwę pod nimi: reguły dla agenta, hooki i bramkę w CI. Od tego byśmy zaczęli.

Co z tego Państwa zespół już ma?

Co trafia do reguł obok skilli, opisujemy w artykule CLAUDE.md i AGENTS.md: reguły dla kodu AI w zespole.

Chcą Państwo jednej wspólnej konfiguracji dla agentów zespołu?

Skille, hooki, reguły i CI konfigurujemy bezpośrednio w repozytoriach zespołu w ramach AI-native SDLC dla zespołów deweloperskich. Państwa zespołowi brakuje raczej rąk niż reguł? Proszę zobaczyć seniora dla Państwa zespołu. Większość naszego kodu pisze AI. Senior sprawdza każdą zmianę i odpowiada za produkcję. Od 2023 roku dostarczyliśmy ponad 15 projektów produkcyjnych.

Odezwiemy się w ciągu dwóch dni roboczych z kilkoma pytaniami o Państwa pracę. Potem ustalimy, co zrobimy najpierw.

Jeśli wolą Państwo najpierw porozmawiać, proszę zarezerwować 15-minutową rozmowę wstępną.

Ile kopii tego samego skilla żyje dziś w Państwa repozytoriach?

Najczęstsze pytania

Czym są skille w Claude Code?

Skill to folder z plikiem SKILL.md: frontmatter z nazwą i opisem, a pod nim instrukcje. Claude Code trzyma opis w kontekście, a pełne instrukcje ładuje dopiero wtedy, gdy zadanie ich wymaga albo gdy uruchomią Państwo skill jako /nazwa.

Czym różni się skill od pluginu?

Skill to jeden zestaw instrukcji. Plugin to katalog, który pakuje skille, agentów, hooki i serwery MCP w jedną całość, z manifestem w .claude-plugin/plugin.json. Skille z pluginu mają przestrzeń nazw, więc nasze uruchamia się jako /wizrd:review.

Jak udostępnić skille Claude Code zespołowi?

Umieścić je w pluginie, wpisać plugin do marketplace i włączyć go w commitowanym .claude/settings.json każdego repozytorium. Wszyscy mają tę samą wersję, a zmiana trafia wszędzie jednym PR-em zamiast do kopii, które się rozjeżdżają.

Czy wiele skilli spowalnia Claude Code?

Każdy skill, który model może wywołać sam, trzyma swoją nazwę i opis w kontekście w każdej turze. To kosztuje tokeny, nawet gdy nic się nie uruchamia. Usuwamy skille, których nikt nie używa, a opisy trzymamy krótkie i konkretne.

Czy skill powinien zastąpić hooki albo kontrole w CI?

Nie. Skill to instrukcje, którymi agent może się kierować. To, co musi obowiązywać, trafia do hooka, reguły lintera, testu albo CI, gdzie agent nie może tego pominąć.