Pluginy dla agentów AI — kompletny poradnik: co zawierają, jak zbudować własny i kiedy to przerost formy

Czego się nauczysz

• Czym jest plugin w świecie agentów AI — jedną paczką, która instaluje naraz skille, subagentów, hooki i połączenia z zewnętrznymi systemami, i dlaczego to nie to samo co „wtyczka” w Chrome czy Figmie.
• Co dokładnie może siedzieć w środku — dziesięć rodzajów komponentów, od skilli po serwery językowe i monitory w tle, oraz który z nich naprawdę Ci się przyda.
• Jak czytać i pisać plugin.json — pole po polu, z regułami ścieżek, które wywracają najwięcej pierwszych pluginów.
• Jak to instalować i rozdawać — w terminalu, w aplikacji Claude, w zespole przez repozytorium, w organizacji przez ustawienia zarządzane, w marketplace publicznym i prywatnym.
• Kiedy plugin jest przerostem formy — i kiedy wystarczy zwykły skill albo katalog .claude/.
• Dlaczego plugin to poważna decyzja bezpieczeństwa — bo instalujesz kod, który wykonuje się z Twoimi uprawnieniami.
• Kompletny przepis na własny plugin i własny marketplace, z gotowym przykładem do skopiowania.

Poradnik jest podzielony na pięć części. Każda jest samodzielna — możesz zacząć od tej, która Cię interesuje.

Jeśli nie wiesz, czym jest skill, zacznij od poradnika o plikach SKILL.md — plugin bez tej wiedzy będzie pustym pudełkiem.

---

Część 1. Czym jest plugin i po co komu paczka

Definicja w jednym zdaniu

Plugin to katalog z manifestem plugin.json, który jedną instalacją dokłada agentowi komplet rozszerzeń: skille, subagentów, hooki, serwery MCP i kilka rzeczy mniej oczywistych.

(Ściśle rzecz biorąc sam manifest jest opcjonalny, jeśli komponenty leżą w domyślnych katalogach — ale przy dystrybucji i tak go potrzebujesz, choćby dla nazwy i wersji.)

Nazwa myli. „Plugin” kojarzy się z wtyczką do przeglądarki albo do Figmy — czymś, co dokłada guzik do interfejsu. Tutaj chodzi o coś innego: plugin to sposób pakowania i dystrybucji konfiguracji agenta. Nie dokłada przycisku. Dokłada agentowi umiejętności, wiedzę, dostępy i automatyzacje — i robi to tak, żeby dało się je wersjonować i rozdać całemu zespołowi.

Problem, który to rozwiązuje

Załóżmy, że w zespole wypracowaliście dobry zestaw: trzy skille z waszymi procedurami, subagent do przeglądu kodu, hook blokujący commit bez numeru zgłoszenia i serwer MCP do wewnętrznego API. Wszystko siedzi w katalogu .claude/ jednej osoby.

Bez pluginów rozdanie tego wygląda tak: „skopiuj sobie te pliki, hooka wklej do ustawień, a MCP skonfiguruj według instrukcji na wiki”. Po miesiącu połowa zespołu ma wersję sprzed trzech poprawek, jedna osoba źle wkleiła hooka, a nowa osoba nie ma nic.

Plugin zamienia to w claude plugin install <nazwa>@<marketplace>. Aktualizacja to podbicie numeru wersji. Wycofanie zmiany to instalacja starszej wersji. Review nowej procedury to zwykły pull request.

Co może zawierać plugin

To najbardziej niedoceniana część systemu. Plugin nie jest tylko workiem na skille:

Komponent	Co dokłada	Katalog
Skille	procedury i wiedzę ładowane na żądanie	skills/
Komendy	to samo, ale jako pojedyncze pliki .md (starszy format)	commands/
Subagenci	wyspecjalizowanych agentów z własnym promptem i zestawem narzędzi	agents/
Hooki	skrypty odpalane na zdarzeniach sesji	hooks/hooks.json
Serwery MCP	dostęp do zewnętrznych systemów, skonfigurowany z góry	.mcp.json
Serwery LSP	inteligencję kodu: diagnostykę po każdej edycji i nawigację po symbolach	.lsp.json
Monitory	procesy w tle, które obserwują logi albo status i zgłaszają zdarzenia	monitors/monitors.json
Style wyjścia	zmianę sposobu, w jaki agent formułuje odpowiedzi	output-styles/
Motywy	kolorystykę interfejsu	themes/
Workflow	skrypty orkiestrujące pracę wielu agentów	workflows/
Binarki	pliki wykonywalne dopisane do PATH, gdy plugin jest włączony	bin/

Do tego settings.json w katalogu głównym pluginu. Uwaga: obsługiwane są tam dokładnie dwa klucze — agent i subagentStatusLine; resztę agent po cichu ignoruje. Kluczem agent plugin aktywuje jednego ze swoich subagentów jako główny tryb pracy, wraz z jego promptem systemowym, ograniczeniami narzędzi i modelem.

Dwa z tych komponentów są mocniejsze, niż się wydaje na pierwszy rzut oka:

