# Prywatny marketplace wtyczek dla zespołu

URL: https://developertoolkit.ai/pl/ecosystem/plugins/team-marketplace/
Description: Prywatny marketplace wtyczek dla Claude Code, Codexa i Cursora: układ repo, zastrzeżone nazwy, reguła wersji, dostęp, walidacja w CI i wdrożenie.

Prywatny marketplace wtyczek to repozytorium git z plikiem katalogu (`.claude-plugin/marketplace.json`), który wymienia wtyczki zespołu. Claude Code instaluje z niego wtyczki, Codex 0.157.1 czyta ten sam plik, a Cursor importuje własny katalog jako marketplace zespołu. Zmiana trafia do ludzi dopiero wtedy, gdy zmieni się `version` wtyczki, więc podbicie wersji musi wymuszać CI.

Spakowałeś zespołową checklistę wydania i konwencje API jako wtyczki, wypchnąłeś je i poprosiłeś wszystkich o instalację. Dwa tygodnie później poprawiasz błędną regułę w skillu API, a połowa zespołu dalej korzysta ze starej. Nikt nie podbił wersji, jednej osobie klon prywatnego repozytorium po cichu się nie udaje, a nowa osoba ma zacommitowane `enabledPlugins`, ale żadnej zainstalowanej wtyczki. Ta strona jest dla tech leada, który jest właścicielem marketplace'u, i dla programisty, który wydaje w nim zmiany. Zakłada, że umiesz już [zbudować wtyczkę](/pl/ecosystem/plugins/building-plugins/); tutaj prowadzisz kanał, który ją dostarcza.

## Co daje działający marketplace zespołu

- Repozytorium marketplace'u `acme-plugins` z dwiema wtyczkami, z każdym plikiem pokazanym i przetestowanym na Claude Code 2.1.283 i codex-cli 0.157.1
- Bramkę CI, `scripts/check-marketplace.sh`, która zatrzymuje pull request przy ostrzeżeniu schematu, zastrzeżonej nazwie, brakującym katalogu źródłowym albo zmianie bez podbicia wersji
- Pętlę wydania: pull request, CI, merge, tag i jedno polecenie aktualizacji na osobę
- Cztery ścieżki wdrożenia (dla każdej osoby, dla repozytorium, dla całej floty, synchronizacja organizacji w claude.ai) z tym, co każda instaluje, a czego nie
- Listę napraw dla awarii, po których ludzie zostają na nieaktualnych wtyczkach

Wszystko, co opisano poniżej jako zaobserwowane, uruchomiono 26 września 2026 roku w tymczasowym katalogu domowym. Katalog dla Cursora sprawdzono schematami z repozytorium `cursor/plugins`; import w panelu opisano na podstawie źródeł wtórnych, bo cursor.com był niedostępny, i go nie uruchomiono.

## Jak zmiana wędruje od pull requesta do każdej osoby w zespole

Marketplace ma jedno zadanie: dopilnować, żeby to, co zmergowano, było tym, czego wszyscy używają. Każdy etap ma kontrolę, która zastępuje czytanie zmiany linijka po linijce.

| Etap | Kto | Kontrola, która to udowadnia | Narzędzie |
| ---- | --- | ---------------------------- | --------- |
| Pull request | Autor wtyczki | CI: ścisła walidacja, testowa instalacja, reguła podbicia wersji | `scripts/check-marketplace.sh` |
| Review | Właściciel w `CODEOWNERS` | Zielone CI, podbita wersja, stały koszt tokenów odczytany z logu CI | Review na GitHubie |
| Wydanie | Właściciel marketplace'u | `claude plugin tag` sprawdza zgodność `plugin.json` z katalogiem | `claude plugin tag --push` |
| Wdrożenie | Każda osoba albo ustawienia zarządzane (managed settings) | `claude plugin list` pokazuje nową wersję | `claude plugin marketplace update`, `claude plugin update` |

## Zbuduj repozytorium marketplace'u z dwiema wtyczkami

Przykładowy marketplace wydaje dwie wtyczki. `acme-release` zawiera skill sprawdzający gotowość do wydania; `acme-api-style` zawiera konwencje HTTP API zespołu. Obie składają się wyłącznie ze skilli, więc kosztują mało kontekstu i przenoszą się między agentami.

