# Budowa i dystrybucja pluginu lub prywatnego marketplace'u

URL: https://developertoolkit.ai/pl/ecosystem/plugins/building-plugins/
Description: Zbuduj plugin ze skillem, hookiem i serwerem MCP, udowodnij jego działanie przez validate i eval, wersjonuj go i wydaj w prywatnym marketplace zespołu.

Plugin agenta kodującego to katalog z manifestem (`.claude-plugin/plugin.json`, `.codex-plugin/plugin.json` albo `.cursor-plugin/plugin.json`), skillami, hookami i konfiguracją MCP, dystrybuowany przez marketplace, czyli repozytorium git z plikiem katalogu. Skille i serwery MCP przenoszą się między Claude Code, Codex i Cursorem; hooki nie, więc każde narzędzie potrzebuje własnego pliku hooków i własnego testu.

Twój zespół ma skill do migracji w jednym repozytorium, hook `PreToolUse` w czyimś `~/.claude/settings.json` i serwer MCP do bazy stagingowej, który trzy osoby skonfigurowały na trzy sposoby. Nowa osoba w zespole nie dostaje niczego z tego, a poprawka hooka nie trafia do nikogo. Ta strona jest dla programisty, który raz pakuje ten zestaw, i dla tech leada, który jest właścicielem prywatnego marketplace'u, z którego zestaw jest wydawany.

## Co zyskujesz, pakując konfigurację agentów zespołu w plugin

- Działający plugin `acme-db-guard`, który łączy skill, blokujący hook i serwer MCP tylko do odczytu, z każdym plikiem pokazanym w całości
- Procedurę weryfikacji, która dowodzi działania pluginu, zanim ktokolwiek go zainstaluje: `validate --strict`, test hooka, `claude plugin eval` na tle przebiegu bez pluginu i odczyt kosztu w kontekście
- Prywatny marketplace, z którego instalują zarówno Claude Code, jak i Codex, oraz ustawienia zarządzane, które przypinają go całemu zespołowi
- Zasadę wersjonowania, zadanie CI, które ją egzekwuje, i tabelę tego, co przenosi się między narzędziami, a co nie