Serwery LSP dają agentowi to, co daje Ci edytor: po każdej edycji pliku agent dostaje z serwera językowego listę błędów i ostrzeżeń, więc widzi błąd typu albo brakujący import od razu, bez uruchamiania kompilatora. Jeśli sam wprowadził błąd, poprawia go w tej samej turze. Oficjalny marketplace ma gotowe pluginy LSP dla jedenastu języków: TypeScript, Python, Rust, Go, Java, C/C++, C#, Kotlin, Lua, PHP i Swift. Binarkę serwera trzeba doinstalować samemu; plugin konfiguruje tylko połączenie.

Monitory to procesy w tle uruchamiane automatycznie razem z pluginem. Każda linia, którą taki proces wypisze na standardowe wyjście, trafia do agenta jako powiadomienie. tail -F logs/error.log jako monitor oznacza, że agent dowiaduje się o błędzie w momencie, w którym ten błąd się pojawia — bez pytania i bez odpytywania.

Plugin a zwykły katalog .claude/

Te same skille, subagentów i hooki możesz mieć bez żadnego pluginu — po prostu w katalogu .claude/ projektu albo w swoim katalogu domowym. Różnica jest w dystrybucji:

	Katalog .claude/	Plugin
Nazwa skilla	/deploy	/moj-plugin:deploy
Zasięg	ten projekt albo Twój komputer	wszędzie, gdzie plugin jest włączony
Aktualizacja	ręczne kopiowanie	podbicie wersji, plugin update
Wersjonowanie	git repozytorium projektu	własny numer wersji i tagi
Hooki	w settings.json	w hooks/hooks.json pluginu
Serwery MCP	konfiguracja użytkownika	w paczce, gotowe do użycia
Nadaje się do	Twoich rzeczy i eksperymentów	dzielenia się

Praktyczna rada: zaczynaj w .claude/, pakuj do pluginu dopiero wtedy, gdy chcesz to komuś dać. Iterowanie na luźnych plikach jest szybsze, a konwersja to później kwestia przeniesienia katalogów i dopisania manifestu.

Przestrzeń nazw — drobiazg, który ratuje przed chaosem

Skille z pluginu są zawsze poprzedzone jego nazwą: /moj-plugin:code-review. To wygląda na uciążliwość, dopóki nie zainstalujesz trzech pluginów, z których każdy ma skilla o nazwie review. Wtedy okazuje się, że to jedyny powód, dla którego wszystkie trzy mogą działać jednocześnie.

Skille z Twojego katalogu .claude/ nie kolidują z pluginami, bo nie mają prefiksu — obie wersje są dostępne obok siebie.

Z subagentami jest inaczej i to częsta pułapka: agent o tej samej nazwie w .claude/agents/ projektu albo użytkownika nadpisuje agenta z pluginu. Jeśli po instalacji pluginu jego agent zachowuje się nie tak, jak powinien, sprawdź, czy nie masz lokalnej definicji o tej samej nazwie.

Koszt kontekstu — patrz na to przed instalacją

Plugin to nie darmowy dodatek. Każdy skill dokłada swoją nazwę i opis do kontekstu na starcie sesji. Każdy serwer MCP dokłada definicje swoich narzędzi — a te potrafią być znacznie droższe niż skille. Menedżer pluginów pokazuje szacowany koszt kontekstu przed instalacją i listę tego, co dokładnie zostanie dodane. Zajrzyj tam, zanim klikniesz „instaluj”. Przy pluginach z marketplace’ów lokalnych i niestandardowych tych danych może nie być — zamiast listy komponentów zobaczysz informację, że zostaną wykryte dopiero przy instalacji.

Warto też co jakiś czas przejrzeć listę zainstalowanych. Menedżer sam grupuje pod nagłówkiem „nieużywane od dawna” te pluginy, po które nie sięgałeś od co najmniej dwóch tygodni i dziesięciu sesji. To zwykle najprostsza oszczędność kontekstu, jaką da się zrobić w minutę. Do tej grupy nigdy nie trafiają pluginy zarządzane przez organizację ani takie, które wnoszą motyw, styl wyjścia, monitor albo workflow — bo one działają bez wywoływania.

---

Część 2. Anatomia pluginu

Struktura katalogu

moj-plugin/
├── .claude-plugin/
│   └── plugin.json          # manifest — JEDYNY plik w tym katalogu
├── skills/
│   ├── przeglad-kodu/
│   │   └── SKILL.md
│   └── raport/
│       ├── SKILL.md
│       └── scripts/generuj.py
├── agents/
│   └── audytor-bezpieczenstwa.md
├── hooks/
│   └── hooks.json
├── .mcp.json                # serwery MCP
├── .lsp.json                # serwery językowe
├── monitors/monitors.json   # procesy w tle
├── output-styles/
├── bin/                     # binarki dopisywane do PATH
├── scripts/                 # skrypty dla hooków
├── settings.json            # domyślne ustawienia
├── README.md
└── CHANGELOG.md