1. **Rozplanuj repozytorium.** Każda wtyczka trafia do `plugins/`, a plik katalogu do korzenia repozytorium.

   ```text
   acme-plugins/
   ├── .claude-plugin/marketplace.json       # katalog; Codex też go czyta
   ├── .cursor-plugin/marketplace.json       # opcjonalnie: własny katalog Cursora
   ├── .github/CODEOWNERS
   ├── .github/workflows/plugin-marketplace.yml
   ├── scripts/check-marketplace.sh
   └── plugins/
       ├── acme-release/
       │   ├── .claude-plugin/plugin.json
       │   └── skills/release-check/SKILL.md
       └── acme-api-style/
           ├── .claude-plugin/plugin.json
           └── skills/api-conventions/SKILL.md
   ```

2. **Napisz katalog.** `name` to to, co wszyscy wpisują po `@`, więc wybierz ją raz i nigdy nie zmieniaj. `validate --strict` kończy się błędem bez `description` na najwyższym poziomie.

   ```json title=".claude-plugin/marketplace.json"
   {
     "name": "acme-plugins",
     "description": "Internal plugins for Acme engineering",
     "owner": { "name": "Acme Platform Team", "email": "platform@acme.example" },
     "plugins": [
       {
         "name": "acme-release",
         "source": "./plugins/acme-release",
         "description": "Release checklist skill: changelog, migrations, feature flags"
       },
       {
         "name": "acme-api-style",
         "source": "./plugins/acme-api-style",
         "description": "Acme REST conventions: error envelope, pagination, versioning"
       }
     ]
   }
   ```

   Nie wpisuj `version` do tych pozycji. Jeśli któraś różni się od `plugin.json`, przy instalacji wygrywa `plugin.json`, a pozycja jest po cichu ignorowana; `validate --strict` zgłasza to jako ostrzeżenie i kończy się błędem.

3. **Omiń zastrzeżone nazwy marketplace'u.** Claude Code odrzuca nazwy udające marketplace'y Anthropic. Zaobserwowane na 2.1.283: `validate --strict` przeszło z `"name": "claude-code-marketplace"`, po czym `claude plugin marketplace add` zakończyło się komunikatem `The name 'claude-code-marketplace' is reserved for official Anthropic marketplaces and can only be used with GitHub sources from the 'anthropics' organization.` To samo stało się z `anthropic-plugins`. Dokumentacja marketplace'ów zastrzega też `npm`, `github`, `gh`, `claudeai-*`, `inline`, `builtin`, `skills-dir` i `synced`. Prefiks z nazwą firmy omija je wszystkie.

4. **Nadaj każdej wtyczce wersję.** `version` w `plugin.json` to sygnał, na który reaguje aktualizacja u osoby z zespołu.

   ```json title="plugins/acme-api-style/.claude-plugin/plugin.json"
   {
     "name": "acme-api-style",
     "version": "1.0.0",
     "description": "Acme REST conventions: error envelope, pagination, versioning",
     "author": { "name": "Acme Platform Team" }
   }
   ```

   ```markdown title="plugins/acme-api-style/skills/api-conventions/SKILL.md"
   ---
   name: api-conventions
   description: Use when adding or changing an HTTP endpoint. Applies Acme's error envelope, cursor pagination and /v{n}/ versioning rules.
   ---

   # Acme API conventions

   - Errors return {"error": {"code", "message", "request_id"}} with a 4xx or 5xx status.
   - List endpoints paginate with an opaque `cursor` and `limit` (max 100), never page numbers.
   - Breaking changes go in a new /v{n}/ prefix; never change a published response shape.
   ```

   `acme-release` ma ten sam kształt ze skillem `release-check`.

   Alternatywą jest pominięcie `version` wszędzie. Claude Code wersjonuje wtedy wtyczkę 12-znakowym SHA commita i każdy commit do marketplace'u staje się wydaniem (zaobserwowane na 2.1.283: `updated from 9235eac629d9 to b7aa77f81abc`). To pasuje do marketplace'u, w którym każdy merge ma od razu trafić do ludzi, ale `validate --strict` kończy się wtedy błędem `No version specified`, a zespół traci czytelny numer, który może zgłosić. Ta strona zostaje przy jawnych wersjach i wymusza ich podbijanie w CI.

5. **Wskaż właściciela każdej wtyczki.** Plik `CODEOWNERS` jawnie określa, kto zatwierdza zmiany.

   ```text title=".github/CODEOWNERS"
   /plugins/acme-release/     @acme/release-eng
   /plugins/acme-api-style/   @acme/api-guild
   /.claude-plugin/           @acme/platform
   ```