Kroki oznaczone poniżej jako uruchomione wykonaliśmy 2026-09-26 na Claude Code 2.1.283 (krok ze szkieletem sprawdzony ponownie na 2.1.286) i codex-cli 0.157.1 w tymczasowym katalogu domowym. Szczegóły Cursora pochodzą z oficjalnego repozytorium `cursor/plugins`, a dwa formaty pluginów opisane poniżej z [cursor.com/docs/plugins](https://cursor.com/docs/plugins) (czytane 2026-10-12); cursor.com był niedostępny 2026-09-26, więc żadnego kroku w Cursorze nie uruchomiliśmy.

## Plugin, skill czy serwer MCP: co zbudować?

Buduj plugin tylko wtedy, gdy musisz wydać zależne od siebie elementy pod jedną wersją. Pojedyncza procedura to [skill](/pl/ecosystem/skills/building-custom-skills/), pojedyncze połączenie to [serwer MCP](/pl/ecosystem/mcp/custom-mcp-development/).

| Twoja sytuacja | Zbuduj |
| -------------- | ------ |
| Jedna procedura wielokrotnego użytku, używana w kilku agentach | Skill instalowany przez `npx skills` |
| Jedno połączenie na żywo z wewnętrznym API | Serwer MCP dodawany per projekt |
| Procedura, która działa tylko z hookiem albo serwerem obok | Plugin |
| Panel, polecenie albo reguła dla wywołań narzędzi wewnątrz samego Claude Code | Mod (Claude Code v2.1.287 i nowszy): plugin, którego handlery zdarzeń w JavaScripcie lub TypeScripcie działają wewnątrz Claude Code |
| Ten sam zestaw ma trafić na każdy laptop, a poprawka do wszystkich | Plugin w marketplace zespołu |
| Zachowanie specyficzne dla dostawcy, np. bot do PR-ów | Żadne z nich: skonfiguruj produkt dostawcy |

[Przegląd pluginów](/pl/ecosystem/plugins/) opisuje instalowanie cudzych pluginów. Ta strona opisuje budowę własnych.

## Z czego składa się plugin w Claude Code, Codex i Cursorze?

Foldery komponentów to ten sam pomysł we wszystkich trzech narzędziach. Różnią się położeniem manifestu i formatem hooków.

```text
acme-plugins/                         # the marketplace repository
├── .claude-plugin/marketplace.json   # catalogue for Claude Code (Codex also reads it)
├── .agents/plugins/marketplace.json  # catalogue for Codex (optional)
└── plugins/acme-db-guard/
    ├── .claude-plugin/plugin.json    # Claude Code manifest
    ├── .codex-plugin/plugin.json     # Codex manifest (optional)
    ├── skills/new-migration/SKILL.md # Agent Skills format: portable
    ├── hooks/hooks.json              # Claude Code hook format: not portable
    ├── scripts/guard-applied-migrations.sh
    └── .mcp.json                     # MCP servers
```

| Element | Claude Code | Codex | Cursor |
| ------- | ----------- | ----- | ------ |
| Manifest | `.claude-plugin/plugin.json` | `.codex-plugin/plugin.json` | `.cursor-plugin/plugin.json` |
| Plik marketplace'u | `.claude-plugin/marketplace.json` | `.agents/plugins/marketplace.json` albo plik Claude | `.cursor-plugin/marketplace.json` |
| Skille | `skills/<name>/SKILL.md`, wykrywane automatycznie | `skills/`; ścieżka `"skills"` w manifeście dokłada kolejne | `"skills": "./skills/"` w manifeście |
| Hooki | `hooks/hooks.json`, wykrywane automatycznie | formatu tu nie sprawdziliśmy (skill `plugin-creator`, który go tworzył, usunięto z wbudowanych skilli Codeksa w 0.159.0) | `"hooks": "./hooks/hooks.json"`, inny schemat |
| Serwery MCP | `.mcp.json` | `"mcpServers": "./.mcp.json"` | `mcp.json` (według `cursor/plugins`) |
| Zmienna katalogu pluginu | `${CLAUDE_PLUGIN_ROOT}` | niesprawdzone | `${CURSOR_PLUGIN_ROOT}` (według plików hooks.json w `cursor/plugins`) |

Dokumentacja pluginów Cursora (czytana 2026-10-12) wymienia dwa formaty: Agent Plugins, z manifestem `plugin.json` w katalogu głównym pluginu, i Cursor Plugins, z manifestem `.cursor-plugin/plugin.json`. Ta strona używa drugiego.

### Czym jest mod i czym różni się od pluginu z hookiem?

Mod to plugin Claude Code, którego handlery zdarzeń w JavaScripcie lub TypeScripcie działają wewnątrz Claude Code i mogą rysować panele, pilnować wywołań narzędzi i dodawać polecenia. Claude Code dodał mody w v2.1.287, więc oba kanały wydań mają je 2026-10-17 (`stable` 2.1.292, `latest` 2.1.302). Hook `PreToolUse` w `acme-db-guard` uruchamia polecenie powłoki spoza Claude Code. Handlery moda działają w procesie samego Claude Code z Twoimi uprawnieniami, a mody nie działają w sandboxie, więc sprawdzaj je jak kod, który uruchamiasz, a nie jak skill.

Z modami współpracują dwa polecenia `claude plugin` (Claude Code 2.1.296, sprawdzone 2026-10-12). `claude plugin validate KATALOG` wypisuje zdarzenia, które mod obsługuje (`hooks:`), i to, o co prosi Claude Code (`calls:`), bez uruchamiania moda. `claude plugin test [KATALOG]` uruchamia każdy plik `*.test.ts` i `*.test.tsx` w katalogu moda (domyślnie w bieżącym) i kończy się kodem `1`, gdy test nie przejdzie. Przykład `acme-db-guard` z tej strony nie jest modem. Format opisuje dokumentacja modów Claude Code.

## Zbuduj plugin acme-db-guard krok po kroku

Przykład pilnuje migracji bazy danych. Skill mówi agentowi, jak napisać nową migrację, hook blokuje edycję migracji śledzonych już przez git, a serwer MCP pozwala agentowi przeglądać staging bez prawa zapisu.

1. **Wygeneruj szkielet pluginu.** Zacznij od generatora danego narzędzia, a potem podmień pliki zastępcze na te poniżej.

   **Claude Code**

   ```bash
   claude plugin init acme-db-guard --with skills hooks mcp --description "Migration guard"
   ```

   Polecenie zapisuje plugin w `~/.claude/skills/acme-db-guard/`, a w następnej sesji ładuje go jako `acme-db-guard@skills-dir`. Z `--with skills hooks mcp` zapisuje też pliki przykładowe: przed dodaniem plików poniżej usuń wygenerowany `SKILL.md` w katalogu głównym pluginu, `skills/example/` i `hooks-handlers/` (handler `SessionStart`), inaczej wydasz przykładowy skill i hook, których nie napisałeś (sprawdzone na 2.1.286). Gdy plugin zadziała, przenieś folder do repozytorium marketplace'u. Jeśli chcesz budowy z przewodnikiem, `plugin-dev@claude-plugins-official` dodaje skill `/plugin-dev:create-plugin` i subagenta walidującego; kosztuje około 2349 tokenów stale obecnych w kontekście, więc włączaj go tylko na czas tworzenia.

   **Codex**

   Codex 0.157.1 miał wbudowany skill `plugin-creator`, który uruchamiał `scripts/create_basic_plugin.py <name>` z flagami takimi jak `--with-skills --with-hooks --with-mcp --with-marketplace`, zapisywał `.codex-plugin/plugin.json` i sprawdzał wynik skryptem `scripts/validate_plugin.py`. OpenAI usunęło ten wbudowany skill w 0.159.0 (2026-09-29), a wbudowane skille w 0.162.1 to `imagegen`, `openai-docs`, `review-agent`, `skill-creator` i `skill-installer`. Na aktualnych wersjach utwórz `.codex-plugin/plugin.json` i foldery z tabeli powyżej ręcznie.

   **Cursor**

   Wpisz `/add-plugin create-plugin` w czacie Agenta, a potem uruchom `/create-plugin` z nazwą, celem i typami komponentów. Jego skill `review-plugin-submission` sprawdza wynik. Oba pochodzą z README `cursor/plugins` i nie były tu uruchamiane.

2. **Napisz manifest.** Pole `name` staje się przestrzenią nazw każdego skilla i komendy, więc użytkownik wywołuje skill jako `/acme-db-guard:new-migration`. Nigdy nie zmieniaj nazwy opublikowanego pluginu.

   ```json title="plugins/acme-db-guard/.claude-plugin/plugin.json"
   {
     "name": "acme-db-guard",
     "version": "0.1.0",
     "description": "Migration skill, schema guard hook and read-only Postgres MCP",
     "author": { "name": "Acme Platform Team" }
   }
   ```

3. **Dodaj skill.** Pole `description` decyduje, kiedy agent załaduje skill, więc wymień w nim frazy, które go wyzwalają.

   ```markdown title="plugins/acme-db-guard/skills/new-migration/SKILL.md"
   ---
   name: new-migration
   description: Use when the user asks to change the database schema, add a column, add an index or write a migration. Writes a new numbered file in db/migrations/ and never edits an applied one.
   ---

   # New migration

   1. List db/migrations/ and pick the next number.
   2. Write the forward migration only; create indexes with CREATE INDEX CONCURRENTLY in a migration of its own, because it cannot run inside a transaction.
   3. Run the migration against a scratch database and the test suite, and paste both results.
   ```

4. **Dodaj hook.** Skill prosi, hook egzekwuje. Kod wyjścia `2` blokuje wywołanie narzędzia i odsyła agentowi komunikat ze stderr.

   ```json title="plugins/acme-db-guard/hooks/hooks.json"
   {
     "hooks": {
       "PreToolUse": [
         {
           "matcher": "Edit|Write",
           "hooks": [
             { "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/guard-applied-migrations.sh\"" }
           ]
         }
       ]
     }
   }
   ```

   ```bash title="plugins/acme-db-guard/scripts/guard-applied-migrations.sh"
   #!/usr/bin/env bash
   command -v jq >/dev/null && command -v git >/dev/null || { echo "acme-db-guard: jq and git are required" >&2; exit 1; }
   path=$(jq -r '.tool_input.file_path // empty')
   case "$path" in
     */db/migrations/*)
       if git ls-files --error-unmatch "$path" >/dev/null 2>&1; then
         echo "Blocked: $path is already committed. Write a new migration instead." >&2
         exit 2
       fi ;;
   esac
   exit 0
   ```

   Przed commitem nadaj skryptowi prawo wykonania (`chmod +x`). Skrypt potrzebuje `jq` i `git` w `PATH`; plugin ich nie zainstaluje, dlatego pierwsza linia kończy skrypt kodem 1 z komunikatem, gdy brakuje któregoś z nich. Kod 1 ujawnia błąd, ale nie blokuje każdego wywołania narzędzia.

5. **Dodaj serwer MCP.** Sekrety podawaj jako `${VARIABLE}`, żeby żadne dane uwierzytelniające nie trafiły do repozytorium. Postgres MCP Pro to pakiet PyPI `postgres-mcp` uruchamiany przez `uvx`; pakiet npm o tej samej nazwie nie ma z nim nic wspólnego. Ostatnie wydanie w PyPI, 0.3.0, pochodzi z 2025-05-16, więc przypnij wersję (`postgres-mcp==0.3.0`) i zamień go na inny serwer bazodanowy, jeśli projekt pozostanie nieutrzymywany.

   ```json title="plugins/acme-db-guard/.mcp.json"
   {
     "mcpServers": {
       "staging-db": {
         "command": "uvx",
         "args": ["postgres-mcp==0.3.0", "--access-mode=restricted"],
         "env": { "DATABASE_URI": "${ACME_STAGING_DATABASE_URI}" }
       }
     }
   }
   ```

6. **Załaduj plugin na jedną sesję.** `claude --plugin-dir ./plugins/acme-db-guard` ładuje plugin bez instalacji. Po zmianie `/reload-plugins` wczytuje ją bez restartu.

**Prompt do skopiowania: spakuj istniejącą konfigurację w plugin**

```text
Package our migration setup as a Claude Code plugin named acme-db-guard under plugins/acme-db-guard/. Move the skill in .claude/skills/new-migration/ into skills/new-migration/. Move the PreToolUse hook from .claude/settings.json into hooks/hooks.json, with its script under scripts/ and referenced through ${CLAUDE_PLUGIN_ROOT}. Move the staging-db server from .mcp.json into the plugin's .mcp.json, keeping every secret as a ${VARIABLE} reference. Write .claude-plugin/plugin.json with version 0.1.0. Do not delete the originals yet. When done, run `claude plugin validate --strict plugins/acme-db-guard` and `claude plugin details acme-db-guard` after a local install, and paste both outputs.
```

## Udowodnij, że plugin działa, zanim ktokolwiek go zainstaluje

Plugin działa na maszynie każdej osoby z zespołu, z jej danymi uwierzytelniającymi, więc „u mnie się załadował” nie jest dowodem. Wykonaj cztery sprawdzenia; razem zastępują czytanie pluginu linijka po linijce.

1. **Waliduj w trybie ścisłym.** `--strict` zamienia ostrzeżenia w niezerowy kod wyjścia, więc łapie nierozpoznane pola i brakujące metadane, które środowisko uruchomieniowe toleruje.

   ```bash
   claude plugin validate --strict ./acme-plugins
   claude plugin validate --strict ./acme-plugins/plugins/acme-db-guard
   ```

   Waliduj osobno marketplace i każdy plugin. Walidacja marketplace'u nie wykrywa katalogu `source`, który nie istnieje; zawodzi dopiero instalacja.

2. **Przetestuj hook bez agenta.** Podaj skryptowi JSON, który wysyła zdarzenie `PreToolUse`, i sprawdź kody wyjścia:

   ```bash
   echo '{"tool_input":{"file_path":"'"$PWD"'/db/migrations/001_init.sql"}}' \
     | plugins/acme-db-guard/scripts/guard-applied-migrations.sh; echo "exit=$?"
   # Blocked: …/db/migrations/001_init.sql is already committed. Write a new migration instead.
   # exit=2
   ```

   Nowy, nieśledzony plik musi zwrócić `exit=0`. Powyższe polecenie działa tylko w repozytorium, w którym `db/migrations/001_init.sql` jest zacommitowany, a job CI poniżej działa w repozytorium marketplace'u, gdzie takiego pliku nie ma. Dlatego własny skrypt testowy pluginu buduje tę konfigurację w tymczasowym repozytorium i sprawdza oba przypadki. Nadaj mu prawo wykonywania; job CI uruchamia go przy każdym pull requeście.

   ```bash title="plugins/acme-db-guard/tests/hook.sh"
   #!/usr/bin/env bash
   set -u
   guard="$(cd "$(dirname "$0")/.." && pwd)/scripts/guard-applied-migrations.sh"
   tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT
   git -C "$tmp" init -q
   mkdir -p "$tmp/db/migrations"; echo x > "$tmp/db/migrations/001_init.sql"
   git -C "$tmp" add -A
   git -C "$tmp" -c user.name=t -c user.email=t@t commit -qm init
   cd "$tmp"
   check() { # $1 = file, $2 = expected exit code
     echo '{"tool_input":{"file_path":"'"$tmp/$1"'"}}' | "$guard" 2>/dev/null
     got=$?; [ "$got" -eq "$2" ] || { echo "FAIL $1: exit $got, want $2"; exit 1; }
   }
   check db/migrations/001_init.sql 2
   check db/migrations/002_add_index.sql 0
   echo "hook tests passed"
   ```

   Raz celowo zepsuj strażnika (zmień w nim `exit 2` na `exit 0`) i sprawdź, że skrypt wypisuje `FAIL` i kończy się kodem 1; test, który nie może się nie powieść, niczego nie dowodzi.

3. **Zmierz koszt.** Zainstaluj plugin z lokalnego marketplace'u i odczytaj spis komponentów:

   ```bash
   claude plugin marketplace add ./acme-plugins
   claude plugin install acme-db-guard@acme-plugins
   claude plugin details acme-db-guard
   ```

   ```text
   Component inventory
     Skills (1)  new-migration
     Hooks (1)  PreToolUse  (harness-only — no model context cost)
     MCP servers (1)  staging-db  (tool schemas resolved at runtime; not counted)
   Projected token cost
     Always-on:   ~71 tok   added to every session
   …
   ```

   Powyższy wynik jest skrócony; pełny wymienia też puste typy komponentów i tabelę dla każdego komponentu. Spodziewaj się około 70 tokenów (2.1.283); wynik różniący się o kilka tokenów na innej wersji jest normalny. Schematy narzędzi MCP nie wchodzą do tej liczby, więc sprawdź też `/context` w sesji z podłączonym serwerem.

4. **Oceń plugin na tle przebiegu bazowego.** `claude plugin eval` uruchamia przypadki z katalogu `evals/` pluginu z pluginem i bez niego, a potem raportuje różnicę. `claude plugin eval init --bare new-migration-numbering` tworzy `evals/new-migration-numbering/prompt.md` (zadanie, `max_turns`, `allowed_tools`) i `graders/criteria.md` (definicję sukcesu ocenianą przez model).

   ```bash
   claude plugin eval ./acme-plugins/plugins/acme-db-guard --runs 3 --threshold 0.8 --no-publish
   ```

   Polecenie kończy się kodem `1`, gdy którykolwiek przypadek wypadnie poniżej progu. Eval uruchamia plugin na twojej maszynie, z twoimi uprawnieniami; `--trust-plugin` przekazuj tylko dla pluginów, które sam napisałeś.

   Eval ocenia skill. Przy domyślnym `--mocks record` nie uruchamia `staging-db`, dopóki nie nagrasz mocka albo nie przekażesz `--allow-real-servers`, a hook zadziała tylko wtedy, gdy przypadek może wywołać Edit lub Write (`--allow-tools Edit Write`). Dowodem działania hooka pozostaje test z JSON-em podanym na wejście w kroku 2 (sprawdzone na 2.1.283).

**Prompt do skopiowania: napisz przypadki eval dla pluginu**

```text
Write three eval cases for the plugin in plugins/acme-db-guard using the format `claude plugin eval init --bare <name>` produces: evals/<name>/prompt.md with max_turns and allowed_tools frontmatter, and evals/<name>/graders/criteria.md with type: llm. Case 1: "add a last_login_at column to users" must propose a new file with the next migration number and never an edit to an existing one. Case 2: "fix the typo in 001_init.sql" must refuse the edit and propose a new migration. Case 3: an unrelated request ("rename the README heading") must not load the new-migration skill. Keep allowed_tools to Read, Glob, Grep and Skill. Then run `claude plugin eval plugins/acme-db-guard --runs 3 --no-publish` and report the with-plugin and without-plugin scores per case.
```

Kto zatwierdza: właściciel pluginu (osoba wskazana w `CODEOWNERS` dla `plugins/acme-db-guard/`) akceptuje wydanie tylko wtedy, gdy wszystkie cztery sprawdzenia przechodzą w pull requeście. Recenzenci czytają różnice z evali i koszt w kontekście, a nie każdą linijkę skilla.

## Opublikuj prywatny marketplace zespołu

Marketplace to plik katalogu w katalogu głównym repozytorium. Jego pole `name` użytkownicy wpisują po `@`, więc wybierz je raz.

```json title=".claude-plugin/marketplace.json"
{
  "name": "acme-plugins",
  "description": "Acme platform team plugins",
  "owner": { "name": "Acme Platform Team" },
  "plugins": [
    {
      "name": "acme-db-guard",
      "source": "./plugins/acme-db-guard",
      "description": "Migration skill, schema guard hook and read-only Postgres MCP"
    }
  ]
}
```

`validate --strict` nie przechodzi bez pola `description` na najwyższym poziomie. Wypchnij repozytorium do prywatnego repozytorium na GitHubie albo GitLabie. Osoby z zespołu instalują je potem w swoim narzędziu:

**Claude Code**

```bash
claude plugin marketplace add acme/acme-plugins
claude plugin install acme-db-guard@acme-plugins
```

Claude Code klonuje repozytorium z danymi uwierzytelniającymi git zapisanymi na maszynie i nigdy o nie nie pyta. Dla HTTPS na GitHubie uruchom `gh auth login`, a potem `gh auth setup-git`; sam `GITHUB_TOKEN` w środowisku nic nie da bez pomocnika uwierzytelniania gita (credential helper). Ustaw `CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`, żeby pominąć próbę przez SSH.

Żeby przypiąć plugin do jednego repozytorium, uruchom oba polecenia z `--scope project`. To zapisuje `.claude/settings.json`:

```json title=".claude/settings.json"
{
  "extraKnownMarketplaces": {
    "acme-plugins": { "source": { "source": "github", "repo": "acme/acme-plugins" } }
  },
  "enabledPlugins": { "acme-db-guard@acme-plugins": true }
}
```

Dodaj ten plik do commita. Marketplace rejestruje się, gdy dana osoba zaufa folderowi, a plugin z zewnętrznym źródłem nadal wymaga jednego `claude plugin install … --scope project` na każdej maszynie.

**Codex**

```bash
codex plugin marketplace add acme/acme-plugins --ref main
codex plugin add acme-db-guard@acme-plugins
codex plugin list
# acme-db-guard@acme-plugins  installed, enabled  0.1.0
```

Codex czyta `.claude-plugin/marketplace.json`, gdy to jedyny katalog. Gdy repozytorium ma też `.agents/plugins/marketplace.json`, Codex używa tamtego pliku (zaobserwowane na 0.157.1). Katalog Codeksa wymaga pól `policy` i `category` przy każdym wpisie:

```json title=".agents/plugins/marketplace.json"
{
  "name": "acme-plugins",
  "interface": { "displayName": "Acme platform team" },
  "plugins": [
    {
      "name": "acme-db-guard",
      "source": { "source": "local", "path": "./plugins/acme-db-guard" },
      "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },
      "category": "Developer Tools"
    }
  ]
}
```

Odświeżaj przez `codex plugin marketplace upgrade acme-plugins`, a nie `update`.

**Cursor**

Cursor potrzebuje `.cursor-plugin/marketplace.json` w katalogu głównym repozytorium, w tym samym kształcie co w `cursor/plugins` (`name`, `owner`, `plugins[]` z `name`, `source` i `description`). Administrator importuje repozytorium jako Team Marketplace w **Dashboard → Settings → Plugins**, wybiera grupy dostępu i oznacza każdy plugin jako **Required** albo **Optional**; członkowie zespołu instalują przez `/add-plugin`. Kroki importu pochodzą ze źródeł pośrednich (cursor.com był niedostępny 2026-09-26), więc potwierdź je w swoim panelu.

Żeby ograniczyć marketplace'y, które zespół może dodać w Claude Code, do listy obejmującej wasz, administrator platformy ustawia ustawienia zarządzane (z serwera, przez MDM albo w `managed-settings.json`):

```json title="managed-settings.json"
{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "anthropics/claude-plugins-official" },
    { "source": "github", "repo": "acme/*" },
    { "source": "skills-dir" }
  ],
  "extraKnownMarketplaces": {
    "acme-plugins": { "source": { "source": "github", "repo": "acme/acme-plugins" }, "autoUpdate": true }
  },
  "enabledPlugins": { "acme-db-guard@acme-plugins": true }
}
```

Zostaw wpis `{ "source": "skills-dir" }`: bez niego polityka blokuje też szkielety z `claude plugin init`, na których autorzy testują pluginy. Marketplace'y firm trzecich nie aktualizują się automatycznie, dopóki użytkownik albo administrator tego nie włączy, dlatego ustawiamy tu `autoUpdate`. [Jedna polityka dla każdego agenta](/pl/org/managed-policy/) opisuje odpowiedniki w Codeksie i Cursorze. Jak prowadzić marketplace na co dzień (uwierzytelnianie prywatnego repozytorium, wdrożenie w zespole, wycofywanie pluginu), opisuje [Prywatny marketplace pluginów dla zespołu](/pl/ecosystem/plugins/team-marketplace/).

## Wersjonuj i wydawaj plugin tak, żeby poprawki docierały do wszystkich

Wypchnięty commit nikogo nie aktualizuje, dopóki `plugin.json` ma starą wartość `version`. Wybierz jedną zasadę i zapisz ją w README marketplace'u:

- **Wersje semantyczne.** Podbijaj `version` w `plugin.json` przy każdym wydaniu. Nie wpisuj wersji dodatkowo we wpisie marketplace'u; jedno źródło wyklucza rozbieżność.
- **Śledzenie commitów.** Pomiń `version` wszędzie, a użytkownicy będą śledzić najnowszy commit.

Taguj każde wydanie, żeby osoba z zespołu mogła przypiąć wersję albo się wycofać:

```bash
# after bumping "version" to 0.1.1 in plugin.json and committing
claude plugin tag --dry-run ./plugins/acme-db-guard
# … Dry run — would create tag acme-db-guard--v0.1.1 at HEAD in …
claude plugin tag --push ./plugins/acme-db-guard
```

`claude plugin tag` sprawdza, czy `plugin.json` i wpis w marketplace są zgodne, zanim utworzy tag `<name>--v<version>`. Zespół pobiera wydanie tak:

```bash
claude plugin marketplace update acme-plugins
claude plugin update acme-db-guard@acme-plugins
# Plugin "acme-db-guard" updated from 0.1.0 to 0.1.1 for scope user. Restart to apply changes.
```

Codex trzyma każdą zainstalowaną wersję we własnym katalogu cache (`plugins/cache/acme-plugins/acme-db-guard/0.1.0/` na 0.157.1). Uruchom `codex plugin marketplace upgrade acme-plugins`, a potem ponownie `codex plugin add acme-db-guard@acme-plugins`. Podczas lokalnej pracy na 0.157.1 skill `plugin-creator` od OpenAI (usunięty z wbudowanych skilli w 0.159.0) zmieniał sufiks `+codex.<token>` w wersji, a nie sam numer wersji.

Egzekwuj zasadę w CI. To zadanie nie przechowuje żadnych sekretów i ich nie potrzebuje, bo walidacja nie wywołuje modelu:

```yaml title=".github/workflows/plugins.yml"
name: plugin-marketplace
on:
  pull_request:
    paths: ['plugins/**', '.claude-plugin/**', '.agents/**']
permissions:
  contents: read
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - uses: actions/setup-node@v7
        with:
          node-version: 22
      - run: npm install -g @anthropic-ai/claude-code@2.1.283
      - run: claude plugin validate --strict .
      - run: for p in plugins/*/; do claude plugin validate --strict "$p" || exit 1; done
      - run: for s in plugins/*/scripts/*.sh; do [ -e "$s" ] || continue; [ -x "$s" ] || { echo "$s not executable"; exit 1; }; done
      - run: for t in plugins/*/tests/*.sh; do [ -e "$t" ] || continue; [ -x "$t" ] || { echo "$t not executable"; exit 1; }; "$t" || exit 1; done
      - name: Claude and Codex manifests carry the same version
        run: |
          for p in plugins/*/; do
            [ -f "$p/.codex-plugin/plugin.json" ] || continue
            a=$(jq -r .version "$p/.claude-plugin/plugin.json")
            b=$(jq -r .version "$p/.codex-plugin/plugin.json" | cut -d+ -f1)
            [ "$a" = "$b" ] || { echo "$p: $a vs $b"; exit 1; }
          done
```

Krok zgodności wersji to nasza propozycja: `claude plugin tag` sprawdza tylko pliki Claude, więc nic innego nie zauważy pozostawionego w tyle manifestu Codeksa. `claude plugin eval` uruchamiaj lokalnie albo w osobnym zadaniu na gałęzi domyślnej, bo wywołuje model i potrzebuje klucza.

**Prompt do skopiowania: przegląd wydania pluginu przed merge**

```text
Review the diff of this pull request against main for the plugins/ directory. For every changed plugin report: whether .claude-plugin/plugin.json and .codex-plugin/plugin.json carry the same version and whether it was bumped; every hook added or changed (event, matcher, the command it runs, and what makes it exit 2); every MCP server added or changed (command or URL, and each environment variable it reads); and any literal credential or URL containing a token. Run `claude plugin validate --strict` on each changed plugin and `claude plugin details <name>` after a local install, and flag an always-on cost increase above 500 tokens. Post a table. Do not approve.
```

## Na ile jeden plugin jest przenośny między Claude Code, Codex i Cursorem?

Codex 0.157.1 zainstalował `acme-db-guard` wprost z marketplace'u w formacie Claude, bez manifestu Codeksa, i skopiował do swojego cache każdy folder, łącznie z hookami. Skopiowanie to jeszcze nie aktywacja. Tabela rozdziela jedno od drugiego.

| Komponent | Claude Code | Codex | Cursor | Przenośny? |
| --------- | ----------- | ----- | ------ | ---------- |
| Skille (`SKILL.md`) | Tak | Tak | Tak, przez `"skills"` w manifeście | Tak: [Agent Skills](/pl/ecosystem/skills/) to otwarty standard |
| Serwery MCP | `.mcp.json` | `"mcpServers"` wskazujące ten sam `.mcp.json` | `mcp.json` | W większości: ten sam serwer, inny plik albo klucz |
| Hooki | `hooks/hooks.json`, `PreToolUse` i inne zdarzenia Claude | niesprawdzone, czy hooki w formacie Claude się aktywują; Codex wymaga zaufania hookom pluginu w `/hooks`, zanim się uruchomią (0.157.1) | schemat `"version": 1` ze zdarzeniami w camelCase, np. `stop` i `afterAgentResponse` | Nie: napisz i przetestuj jeden plik hooków na narzędzie |
| Komendy slash, subagenci | Tak | niesprawdzone dla pluginu w formacie Claude | Cursor ma własne foldery `commands/` i `agents/` | Nie |
| Przestrzeń nazw | `/<plugin>:<skill>` | niesprawdzone | niesprawdzone | Przetestuj w każdym narzędziu |

Praktyczna zasada: procedurę umieść w skillu, a połączenie w serwerze MCP, bo te dwa elementy się przenoszą. Hooki trzymaj cienkie, jako jeden mały skrypt wywoływany z pliku hooków każdego narzędzia, żeby logika istniała raz, nawet jeśli podpięcie nie. W pliku hooków Cursora (`"version": 1`) wywołuj ten sam skrypt jako `"${CURSOR_PLUGIN_ROOT}/scripts/guard-applied-migrations.sh"`, a nie ścieżką względną wobec katalogu roboczego.

**Pułapki, które kosztują wydanie**

- Nazwa marketplace'u `claude-code-marketplace`, `anthropic-plugins` albo `official-claude-plugins`: `validate` może przejść, ale `marketplace add` zawiedzie, bo nazwa jest zarezerwowana. Zarezerwowane są też `npm`, `github`, `skills-dir` i `builtin`.
- `claude plugin add`, `codex plugin install` i `codex plugin marketplace update` nie istnieją: żadnego z nich nie ma w `claude plugin --help` (2.1.296), `codex plugin --help` ani `codex plugin marketplace --help` (0.162.1), sprawdzone 2026-10-12. Poprawne polecenia to `claude plugin install`, `codex plugin add` i `codex plugin marketplace upgrade`.
- `enabledPlugins` w `.claude/settings.json` zatwierdzonym w repozytorium włącza plugin, ale nie instaluje pluginu z zewnętrznym źródłem.
- `codex plugin marketplace add openai/plugins` nie działa: `openai-curated` jest zarezerwowany i przychodzi wbudowany.

## Gdy wydanie pluginu się psuje: jak wrócić do działania

- **Zespół nadal używa starego hooka mimo poprawki.** Wersja się nie zmieniła albo automatyczne aktualizacje są wyłączone. Podbij `version`, otaguj wydanie i poproś zespół o `claude plugin marketplace update acme-plugins` i `claude plugin update acme-db-guard@acme-plugins`, a potem restart.
- **Hook blokuje każdą edycję.** Hook, który przy każdym wywołaniu kończy się kodem `2`, odcina agenta od pracy. Od razu wyłącz plugin przez `claude plugin disable acme-db-guard@acme-plugins`, odtwórz problem testem z JSON-em podanym przez potok i dodaj to wejście jako przypadek testowy przed ponownym wydaniem.
- **Hook nic nie robi na jednym laptopie.** Brakuje `jq` albo `git`, albo skrypt stracił prawo wykonania w archiwum zip. Sprawdź `ls -l` na zainstalowanej kopii i spraw, żeby skrypt głośno zawodził, gdy brakuje narzędzia, tak jak robi to skrypt powyżej.
- **Instalacja kończy się błędem `Source path does not exist`.** Plugin przemianowano albo przeniesiono bez aktualizacji pola `source`. Popraw wpis i w CI waliduj każdy katalog pluginu, nie tylko marketplace.
- **Serwer MCP startuje z pustym ciągiem połączenia.** Osoba z zespołu nie wyeksportowała `ACME_STAGING_DATABASE_URI`. Opisz wymagane zmienne w skillu i w README marketplace'u; nigdy nie wpisuj danych uwierzytelniających na sztywno jako wartości zapasowej.
- **Plugin działa w Claude Code, a w Codeksie po cichu nic nie robi.** Codex użył drugiego katalogu albo to komponent, którego Codex nie aktywuje. Uruchom `codex plugin list`, żeby zobaczyć, który `marketplace.json` odczytał, i przetestuj każdy komponent w prawdziwej sesji Codeksa.

## Jak popularne jest budowanie pluginów i ile kosztuje w kontekście

Na dzień 2026-09-26 plugin Anthropic do tworzenia pluginów, `plugin-dev`, miał 67 663 instalacje w katalogu claude.com/plugins. Oficjalne katalogi zawierały 314 wpisów w `claude-plugins-official`, 65 w `openai-curated` Codeksa i 94 w `cursor-plugins` Cursora (policzone z pliku marketplace'u w każdym repozytorium). Przykład `acme-db-guard` dokłada około 71 tokenów stale obecnych w każdej sesji, wobec około 2349 dla samego `plugin-dev`, więc narzędzia do tworzenia pluginów włączaj tylko w sesjach, w których je tworzysz.

## Dokąd dalej z pluginami

- [Przegląd pluginów i marketplace'ów](/pl/ecosystem/plugins/) — Instalacja, pomiar i dopuszczanie cudzych pluginów w każdym agencie.
- [Prywatny marketplace pluginów dla zespołu](/pl/ecosystem/plugins/team-marketplace/) — Prowadzenie kanału: dostęp do prywatnego repozytorium, reguła wersji w CI i wdrożenie w zespole.
- [Budowa i publikacja własnych skilli](/pl/ecosystem/skills/building-custom-skills/) — Format SKILL.md, który przenosi się między agentami.
- [Automatyzacja z hookami Claude Code](/pl/claude-code/automate/hooks-automation/) — Zdarzenia, matchery i kody wyjścia dla hooka w twoim pluginie.
- [Bezpieczeństwo łańcucha dostaw skilli](/pl/ecosystem/skills/skill-security/) — Co sprawdzić, zanim instrukcje i hooki pluginu trafią do zespołu.
- [Marketplace'y i rejestry](/pl/ecosystem/plugins/marketplaces-registries/) — Skąd pochodzą pluginy, skille i serwery MCP oraz na ile ufać każdemu źródłu.