Błąd numer jeden przy pierwszym pluginie: wrzucenie skills/, agents/ albo hooks/ do środka katalogu .claude-plugin/. Tam należy wyłącznie plugin.json. Wszystkie katalogi komponentów siedzą w katalogu głównym pluginu. Jeśli plugin się ładuje, ale nie widzisz jego skilli — sprawdź to najpierw.

Katalogiem głównym pluginu jest jego własny folder: ten, który przekazujesz przy testowaniu albo który zawiera .claude-plugin/plugin.json. Nigdy nie jest nim ~/.claude/.

Manifest plugin.json

Wymagane jest dokładnie jedno pole: name. Cała reszta jest opcjonalna — ale w praktyce warto wypełnić kilka więcej.

{
  "name": "narzedzia-zespolu",
  "displayName": "Narzędzia zespołu",
  "version": "1.4.0",
  "description": "Procedury wydania, przegląd kodu i dostęp do wewnętrznego API",
  "author": { "name": "Zespół Platformy", "email": "[email protected]" },
  "homepage": "https://wiki.firma.pl/claude",
  "repository": "https://github.com/firma/claude-narzedzia",
  "license": "MIT",
  "keywords": ["wydanie", "przeglad-kodu", "wewnetrzne"]
}

Pole	Rola
name	wymagane, kebab-case; z niego bierze się przestrzeń nazw komponentów
displayName	nazwa wyświetlana w interfejsie; może mieć spacje i wielkie litery
version	przypina plugin do tej wersji — użytkownicy dostaną aktualizację dopiero po jej podbiciu
description	to, co ludzie zobaczą w katalogu pluginów; potraktuj poważnie
author, homepage, repository, license, keywords	metadane do odkrywalności i zaufania
defaultEnabled	ustaw false, jeśli plugin ma się zainstalować wyłączony
dependencies	inne pluginy, których ten wymaga
userConfig	konfiguracja, o którą plugin poprosi użytkownika przy instalacji

Reguły ścieżek — tu ludzie się przewracają

Manifest może wskazywać niestandardowe lokalizacje komponentów. Haczyk polega na tym, że różne pola zachowują się różnie:

• skills — dopisuje do domyślnego skills/. Zawsze skanowany jest też katalog domyślny.
• commands, agents, outputStyles, workflows oraz experimental.themes i experimental.monitors (motywy i monitory są w manifeście polami eksperymentalnymi) — zastępują domyślny katalog. Jeśli ustawisz "agents": "./custom/agents/", domyślny agents/ przestaje być czytany. Chcesz obu? Wypisz oba: "agents": ["./agents/", "./custom/agents/"].
• hooks, mcpServers, lspServers — łączą konfiguracje z wielu źródeł.

Wszystkie ścieżki są względne wobec katalogu głównego pluginu i muszą zaczynać się od ./. Ścieżki bezwzględne nie zadziałają. Jedyny wyjątek: pole skills przyjmuje też ".", czyli sam katalog główny pluginu.

userConfig — pytanie do użytkownika przy instalacji

Jeśli plugin potrzebuje tokenu albo adresu API, nie każ ludziom edytować plików. Zadeklaruj to:

{
  "userConfig": {
    "api_endpoint": {
      "type": "string",
      "title": "Adres API",
      "description": "Adres wewnętrznego API zespołu",
      "required": true
    },
    "api_token": {
      "type": "string",
      "title": "Token API",
      "sensitive": true
    },
    "liczba_watkow": {
      "type": "number", "title": "Liczba wątków",
      "min": 1, "max": 10, "default": 4
    }
  }
}

Typy: string, number, boolean, directory, file. Wartości oznaczone sensitive: true trafiają do pęku kluczy systemu albo do osobnego pliku poświadczeń — zależnie od platformy; zwykłe wartości lądują w ustawieniach użytkownika. Odwołujesz się do nich przez ${user_config.api_token} w konfiguracji MCP i LSP oraz w treści skilli i agentów; w procesach hooków dostępna jest też zmienna środowiskowa CLAUDE_PLUGIN_OPTION_<KLUCZ>. Monitory w tle jako jedyny komponent nie mogą korzystać z ${user_config.*}.

Dwie zmienne, bez których nic nie zadziała

Plugin nie wie, gdzie zostanie zainstalowany. Dlatego nigdy nie wpisuj ścieżek na sztywno — używaj podstawień:

Zmienna	Wskazuje na	Do czego
${CLAUDE_PLUGIN_ROOT}	katalog instalacji pluginu	skrypty, binarki, pliki konfiguracyjne z paczki
${CLAUDE_PLUGIN_DATA}	trwały katalog danych pluginu	zależności, cache, rzeczy generowane — przeżywa aktualizację
${CLAUDE_PROJECT_DIR}	katalog główny projektu	skrypty i konfiguracja specyficzne dla projektu

Różnica między pierwszą a drugą jest istotna. ${CLAUDE_PLUGIN_ROOT} przy aktualizacji pluginu wskaże na nowy katalog — wszystko, co tam wygenerowałeś, przepada. ${CLAUDE_PLUGIN_DATA} zostaje. Tam instalujesz zależności, tam trzymasz środowisko wirtualne Pythona, tam ląduje cache.