6. **Wypchnij je do prywatnego repozytorium**, na przykład `acme/acme-plugins` na GitHubie. GitLab i inne hostingi działają przez pełny adres `https://…git`.

**Prompt do skopiowania: szkielet repozytorium marketplace'u**

```text
Create a Claude Code plugin marketplace in this empty repository. Catalogue: .claude-plugin/marketplace.json with name "acme-plugins", a top-level description, owner.name "Acme Platform Team", and two entries whose source is ./plugins/<name> and which carry no version field. Plugin 1: plugins/acme-release with .claude-plugin/plugin.json at version 1.0.0 and a skill skills/release-check/SKILL.md that, before a release, lists user-visible changes missing from CHANGELOG.md, migrations without a rollback note, and new feature flags with their defaults, and never tags. Plugin 2: plugins/acme-api-style at 1.0.0 with a skill skills/api-conventions/SKILL.md for our error envelope, cursor pagination (limit max 100) and /v{n}/ versioning. Write each skill description so it names the trigger phrases. Then run `claude plugin validate --strict .` and `claude plugin validate --strict` on each plugin directory and paste the outputs. Do not install anything.
```

## Zwaliduj marketplace w CI, zanim ktokolwiek z niego zainstaluje

`claude plugin validate --strict` jest konieczne, ale nie wystarcza. W teście na 2.1.283 przepuściło katalog, którego `source` wskazywał nieistniejący katalog, i przepuściło zastrzeżoną nazwę. Oba błędy wychodzą dopiero przy instalacji. Dlatego bramka poniżej waliduje, potem instaluje każdą wtyczkę obydwoma CLI do jednorazowego katalogu domowego, a na końcu wymusza regułę wersji.

```bash title="scripts/check-marketplace.sh"
#!/usr/bin/env bash
# Usage: scripts/check-marketplace.sh <base-ref>   (CI passes origin/main)
set -euo pipefail
base="${1:-origin/main}"
market=$(jq -r .name .claude-plugin/marketplace.json)
export HOME="$(mktemp -d)" CODEX_HOME="$(mktemp -d)"   # scratch homes: nothing leaks in

# 1. Schema: --strict fails on warnings the runtime would tolerate
claude plugin validate --strict .
for p in plugins/*/; do claude plugin validate --strict "$p"; done

# 2. Install smoke test: catches reserved names and missing source directories,
#    which validate passes
claude plugin marketplace add ./
for name in $(jq -r '.plugins[].name' .claude-plugin/marketplace.json); do
  claude plugin install "$name@$market"
  claude plugin details "$name" | grep 'Always-on'
done
codex plugin marketplace add ./
for name in $(jq -r '.plugins[].name' .claude-plugin/marketplace.json); do
  codex plugin add "$name@$market"
done

# 3. Release rule: a changed plugin must carry a new version, or nobody receives it
for p in plugins/*/; do
  git diff --quiet "$base" -- "$p" && continue
  old=$(git show "$base:${p}.claude-plugin/plugin.json" 2>/dev/null | jq -r .version || echo new)
  new=$(jq -r .version "${p}.claude-plugin/plugin.json")
  if [ "$old" = "$new" ]; then
    echo "::error::${p} changed but .claude-plugin/plugin.json still says $new"
    exit 1
  fi
  # ...and the new version must sort above the old one (catches 1.0.0 -> 1.0)
  if [ "$old" != new ] && [ "$(printf '%s\n%s\n' "$old" "$new" | sort -V | tail -1)" != "$new" ]; then
    echo "::error::${p} version went from $old to $new; it must go up"
    exit 1
  fi
done
echo "marketplace OK"
```

Uruchomiony lokalnie skrypt wypisał `Always-on: ~49 tok` dla `acme-release` (twoja liczba zależy od opisu skilla, który napiszesz) i `~68 tok` dla `acme-api-style` i zakończył się `marketplace OK`. Codex ostrzega, że nie utworzy pomocniczych plików binarnych w katalogu tymczasowym; w tym jobie to ostrzeżenie jest nieszkodliwe. Z literówką w `source` zatrzymał się na `Source path does not exist`, a ze skillem zmienionym bez podbicia wersji — na linii `::error::`. Drugi warunek odrzuca też wersję, która spada albo traci składnik, na przykład z `1.0.0` na `1.0`. Krok podbicia wersji to nasza własna reguła, nie funkcja dostawcy.

