Przejdź do głównej zawartości
AI Developer Toolkit

Prywatny marketplace wtyczek dla zespołu

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ę; tutaj prowadzisz kanał, który ją dostarcza.

Co daje działający marketplace zespołu

Dział zatytułowany „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

Dział zatytułowany „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.

EtapKtoKontrola, która to udowadniaNarzędzie
Pull requestAutor wtyczkiCI: ścisła walidacja, testowa instalacja, reguła podbicia wersjiscripts/check-marketplace.sh
ReviewWłaściciel w CODEOWNERSZielone CI, podbita wersja, stały koszt tokenów odczytany z logu CIReview na GitHubie
WydanieWłaściciel marketplace’uclaude plugin tag sprawdza zgodność plugin.json z katalogiemclaude plugin tag --push
WdrożenieKaż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

Dział zatytułowany „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.

    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.

    .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.

    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" }
    }
    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.

    .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.

Zwaliduj marketplace w CI, zanim ktokolwiek z niego zainstaluje

Dział zatytułowany „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.

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:

.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.

Wydaj wersję wtyczki i dostarcz ją zespołowi

Dział zatytułowany „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>:

    Okno terminala
    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:

    Okno terminala
    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.

  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

Dział zatytułowany „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.

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żkaPolecenie lub plikCo robi
Dla każdej osobyclaude plugin marketplace add acme/acme-plugins, potem claude plugin install acme-api-style@acme-pluginsDodaje i instaluje w zakresie użytkownika
Dla repozytoriumclaude plugin marketplace add acme/acme-plugins --scope project i claude plugin install acme-api-style@acme-plugins --scope project, potem zacommituj .claude/settings.jsonDeklaruje marketplace w extraKnownMarketplaces i włącza wtyczkę w enabledPlugins
Dla całej flotyUstawienia 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 EnterpriseOrganization settings → Plugins & skillsSynchronizuje 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).

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.

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.

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

Dział zatytułowany „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.

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

Dział zatytułowany „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

Dział zatytułowany „Dokąd dalej w temacie wtyczek”
Zbuduj wtyczkę Manifesty, skill, hook i serwer MCP w jednej wtyczce, z testami eval i hooków.
Przegląd wtyczek i marketplace'ów Instalacja, pomiar i lista dozwolonych wtyczek w każdym agencie.
Marketplace'y i rejestry Skąd pochodzą wtyczki, skille i serwery MCP oraz jak przeglądać te z zewnątrz.
Jedna polityka dla wszystkich agentów kodujących Ustawienia zarządzane, dozwolone marketplace'y i wtyczki u wszystkich dostawców.
Bezpieczeństwo łańcucha dostaw skilli Co sprawdzić, zanim instrukcje i skrypty wtyczki trafią do zespołu.

Autor:

Zobacz co nowego na platformie.

Polityka prywatności Regulamin Ustawienia cookie