{
  "mcpServers": {
    "wewnetrzne-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": { "CACHE_DIR": "${CLAUDE_PLUGIN_DATA}/cache" }
    }
  }
}

Komponenty po kolei

Subagenci

Plik markdown w agents/, z frontmatterem opisującym, czym ten agent jest:

---
name: audytor-bezpieczenstwa
description: Przegląda zmiany pod kątem podatności i wycieków danych
model: sonnet
effort: high
maxTurns: 20
disallowedTools: Write, Edit
skills:
  - narzedzia-zespolu:standardy-bezpieczenstwa
---

Jesteś audytorem bezpieczeństwa. Analizujesz kod, nigdy go nie zmieniasz.
...

Zwróć uwagę na disallowedTools: Write, Edit — audytor, który nie może niczego zmienić, jest po prostu bezpieczniejszy. Pole skills wstępnie ładuje wskazane skille do kontekstu subagenta.

Ze względów bezpieczeństwa subagent z pluginu nie może definiować własnych hooków, serwerów MCP ani trybu uprawnień.

Hooki

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/format.sh" }
        ]
      }
    ]
  }
}

Zdarzenia, na które można się podpiąć, to m.in. SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, Stop i SessionEnd. Typ hooka nie musi być komendą — może być też żądaniem HTTP, wywołaniem narzędzia MCP, promptem albo uruchomieniem agenta.

Plugin jednoskillowy

Jeśli plugin ma dostarczyć dokładnie jeden skill, nie musisz robić katalogu skills/ — wystarczy SKILL.md w katalogu głównym. Nazwę wywołania bierze się wtedy z pola name we frontmatterze.

Plugin w katalogu skilli — najkrótsza droga

Osobny tryb, wart znajomości, bo omija cały narzut z marketplace’em. Dowolny folder w ~/.claude/skills/ (albo .claude/skills/ projektu), który zawiera .claude-plugin/plugin.json, ładuje się automatycznie jako plugin — bez instalacji, bez katalogu, bez niczego. Rusztowanie stawia jedna komenda:

claude plugin init moje-narzedzie --with skills hooks

Dzięki temu pojedynczy folder może wieźć skille razem z hookami i serwerem MCP, czego zwykły skill nie potrafi. Zastrzeżenia dotyczą wyłącznie wariantu projektowego (.claude/skills/ w repo): ładuje się dopiero po zaufaniu katalogowi roboczemu, serwery MCP wymagają wtedy zgody osobno dla każdego, serwery LSP startują dopiero po zaufaniu, a monitory w tle w ogóle się nie ładują. Wariant osobisty w ~/.claude/skills/ nie ma żadnego z tych ograniczeń. Odinstalowanie w obu przypadkach to skasowanie folderu.

---

Część 3. Jak się tego używa

Skąd brać pluginy

Dwa katalogi utrzymuje Anthropic:

• claude-plugins-official — kuratorowany zestaw. Rejestruje się sam przy pierwszym interaktywnym uruchomieniu. Automatyczne aktualizacje są tu domyślnie włączone.
• claude-community — katalog społecznościowy; trafiają tu zgłoszenia zewnętrzne po przejściu automatycznej walidacji i przeglądu bezpieczeństwa. Dodajesz go ręcznie, a każdy plugin jest przypięty do konkretnego commita.

Poza tym marketplace’em może być dowolne repozytorium z plikiem .claude-plugin/marketplace.json — także prywatne, także na GitLabie czy Bitbuckecie.

Co warto znać z oficjalnego katalogu:

• inteligencja kodu — jedenaście pluginów LSP (typescript-lsp, pyright-lsp, rust-analyzer-lsp, gopls-lsp i dalej)
• integracje — github, gitlab, atlassian, linear, asana, notion, figma, slack, sentry, vercel, supabase, firebase
• security-guidance — przegląda każdą zmianę pod kątem typowych podatności i każe je poprawić w tej samej sesji
• commit-commands, pr-review-toolkit, plugin-dev — workflow developerski
• style wyjścia — tryb objaśniający i tryb nauki

3.1. W terminalu (Claude Code)

# dodaj marketplace (GitHub, pełny URL git, ścieżka lokalna albo URL do pliku)
/plugin marketplace add anthropics/claude-plugins-community
/plugin marketplace add https://gitlab.com/firma/pluginy.git#v1.0.0
/plugin marketplace add ./moj-marketplace

# zainstaluj
/plugin install nazwa@marketplace

# zarządzaj
/plugin                    # panel: Discover / Installed / Marketplaces / Errors
/plugin list
/plugin disable nazwa@marketplace
/plugin uninstall nazwa@marketplace
/reload-plugins            # zastosuj zmiany bez restartu

Przy instalacji wybierasz zasięg:

Zasięg	Kto to dostaje	Gdzie się zapisuje
user	Ty, we wszystkich projektach	ustawienia użytkownika
project	wszyscy współpracownicy repozytorium	.claude/settings.json
local	Ty, tylko w tym repozytorium	.claude/settings.local.json
managed	cała organizacja, bez możliwości zmiany	ustawienia zarządzane