Workflow nie ma żadnych sekretów, bo walidacja i instalacja nie wywołują modelu:

```yaml title=".github/workflows/plugin-marketplace.yml"
name: plugin-marketplace
on:
  pull_request:
    paths: ['plugins/**', '.claude-plugin/**', '.agents/**', '.cursor-plugin/**', 'scripts/**', '.github/**']
permissions:
  contents: read
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
          persist-credentials: false
      - uses: actions/setup-node@v7
        with:
          node-version: 22
      - run: npm install -g @anthropic-ai/claude-code@2.1.283 @openai/codex@0.157.1
      - run: bash scripts/check-marketplace.sh "origin/$BASE_REF"
        env:
          BASE_REF: ${{ github.base_ref }}
```

`claude plugin eval` wywołuje model i potrzebuje klucza API, więc trzymaj je poza tym jobem `pull_request`. Uruchamiaj je na domyślnej gałęzi albo lokalnie; pokazuje to strona o [budowie wtyczek](/pl/ecosystem/plugins/building-plugins/).

**Prompt do skopiowania: review pull requesta do marketplace'u**

```text
Review this pull request against main for the acme-plugins marketplace. For each plugin under plugins/ that changed, report: the old and new version in .claude-plugin/plugin.json and whether the change is a patch, minor or major by our rule (skill wording = patch, new skill or command = minor, removed or renamed skill = major); every hook, MCP server or script added, with the command it runs and every environment variable it reads; any literal credential or token-bearing URL; and the always-on token figure CI printed for it, flagging any increase above 300 tokens. Check that no marketplace entry carries a version field and that the catalogue name is still acme-plugins. Output one table per plugin. Do not approve or merge.
```

## Wydaj wersję wtyczki i dostarcz ją zespołowi

Merge nikogo nie aktualizuje. Zaobserwowane na 2.1.283: po zmianie skilla bez zmiany wersji `claude plugin marketplace update` zakończyło się sukcesem, a `claude plugin update acme-release@acme-plugins` odpowiedziało `acme-release is already at the latest version (1.0.0)`; skill w cache miał dalej stary tekst. Po podbiciu do `1.0.1` to samo polecenie wypisało `Plugin "acme-release" updated from 1.0.0 to 1.0.1 for scope user. Restart to apply changes.` i utworzyło nowy katalog cache `1.0.1` obok starego.

1. **Otaguj zmergowane wydanie.** Na czystym checkoucie `main` polecenie sprawdza zgodność `plugin.json` z katalogiem, zanim zapisze tag `<name>--v<version>`:

   ```bash
   claude plugin tag --dry-run plugins/acme-release
   # Tag:     acme-release--v1.0.1
   # √ Dry run — would create tag acme-release--v1.0.1 at HEAD in …
   claude plugin tag --push plugins/acme-release
   ```

   Gdy pozycja w katalogu miała jeszcze `"version": "1.0.0"`, polecenie odmówiło: `Version mismatch: plugin.json says "1.0.1" but .claude-plugin/marketplace.json plugins[0].version says "1.0.0".`

2. **Ogłoś wydanie** z tagiem, jednozdaniowym opisem zmiany i poleceniami aktualizacji poniżej. Każda osoba aktualizuje w swoim narzędziu:

   **Claude Code**

   ```bash
   claude plugin marketplace update acme-plugins
   claude plugin update acme-release@acme-plugins
   claude plugin list    # Version: 1.0.1
   ```

   Potem zrestartuj sesję. Zewnętrzne marketplace'y nie aktualizują się automatycznie, dopóki użytkownik albo administrator tego nie włączy (domyślne zachowanie Claude Code 2.1.283; zob. dokumentację marketplace'ów); dlatego ustawienia zarządzane poniżej włączają `autoUpdate`.

   **Codex**

   ```bash
   codex plugin marketplace upgrade acme-plugins
   codex plugin add acme-release@acme-plugins
   codex plugin list    # acme-release@acme-plugins  installed, enabled  1.0.1
   ```

   Codex nie ma `codex plugin update` ani `marketplace update` (na 0.162.1, sprawdzone 2026-10-12, `codex plugin --help` wymienia `add`, `list`, `marketplace` i `remove`, a `codex plugin marketplace --help` wymienia `add`, `list`, `upgrade` i `remove`); ponowne `add` instaluje nową wersję do osobnego katalogu cache (zaobserwowane na 0.157.1). `upgrade` odświeża tylko źródła Git: dla marketplace'u dodanego z lokalnej ścieżki kończy się błędem `marketplace 'acme-plugins' is not configured as a Git marketplace`.

   **Cursor**

   Cursor rozprowadza marketplace zespołu z panelu administracyjnego, a nie przez polecenie uruchamiane przez każdą osobę; tego, jak nowa wersja trafia do członków zespołu, tu nie zweryfikowano (cursor.com był niedostępny 26 września 2026). Sprawdź to w panelu po pierwszym wydaniu.