Po instalacji przeczytaj podsumowanie. Jeśli mówi Plugin is now active. — gotowe. Jeśli Run /reload-plugins to activate. — uruchom tę komendę. Warto wiedzieć, że przeładowanie ma swój koszt: nowe komponenty muszą się ogłosić, a plugin z serwerami MCP potrafi unieważnić cache promptu, przez co następne żądanie czyta całą rozmowę od nowa.

3.2. W aplikacji Claude (Cowork)

Wersja dla osób, które nie żyją w terminalu. Customize → Plugins, potem Browse plugins. Domyślnie widzisz katalog Anthropic — zestaw zaproponowany na starcie zależy od planu i konfiguracji konta; własne marketplace’y dodajesz adresem repozytorium — wystarczy https://github.com/firma/pluginy albo skrót firma/pluginy. Plugin można też wgrać z pliku.

Po instalacji otwierasz plugin i widzisz jego zawartość: skille i subagenci jako zakładki, konektory i hooki na osobnych stronach. Każdy komponent da się włączyć albo wyłączyć osobno — to przydatne, gdy chcesz z paczki tylko część.

Kilka rzeczy specyficznych dla tej powierzchni:

• Nie wszystkie komponenty działają wszędzie. Dokumentacja Cowork mówi wprost, że pluginy są używane w Cowork i w Claude Code, a nie w zwykłym czacie; centrum pomocy opisuje z kolei, że skille i konektory z pluginu widać także w czacie, a wyszarzone są tylko hooki i subagenci. Bezpieczne założenie: hooki i subagenci to wyłącznie Cowork i Claude Code, reszta bywa dostępna szerzej — sprawdź na swoim koncie.
• Konektory łączą się przez chmurę Anthropic, nie z Twojej sieci lokalnej. Serwer MCP za firmowym firewallem nie będzie osiągalny bez dodatkowej pracy.
• Organizacja może wymusić pluginy. Na planach Team i Enterprise administrator może ustawić plugin jako obowiązkowy — wtedy instaluje się sam i nie da się go usunąć.
• Limity paczki: 200 MB po rozpakowaniu, 5 000 plików na plugin, 500 pluginów na marketplace, 25 marketplace’ów na użytkownika.

3.3. W zespole — przez repozytorium

Najczystszy sposób, żeby nowa osoba dostała komplet narzędzi razem z git clone. W pliku .claude/settings.json projektu:

{
  "extraKnownMarketplaces": {
    "narzedzia-firmy": {
      "source": { "source": "github", "repo": "firma/claude-pluginy" }
    }
  },
  "enabledPlugins": {
    "standard-backend@narzedzia-firmy": true
  }
}

Marketplace dodaje się sam, gdy tylko członek zespołu zaufa katalogowi repozytorium. Uwaga na jedno: samo dodanie marketplace’u nie instaluje pluginów pochodzących ze źródeł zewnętrznych. Taki plugin zgłosi się jako niezainstalowany i pokaże komendę do uruchomienia. To celowe — repozytorium nie może po cichu ściągnąć na Twój komputer kodu z obcego repo.

3.4. W organizacji

Administratorzy na planach Team i Enterprise mogą:

• rozdać pluginy przez ustawienia zarządzane (zasięg managed, użytkownik nie zmieni)
• ograniczyć, jakie marketplace’y wolno w ogóle dodawać
• włączyć skanowanie pluginów pod kątem złośliwej zawartości (funkcja planu Enterprise)
• ograniczyć dostępność pluginów per grupa użytkowników (to akurat funkcja planu Enterprise)

Jeśli marketplace firmowy jest dystrybuowany przez ustawienia organizacji, obowiązują dodatkowe reguły co do źródeł — najprościej trzymać foldery pluginów w tym samym repozytorium co marketplace i wskazywać je ścieżkami względnymi. Wtedy użytkownicy nie potrzebują dostępu do żadnego innego repo.

3.5. Aktualizacje

Automatyczne aktualizacje są domyślnie włączone tylko dla oficjalnych katalogów Anthropic. Dla marketplace’ów firmowych i lokalnych trzeba je włączyć samodzielnie — w panelu /plugin albo, dla całej organizacji, ustawieniem autoUpdate przy wpisie marketplace’u.

Sprawdzanie aktualizacji dzieje się po starcie sesji, z losowym opóźnieniem do dziesięciu minut, żeby trwająca sesja pracowała na wersji, którą załadowała. Gdy coś się zaktualizuje, dostaniesz propozycję przeładowania.

---

Część 4. Kiedy plugin, a kiedy szkoda zachodu

Test trzech pytań

1. Czy ktoś poza mną ma tego używać? Jeśli nie — zostań przy .claude/. Plugin bez odbiorcy to sam narzut.
2. Czy dokładam więcej niż jeden rodzaj rzeczy? Sam skill nie potrzebuje pluginu. Skill plus hook, skill plus serwer MCP, skill plus subagent — to już tak, bo skill sam z siebie tego nie zapakuje.
3. Czy to musi być wersjonowane? Jeśli procedura będzie się zmieniać i chcesz wiedzieć, kto ma którą wersję — plugin. Jeśli to eksperyment — nie.