3. **Potwierdź wdrożenie.** Poproś zespół o wklejenie wyniku `claude plugin list` (albo `codex plugin list`) do wątku wydania albo sprawdź po jednej maszynie z każdego zespołu. Wydanie jest skończone, gdy otagowana wersja jest tą, której ludzie używają.

Złego wydania nie cofasz, tylko naprawiasz nowym: zrób revert zmiany na `main`, podbij wersję do nowej, na przykład `1.0.2`, i otaguj ponownie. Aktualizacja reaguje tylko na nowy numer wersji, więc revert, który zostawia `1.0.1`, do nikogo nie dotrze.

## Wdróż marketplace w całym zespole

Wybierz ścieżkę według tego, ile kontroli potrzebujesz. Każda zapisuje inne ustawienia i żadna nie sprawi, że prywatny klon zadziała bez poświadczeń git.

**Claude Code**

**Najpierw dostęp do prywatnego repozytorium.** Claude Code klonuje z poświadczeniami git maszyny i nigdy o nie nie pyta. Dla HTTPS na GitHubie uruchom `gh auth login`, a potem `gh auth setup-git`. `GITHUB_TOKEN` w środowisku bez credential helpera nic nie daje, a `marketplace.json` nie ma pola na token (sprawdzone na Claude Code 2.1.283). Ustaw `CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`, żeby pominąć próbę SSH. Zanim zaczniesz podejrzewać wtyczkę, sprawdź dostęp zwykłym gitem: `git ls-remote https://github.com/acme/acme-plugins.git`.

| Ścieżka | Polecenie lub plik | Co robi |
| ------- | ------------------ | ------- |
| Dla każdej osoby | `claude plugin marketplace add acme/acme-plugins`, potem `claude plugin install acme-api-style@acme-plugins` | Dodaje i instaluje w zakresie użytkownika |
| Dla repozytorium | `claude plugin marketplace add acme/acme-plugins --scope project` i `claude plugin install acme-api-style@acme-plugins --scope project`, potem zacommituj `.claude/settings.json` | Deklaruje marketplace w `extraKnownMarketplaces` i włącza wtyczkę w `enabledPlugins` |
| Dla całej floty | Ustawienia zarządzane (z serwera, przez MDM albo `managed-settings.json`) | Ustala listę dozwolonych marketplace'ów, dodaje twój z autoaktualizacją, włącza wtyczki |
| claude.ai Team lub Enterprise | **Organization settings → Plugins & skills** | Synchronizuje marketplace przez połączenie organizacji z GitHubem lub GitLabem; repozytorium musi być prywatne albo wewnętrzne, a żadna wtyczka nie może mieć katalogu `bin/` na najwyższym poziomie |

Ścieżka dla repozytorium zapisuje oba klucze, ale **`enabledPlugins` włącza wtyczkę; nie instaluje jej.** Marketplace rejestruje się dopiero wtedy, gdy dana osoba zaufa folderowi, a wtyczka z zewnętrznym źródłem nadal wymaga jednego `claude plugin install … --scope project` na każdej maszynie. Wpisz to polecenie do README repozytorium, a każda osoba niech potwierdzi instalację przez `claude plugin list`.

Ścieżka dla całej floty, na podstawie przykładu z dokumentacji Anthropic (który ustawia też `disableSideloadFlags`). Zostaw `{ "source": "skills-dir" }` na liście dozwolonych: bez tego tryb ścisły blokuje też osobiste wtyczki tworzone przez `claude plugin init` (`<name>@skills-dir`).

```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-release@acme-plugins": true,
    "acme-api-style@acme-plugins": true
  }
}
```

`strictKnownMarketplaces` sprawia, że tylko te marketplace'y da się dodać. Jak rozprowadzać i audytować ten plik, opisuje strona [jedna polityka dla wszystkich agentów kodujących](/pl/org/managed-policy/).

Nowsze opcje `claude plugin` (pomoc Claude Code 2.1.296, sprawdzone 2026-10-12) skracają drogę per osoba. `--marketplace SOURCE` instaluje plugin z marketplace'u, którego jeszcze nie dodano, najpierw dodając go w ustawieniach użytkownika, z tymi samymi kontrolami co `claude plugin marketplace add`, na przykład `claude plugin install acme-api-style --marketplace acme/acme-plugins`. Pojawiła się w v2.1.292, więc 2026-10-17 mają ją oba kanały wydań (`stable` to 2.1.292). `--config KEY=VALUE` ustawia opcję zadeklarowaną w manifeście pluginu, a `claude plugin configure acme-api-style` pokazuje, które opcje nadal są nieustawione; obie pojawiły się w v2.1.285, więc mają je oba kanały.

**Codex**

Codex 0.157.1 czyta `.claude-plugin/marketplace.json`, gdy jest to jedyny katalog w repozytorium, więc przykładowy marketplace nie potrzebuje pliku dla Codexa. Zaobserwowane:

```bash
codex plugin marketplace add acme/acme-plugins --ref main
codex plugin add acme-api-style@acme-plugins
codex plugin list
# Marketplace `acme-plugins`
# …/.claude-plugin/marketplace.json
# acme-api-style@acme-plugins  installed, enabled  1.0.0
```

Codex zapisuje wynik w `config.toml` jako `[marketplaces.acme-plugins]` i `[plugins."acme-api-style@acme-plugins"] enabled = true`. Codex kopiuje katalog `skills/` każdej wtyczki do `plugins/cache/acme-plugins/<plugin>/<version>/`; zanim ogłosisz wsparcie dla Codexa, otwórz sesję i uruchom `/skills`, żeby potwierdzić, że skille się ładują.

Katalog dla Codexa dodaj tylko wtedy, gdy potrzebujesz pól specyficznych dla Codexa, takich jak `policy`. Gdy istnieje `.agents/plugins/marketplace.json`, Codex używa go zamiast pliku Claude, więc obie listy muszą być identyczne:

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

Jeśli go dodasz, dopisz do skryptu CI jedną linię: `diff <(jq -r '.plugins[].name' .claude-plugin/marketplace.json | sort) <(jq -r '.plugins[].name' .agents/plugins/marketplace.json | sort)`.

**Cursor**

Cursor potrzebuje własnego katalogu w `.cursor-plugin/marketplace.json` oraz pliku `.cursor-plugin/plugin.json` w katalogu każdej wtyczki. Dokumentacja pluginów Cursora (czytana 2026-10-12) wymienia dwa formaty, Agent Plugins z `plugin.json` w katalogu głównym pluginu i Cursor Plugins z `.cursor-plugin/plugin.json`; poniższe pliki używają drugiego. Skille w `skills/` działają bez zmian. Poniższe pliki przechodzą schematy JSON i walidator `scripts/validate-plugins.mjs` z oficjalnego repozytorium Cursora `cursor/plugins` (commit z 25 września 2026):

```json title=".cursor-plugin/marketplace.json"
{
  "name": "acme-plugins",
  "owner": { "name": "Acme Platform Team", "email": "platform@acme.example" },
  "metadata": { "description": "Internal plugins for Acme engineering" },
  "plugins": [
    { "name": "acme-release", "source": "plugins/acme-release", "description": "Release checklist skill: changelog, migrations, feature flags" },
    { "name": "acme-api-style", "source": "plugins/acme-api-style", "description": "Acme REST conventions: error envelope, pagination, versioning" }
  ]
}
```

```json title="plugins/acme-api-style/.cursor-plugin/plugin.json"
{
  "name": "acme-api-style",
  "version": "1.0.0",
  "description": "Acme REST conventions: error envelope, pagination, versioning",
  "author": { "name": "Acme Platform Team" },
  "skills": "./skills/"
}
```

Nie kopiuj katalogu Claude. Schemat Cursora zabrania nieznanych kluczy na najwyższym poziomie, więc `description` z pliku Claude kończy się błędem `must NOT have additional properties`; Cursor oczekuje go w `metadata`. Żeby pilnować tego w CI, skopiuj `schemas/` i `scripts/validate-plugins.mjs` z `cursor/plugins`, zainstaluj `ajv` i `ajv-formats` i uruchom `node scripts/validate-plugins.mjs`. Walidator zgłasza też brakujący katalog `source`. Oba pliki `plugin.json` danej wtyczki trzymaj w tej samej wersji; reguła wersji w CI sprawdza tylko plik Claude, więc dopisz do niej ścieżkę Cursora, jeśli zależy ci na użytkownikach Cursora.