Kiedy plugin jest właściwym wyborem

• Standard zespołowy. Komplet: konwencje, procedury, dostępy i automaty, instalowany jedną komendą.
• Coś więcej niż skille. Serwer MCP z gotową konfiguracją, hook wymuszający regułę, subagent do konkretnej roboty.
• Onboarding. Nowa osoba klonuje repo i ma wszystko. Bez akapitu na wiki, którego i tak nikt nie przeczyta.
• Zestaw ról. Plugin, który sam nie robi nic poza deklaracją dependencies, to gotowy „pakiet dla backendu” albo „pakiet dla marketingu” — jedna instalacja pociąga całą resztę.
• Rozdawanie na zewnątrz. Jeśli budujesz narzędzie i chcesz, żeby ludzie mogli go używać z agentem — marketplace jest do tego.

Kiedy odpuścić

Sytuacja	Zamiast pluginu
Jedna procedura, tylko dla Ciebie	skill w ~/.claude/skills/
Kilka skilli w jednym projekcie	katalog .claude/skills/ w repo
Potrzebny sam dostęp do systemu	pojedynczy serwer MCP w konfiguracji
Eksperyment, nie wiadomo czy zostanie	.claude/, spakujesz później
Skille + hooki, ale tylko u siebie	plugin w katalogu skilli (claude plugin init)
Wiedza, nie procedura	instrukcje projektu / CLAUDE.md

Anty-wzorce

Plugin-śmietnik. Wszystko, co zespół kiedykolwiek napisał, w jednej paczce. Koszt kontekstu rośnie, a większość zawartości nigdy się nie przydaje. Lepiej kilka pluginów tematycznych i jeden „pakiet” spinający je zależnościami.

Serwer MCP dorzucony na wszelki wypadek. Definicje narzędzi MCP potrafią kosztować w kontekście więcej niż wszystkie skille pluginu razem wzięte. Dokładaj serwer tylko wtedy, gdy plugin faktycznie go używa.

Ścieżki bezwzględne. /Users/ja/projekty/plugin/scripts/x.sh zadziała u Ciebie i u nikogo więcej. Zawsze ${CLAUDE_PLUGIN_ROOT}.

Zapisywanie danych do katalogu instalacji. Pierwsza aktualizacja pluginu je skasuje. Od tego jest ${CLAUDE_PLUGIN_DATA}.

Brak pola version. Bez niego trudno powiedzieć, kto ma co zainstalowane, a przypinanie i zależności przestają działać przewidywalnie.

Instalowanie bez czytania. O tym niżej — to najpoważniejszy punkt w całym poradniku.

Bezpieczeństwo — czytaj to dwa razy

Plugin wykonuje dowolny kod na Twojej maszynie, z Twoimi uprawnieniami. Nie jest to przenośnia ani ostrożnościowa formułka. Plugin może zawierać hook uruchamiany przy starcie każdej sesji, serwer MCP wystawiający dowolne narzędzia, binarki dopisane do PATH i skrypty odpalane po każdej edycji pliku. Anthropic zastrzega wprost, że nie kontroluje, jakie serwery MCP, pliki i oprogramowanie znajdują się w pluginach, i nie może zweryfikować, że działają zgodnie z opisem.

Minimalna higiena:

• Instaluj tylko ze źródeł, którym ufasz. To dotyczy też marketplace’ów — dodanie marketplace’u to decyzja tej samej wagi co instalacja pluginu.
• Przeczytaj listę „Will install” przed instalacją. Widać tam komendy, skille, agentów, hooki oraz serwery MCP i LSP.
• Zajrzyj do hooks.json, .mcp.json i scripts/ przy pluginach spoza oficjalnego katalogu. To trzy miejsca, gdzie siedzi wykonywalny kod.
• W organizacji ogranicz dozwolone marketplace’y ustawieniami zarządzanymi i włącz skanowanie.
• Przypinaj wersje. Plugin przypięty do konkretnego commita nie zmieni się pod Tobą po cichu.
• Traktuj plugin w repozytorium jak kod. Review w pull requeście, nie „wrzuciłem, działa”.

---

Część 5. Przepis: własny plugin i własny marketplace

Krok 1. Postaw szkielet

Ręcznie:

mkdir -p moj-plugin/.claude-plugin

moj-plugin/.claude-plugin/plugin.json:

{
  "name": "moj-plugin",
  "description": "Do czego to służy — to zdanie zobaczą ludzie w katalogu",
  "version": "0.1.0",
  "author": { "name": "Twoje imię" }
}

Albo automatycznie, od razu w katalogu skilli, bez marketplace’u:

claude plugin init moj-plugin --with skills hooks

Krok 2. Przenieś to, co już masz

Jeśli masz działającą konfigurację w .claude/, konwersja to głównie kopiowanie:

cp -r .claude/skills   moj-plugin/
cp -r .claude/agents   moj-plugin/
cp -r .claude/commands moj-plugin/

Hooki wymagają jednego kroku więcej: obiekt hooks z .claude/settings.json przenosisz do moj-plugin/hooks/hooks.json — format jest ten sam.