Import opiera się na **źródłach wtórnych** (dokumentacja Cursora była niedostępna 26 września 2026): w planie Teams lub Enterprise administrator otwiera **Dashboard → Settings → Plugins → Team Marketplaces → Import**, wkleja adres repozytorium, wybiera grupy dostępu i oznacza każdą wtyczkę jako **Required** albo **Optional**. Członkowie zespołu instalują przez `/add-plugin` w czacie Agenta. README jednego ze społecznościowych szablonów podaje, że plan Teams dostaje jeden marketplace zespołu; potwierdź ten limit w swoim panelu.

Agenci bez interfejsu w CI albo w kontenerach też potrzebują wtyczek. Zbuduj raz katalog startowy przez `CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin install …`, uruchamiaj agenta z `CLAUDE_CODE_PLUGIN_SEED_DIR=/opt/claude-seed` i ustaw `CLAUDE_CODE_SYNC_PLUGIN_INSTALL=1`, żeby uruchomienie z `-p` czekało na instalacje. Resztę tej konfiguracji opisuje strona o [agentach bez interfejsu w CI](/pl/ecosystem/agent-tools/headless-agents-ci/).

**Prompt do skopiowania: podłącz repozytorium do marketplace'u zespołu**

```text
Wire this repository to the acme-plugins marketplace (GitHub repo acme/acme-plugins). Run `claude plugin marketplace add acme/acme-plugins --scope project` and `claude plugin install acme-api-style@acme-plugins --scope project`, then show me the resulting .claude/settings.json. Add a "Team plugins" section to README.md that tells a new teammate to run `gh auth login`, `gh auth setup-git`, `git ls-remote https://github.com/acme/acme-plugins.git` and the same install command, and to confirm with `claude plugin list` that acme-api-style shows the current version. Do not add any token or credential to any file. Stop before committing.
```

## Jak duże są publiczne marketplace'y wtyczek i ile kontekstu kosztuje wtyczka zespołu

Na dzień 26 września 2026 katalog Anthropic `claude-plugins-official` miał 314 pozycji, `openai-curated` Codexa miał 65, a `cursor-plugins` Cursora 94 (policzone z pliku marketplace'u w każdym repozytorium). Największy wieloagentowy zewnętrzny marketplace w naszym researchu, `wshobson/agents` (nazwa marketplace'u `claude-code-workflows`), zawierał 94 wtyczki z katalogiem dla Claude i dla Codexa i miał 39 978 gwiazdek na GitHubie (GitHub API, 26 września 2026). Prywatne marketplace'y nie mają publicznych liczników.

Przykładowe wtyczki kosztują 49 i 68 tokenów stale obecnych w każdej sesji (`claude plugin details`, 2.1.283), razem około 117. Wtyczki złożone wyłącznie ze skilli są tanie; wtyczka z wieloma skillami albo serwerem MCP kosztuje więcej, a na 2.1.283 liczba z `claude plugin details` może nie obejmować schematów narzędzi MCP, więc sprawdź też `/context` w sesji. Wypisuj stały koszt w CI, tak jak robi to skrypt, i traktuj jego skok na review jako pytanie o projekt wtyczki.

**Pułapki prywatnego marketplace'u**

- Zaliczone `validate --strict` nie dowodzi, że marketplace się instaluje: zastrzeżone nazwy i brakujące katalogi `source` wychodzą dopiero przy `marketplace add` albo `install`. Trzymaj testową instalację w CI.
- Dopóki `plugin.json` ma `version`, wypchnięty commit bez nowej wersji nie trafia do nikogo. `plugin.json` wygrywa z `version` w katalogu, więc trzymaj wersję w jednym miejscu.
- `enabledPlugins` w `.claude/settings.json` włącza; nie instaluje.
- Katalogi Claude i Cursora nie są wymienne: Cursor odrzuca `description` na najwyższym poziomie.
- Sam `GITHUB_TOKEN` nie uwierzytelnia prywatnego klonu. Użyj credential helpera.
- Pisownia się różni: `claude plugin install` i `claude plugin marketplace update`, ale `codex plugin add` i `codex plugin marketplace upgrade` (sprawdzone na Claude Code 2.1.283 i codex-cli 0.157.1).
- Nigdy nie zmieniaj po prostu `name` opublikowanej wtyczki ani marketplace'u: z niej powstaje każdy identyfikator instalacji i każdy skill z przestrzenią nazw (`/acme-release:release-check`). Zmiana nazwy wtyczki idzie przez mapę `renames` w katalogu.

## Co psuje się w marketplace zespołu i jak to naprawić

- **Po merge ludzie dalej korzystają ze starego skilla.** Wersja się nie zmieniła albo nikt nie zaktualizował. Podbij `version`, otaguj i roześlij polecenia aktualizacji; sprawdź przez `claude plugin list`. Dodaj krok podbicia wersji do CI, żeby to się nie powtórzyło.
- **`marketplace add` kończy się komunikatem „reserved for official Anthropic marketplaces”.** Zmień nazwę katalogu, zanim ktokolwiek go zainstaluje. Jeśli ludzie już zainstalowali wtyczki, zmiana nazwy zmienia każdy identyfikator instalacji, więc potraktuj ją jak migrację: ogłoś ją i poproś wszystkich o usunięcie starego marketplace'u i dodanie nowego.
- **Musisz zmienić nazwę wtyczki w marketplace.** Nie zmieniaj samego `name`. Dopisz starą nazwę do mapy `renames` w katalogu (`{ "stara-nazwa": "nowa-nazwa" }` albo `null` dla usuniętej wtyczki). Po `claude plugin marketplace update` Claude Code 2.1.283 przenosi wpis `enabledPlugins` każdej osoby z zespołu na nową nazwę, a `claude plugin list` oznacza starą instalację jako „Renamed to …”. Starego identyfikatora nie rozwiązuje: `install` i `update` po starej nazwie kończą się błędem „not found”, więc zespół uruchamia `claude plugin install <nowa-nazwa>@acme-plugins`. Zostaw stare wpisy w mapie.
- **Instalacja kończy się błędem `Source path does not exist`.** Katalog wtyczki przeniesiono albo przemianowano bez zmiany `source`. Popraw pozycję; następny taki błąd wyłapie krok instalacji w CI.
- **Marketplace nie pojawia się na maszynie osoby z zespołu.** Ta osoba nie zaufała folderowi albo jej poświadczenia git nie pozwalają sklonować prywatnego repozytorium. Uruchom `git ls-remote` na adresie repozytorium; jeśli pyta o hasło albo się nie udaje, najpierw napraw `gh auth setup-git` (albo credential helpera swojego hostingu).
- **Zacommitowana wtyczka jest włączona, ale jej nie ma.** `enabledPlugins` nie instaluje. Uruchom na tej maszynie `claude plugin install <name>@acme-plugins --scope project`.
- **Codex instaluje inną listę wtyczek niż Claude Code.** Istnieje `.agents/plugins/marketplace.json` i Codex czyta go zamiast pliku Claude. Zrównaj obie listy i dodaj linię z `diff` do CI.
- **`codex plugin marketplace upgrade` kończy się błędem „not configured as a Git marketplace”.** Marketplace dodano z lokalnej ścieżki. Usuń go i dodaj ponownie z `acme/acme-plugins`.
- **Walidator Cursora zgłasza `must NOT have additional properties`.** Katalog Cursora skopiowano z katalogu Claude. Przenieś `description` do `metadata` i usuń pozostałe klucze właściwe tylko dla Claude.
- **`claude plugin tag` odmawia z powodu niezgodności wersji.** Pozycja w katalogu ma własne `version`. Usuń to pole i otaguj ponownie.

## Dokąd dalej w temacie wtyczek

- [Zbuduj wtyczkę](/pl/ecosystem/plugins/building-plugins/) — Manifesty, skill, hook i serwer MCP w jednej wtyczce, z testami eval i hooków.
- [Przegląd wtyczek i marketplace'ów](/pl/ecosystem/plugins/) — Instalacja, pomiar i lista dozwolonych wtyczek w każdym agencie.
- [Marketplace'y i rejestry](/pl/ecosystem/plugins/marketplaces-registries/) — Skąd pochodzą wtyczki, skille i serwery MCP oraz jak przeglądać te z zewnątrz.
- [Jedna polityka dla wszystkich agentów kodujących](/pl/org/managed-policy/) — Ustawienia zarządzane, dozwolone marketplace'y i wtyczki u wszystkich dostawców.
- [Bezpieczeństwo łańcucha dostaw skilli](/pl/ecosystem/skills/skill-security/) — Co sprawdzić, zanim instrukcje i skrypty wtyczki trafią do zespołu.