Po migracji usuń oryginały z .claude/. Definicje agentów z projektu i katalogu użytkownika nadpisują agentów o tej samej nazwie z pluginu, więc dopóki oryginały leżą na miejscu, wersja z pluginu nie zadziała. Ze skillami jest inaczej — te z pluginu mają prefiks, więc obie wersje po prostu istnieją obok siebie i łatwo o dublowanie.

Krok 3. Testuj lokalnie

claude --plugin-dir ./moj-plugin

Flagę można powtórzyć dla kilku pluginów naraz, przyjmuje też archiwum .zip. Jeśli plugin o tej nazwie masz już zainstalowany z marketplace’u, lokalna kopia ma pierwszeństwo — możesz testować zmiany bez odinstalowywania. Wyjątek: pluginów wymuszonych (włączonych lub wyłączonych) ustawieniami zarządzanymi organizacji ta flaga nie nadpisze.

Po każdej zmianie: /reload-plugins. Potem sprawdź komponent po komponencie:

• skille — wywołaj /moj-plugin:nazwa
• subagenci — czy widać ich w /context w sekcji agentów
• hooki — wywołaj zdarzenie, na które nasłuchują, i sprawdź efekt w logu diagnostycznym
• serwery MCP i LSP — zakładka Errors w panelu /plugin

Krok 4. Waliduj

claude plugin validate ./moj-plugin

Sprawdza plugin.json, frontmatter skilli i agentów oraz hooks.json. Ostrzeżenia nie blokują — dodaj --strict, żeby traktować je jak błędy. Ta sama walidacja działa w sesji jako /plugin validate, a przy zgłoszeniu do katalogu społecznościowego przechodzi ją każdy plugin, więc lepiej uruchomić ją u siebie wcześniej.

Gdy coś nie działa, claude --debug pokazuje ładowanie pluginów, błędy manifestu, rejestrację komponentów i start serwerów MCP. Najczęstsze przyczyny to, po kolei: katalogi w złym miejscu, skrypt bez prawa wykonywania (chmod +x), ścieżka bezwzględna zamiast ${CLAUDE_PLUGIN_ROOT}.

Krok 5. Zrób marketplace

Marketplace to plik .claude-plugin/marketplace.json w katalogu głównym repozytorium:

{
  "name": "narzedzia-firmy",
  "owner": { "name": "Zespół Platformy", "email": "[email protected]" },
  "description": "Wewnętrzne pluginy Claude",
  "plugins": [
    {
      "name": "standard-backend",
      "source": "./pluginy/standard-backend",
      "description": "Komplet dla zespołu backendowego",
      "version": "1.0.0",
      "category": "zespoly"
    },
    {
      "name": "przeglad-kodu",
      "source": { "source": "github", "repo": "firma/claude-przeglad-kodu" },
      "description": "Agenci i procedury przeglądu kodu"
    }
  ]
}

Wymagane są tylko trzy pola na poziomie marketplace’u — name, owner, plugins — a w każdym wpisie name i source.

Źródła pluginu:

Źródło	Kiedy	Uwaga
ścieżka względna ("./pluginy/x")	plugin leży w tym samym repo	najprostsze; nie działa, gdy marketplace dodano jako bezpośredni URL do pliku
github	osobne repo na GitHubie	obsługuje ref (gałąź/tag) i sha (dokładny commit)
url	dowolny host git	jw.
git-subdir	podkatalog w monorepo	klonuje wyłącznie wskazany podkatalog, oszczędza transfer
npm	plugin publikowany jako pakiet
archive	zip po HTTPS	działa bez gita i npm po stronie użytkownika
command	katalog produkowany lokalną komendą	przeliczany raz na sesję

Nazwa marketplace’u jest publiczna — użytkownicy zobaczą ją przy instalacji (nazwa@narzedzia-firmy). Kilkanaście nazw jest zarezerwowanych dla Anthropic i nazwy podszywające się pod oficjalne (official-claude-plugins i podobne) są blokowane.

claude plugin validate ./moj-plugin   # przed publikacją

Hosting to zwykły push do repozytorium. Repozytorium prywatne działa tak samo — to standardowy sposób na marketplace firmowy.

Krok 6. Wersjonuj

Ustaw version w plugin.json. To przypina plugin: użytkownicy dostaną nową wersję dopiero po podbiciu tego pola. Wyjątkiem jest źródło command — takiego pluginu nie przypina ani version w manifeście, ani wpis w marketplace.

Jeśli inne pluginy mają zależeć od Twojego z ograniczeniem wersji, potrzebne są tagi gita w konwencji {nazwa-pluginu}--v{wersja}. Komenda robi to za Ciebie:

claude plugin tag --push

Przed utworzeniem tagu waliduje zawartość, sprawdza zgodność wersji między plugin.json a wpisem w marketplace i wymaga czystego drzewa roboczego.

Krok 7. Zależności i pakiety zespołowe

Plugin może wymagać innych pluginów:

{
  "name": "deploy-kit",
  "version": "3.1.0",
  "dependencies": [
    "audit-logger",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

Bez ograniczenia wersji zależność śledzi najnowszą dostępną — czyli cudza aktualizacja może Ci coś zepsuć bez ostrzeżenia. Zakres semver (~2.1.0, ^2.0, >=1.4, =2.1.0) trzyma ją w przetestowanym przedziale.

Z tego wynika przyjemny wzorzec: plugin, który nie ma nic poza name i dependencies, jest gotowym pakietem startowym dla roli. Instalacja jednego pociąga cztery.

Domyślnie zależność z innego marketplace’u jest blokowana — żeby jeden katalog nie wciągał po cichu pluginów ze źródła, którego nie sprawdzałeś. Odblokowuje to pole allowCrossMarketplaceDependenciesOn w marketplace.json.

Krok 8. Rozdaj

• Zespół — repozytorium prywatne + extraKnownMarketplaces w .claude/settings.json projektu
• Organizacja — ustawienia zarządzane, zasięg managed
• Publicznie — zgłoszenie do katalogu społecznościowego przez formularz w aplikacji albo w konsoli; przechodzi tę samą walidację co lokalna, plus automatyczne skanowanie bezpieczeństwa
• Oficjalny katalog Anthropic jest kuratorowany osobno — nie ma tam procesu zgłoszeniowego

---

Pełny przykład: plugin zespołowy

Realistyczna paczka, która robi coś więcej niż jeden skill. Struktura:

standard-backend/
├── .claude-plugin/plugin.json
├── skills/
│   ├── wydanie/SKILL.md
│   └── konwencje-api/SKILL.md
├── agents/
│   └── audytor-migracji.md
├── hooks/hooks.json
├── scripts/sprawdz-migracje.sh
└── .mcp.json

.claude-plugin/plugin.json:

{
  "name": "standard-backend",
  "displayName": "Standard backendu",
  "version": "1.2.0",
  "description": "Procedura wydania, konwencje API, audyt migracji i dostęp do wewnętrznego rejestru usług",
  "author": { "name": "Zespół Platformy", "email": "[email protected]" },
  "repository": "https://github.com/firma/claude-pluginy",
  "license": "Proprietary",
  "keywords": ["backend", "wydanie", "migracje"],
  "userConfig": {
    "rejestr_url": {
      "type": "string",
      "title": "Adres rejestru usług",
      "required": true
    }
  }
}

hooks/hooks.json — hook, który po każdej edycji pliku migracji sprawdza, czy da się ją cofnąć:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | grep -q '/migrations/' && \"${CLAUDE_PLUGIN_ROOT}\"/scripts/sprawdz-migracje.sh || true"
          }
        ]
      }
    ]
  }
}

.mcp.json — serwer MCP korzystający z adresu podanego przez użytkownika przy instalacji:

{
  "mcpServers": {
    "rejestr-uslug": {
      "command": "${CLAUDE_PLUGIN_ROOT}/bin/rejestr-mcp",
      "args": ["--url", "${user_config.rejestr_url}"],
      "env": { "CACHE_DIR": "${CLAUDE_PLUGIN_DATA}/cache" }
    }
  }
}

agents/audytor-migracji.md:

---
name: audytor-migracji
description: Sprawdza migracje bazy pod kątem blokowania tabel i braku wycofania
model: sonnet
effort: high
disallowedTools: Write, Edit
skills:
  - standard-backend:konwencje-api
---

Analizujesz migracje bazy danych. Niczego nie zmieniasz — raportujesz.

Dla każdej migracji sprawdź:
1. Czy istnieje ścieżka wycofania
2. Czy dodanie kolumny z indeksem jest rozbite na dwa kroki
3. Czy operacja blokuje tabelę dłużej niż sekundę przy naszym rozmiarze danych
4. Czy zmiana jest zgodna wstecz z wersją aplikacji obecnie na produkcji

Wpis w marketplace.json i po instalacji zespół dostaje: dwa skille, agenta, hooka pilnującego migracji i skonfigurowany dostęp do rejestru usług. Jedną komendą.

Ściąga

Struktura

plugin/
├── .claude-plugin/plugin.json   # TYLKO manifest tutaj
├── skills/  agents/  hooks/  bin/  scripts/
├── .mcp.json  .lsp.json  settings.json
└── monitors/monitors.json

Manifest — minimum name (wymagane) · description · version · author

Reguły ścieżek skills dopisuje do domyślnego · commands, agents, outputStyles zastępują · hooks, mcpServers, lspServers łączą

Zmienne ${CLAUDE_PLUGIN_ROOT} — pliki z paczki · ${CLAUDE_PLUGIN_DATA} — dane, które mają przeżyć aktualizację

Cykl pracy

claude plugin init nazwa          # szkielet
claude --plugin-dir ./nazwa       # test lokalny
/reload-plugins                   # po każdej zmianie
claude plugin validate ./nazwa    # walidacja
claude plugin tag --push          # tag wersji

Trzy pytania przed zrobieniem pluginu Ktoś poza mną tego użyje? · Dokładam więcej niż same skille? · Ma być wersjonowane?

Jedna zasada nadrzędna Plugin uruchamia kod na Twojej maszynie. Instaluj tylko to, czemu ufasz — i czytaj, co instalujesz.