My Architect, część 5: dystrybucja skilli i MCP przez marketplace Claude Code

To finał serii o My Architect — systemie, w którym projekt żyje pomiędzy sesjami agenta AI. W części 1 tłumaczyłem, po co agentowi pamięć i plan. Dziś ostatni element układanki: jak to wszystko trafia na maszynę użytkownika za pomocą dwóch komend.

Problem ostatniej mili

Z perspektywy użytkownika My Architect to trzy rzeczy. Serwer MCP @my-architect/mcp, który daje agentowi trzydzieści parę narzędzi. Skill myarchitect — reguły zachowania: kiedy agent sam zakłada node dla odłożonego buga, a kiedy zatrzymuje się i pyta. I cztery slash commands do typowych scenariuszy.

Kiedyś instalacja wyglądała jak instrukcja na pół strony. Otwórz .mcp.json, wpisz konfigurację serwera, nie pomyl nazwy zmiennej środowiskowej. Pobierz SKILL.md, wrzuć do ~/.claude/skills/, powtórz na służbowym laptopie. Każdy ręczny krok to miejsce, w którym człowiek odpada, a u mnie przybywa kolejna kopia skilla, o której aktualizacji muszę pamiętać.

Plugin marketplace w Claude Code zamknął tę dziurę. Marketplace to zwykłe publiczne repozytorium git z plikiem manifestu, a plugin w jego środku to folder z konfiguracją, skillem i komendami. Żadnej rejestracji, żadnej moderacji, żadnego sklepu: repo na GitHubie jest kanałem dystrybucji.

Instalacja oczami użytkownika

Token wystarczy wyeksportować raz (bierze się go w Settings → Connect Agent na stronie):

export MCP_API_KEY=mcp_TWOJ_TOKEN

Dalej dwie komendy wewnątrz Claude Code:

/plugin marketplace add d7561985/my-architect-marketplace
/plugin install my-architect@my-architect-marketplace

Weryfikacja — /mcp: serwer my-architect powinien figurować jako podłączony.

Za kulisami Claude Code klonuje repozytorium, parsuje manifest, rejestruje skill i slash commands, a przy starcie sesji odpala serwer MCP komendą npx -y @my-architect/mcp@latest. Użytkownik nie edytował ręcznie ani jednego pliku. Tamta instrukcja na pół strony skurczyła się do trzech linijek, w których prawie nic nie może się popsuć.

Anatomia: dwa manifesty i markdown

Główny marketplace.json to cienka otoczka: nazwa, właściciel, lista pluginów z linkami do folderów. Pole $schema wskazuje na schemat z json.schemastore.org, więc edytor podświetla błędy jeszcze przed commitem.

Cała merytoryczna część siedzi w plugin.json pluginu:

{
  "name": "my-architect",
  "version": "1.4.0",
  "mcpServers": {
    "my-architect": {
      "command": "npx",
      "args": ["-y", "@my-architect/mcp@latest"],
      "env": {
        "MCP_API_KEY": "${MCP_API_KEY}",
        "MA_API_URL": "https://my-architect.app"
      }
    }
  }
}

Ważna jest tu jedna linijka: "${MCP_API_KEY}". To podstawienie ze środowiska shella użytkownika w momencie uruchomienia. Repozytorium jest publiczne i sekrety nie mają w nim czego szukać — token żyje u użytkownika w ~/.zshrc i nigdy nie opuszcza jego maszyny.

Reszta to markdown. SKILL.md z frontmatterem YAML (name i description, na podstawie którego Claude decyduje, kiedy załadować skill), oraz commands/*.md — cztery pliki, z których każdy staje się slash command w rodzaju /my-architect:next. Komendy to cienkie promptowe nakładki na skill: „weź następne zadanie i prowadź je przez Workflow D".

Kodu serwera tu nie ma

W repozytorium marketplace'u nie ma ani linijki TypeScriptu. Serwer MCP żyje w prywatnym repo produktowym i jest publikowany do npm, a plugin odwołuje się do @my-architect/mcp@latest. Wyszła nowa wersja serwera z nowymi narzędziami — użytkownicy dostają ją przy następnym uruchomieniu Claude Code, zupełnie bez żadnych działań z ich strony i bez release'u pluginu.

Ze skillem jest odwrotnie, i to świadoma decyzja. SKILL.md leży w publicznym repo jako jedyne źródło prawdy. Prywatne repozytorium produktowe z zasady nie trzyma kopii: przeszedłem już okres, w którym jedna wersja skilla żyła w ~/.claude/skills/ jako instalacja osobista, druga w produkcie, i po cichu się rozjeżdżały. Teraz reguła jest zapisana wprost w CLAUDE.md marketplace'u: edytujemy tutaj, pushujemy stąd, użytkownicy ciągną stąd. Każda znaleziona kopia jest z definicji nieaktualna.

Dyscyplina wersji

Marketplace ma nieoczywistą konsekwencję: /plugin update my-architect zadziała tylko wtedy, gdy wersja w plugin.json się zmieniła. Poprawisz sformułowanie w SKILL.md i wypchniesz bez bumpa — żaden użytkownik tego nie zobaczy, aktualizacja po prostu nie zostanie zaproponowana. Dlatego reguła jest twarda: każda widoczna zmiana to bump wersji plus wpis w CHANGELOG, nawet jeśli zmieniło się jedno słowo.

Przed publikacją — claude plugin validate .: oba manifesty i frontmatter skilla muszą się sparsować. Release domyka komenda claude plugin tag, która sprawdza wzajemną zgodność wersji w plugin.json, wpisu w marketplace i tworzonego git taga i dopiero potem nadaje tag w rodzaju my-architect--v1.4.0. Spójność wersji weryfikuje narzędzie, a nie moja uważność, i to jest właściwy podział obowiązków.

Półtora miesiąca w changelogu

Plugin żyje od końca kwietnia, a jego changelog okazał się kroniką tego, jak zmieniało się moje rozumienie pracy agenta z architektem:

v1.0.0 (29 kwietnia) — skill jako proaktywny tracker backlogu plus autokonfiguracja serwera MCP.
v1.1.0 (29 maja) — Workflow C: dokumenty na node'ach jako source of truth, validate_project przed zamknięciem zadania.
v1.2.0 (5 czerwca) — Workflow D: architekt przestał być dziennikiem pisanym po fakcie, skill wymaga teraz czytania node'a i dokumentów przed kodem i aktualizowania ich w trakcie pracy.
v1.3.0 (7 czerwca) — cztery slash commands: next, progress, doc, reconcile.
v1.4.0 (7 czerwca) — zaostrzona reguła nazewnictwa node'ów: encja, nie praca, z linterem po stronie serwera.

Zauważcie: cztery merytoryczne release'y w pięć tygodni i żaden nie wymagał od użytkowników niczego poza /plugin update.

Podsumowanie serii

Pięć części składa się w jedną myśl. Agent jest dokładnie tak silny, jak dobre jest zewnętrzne rusztowanie wokół niego.

W części 1 — po co to rusztowanie jest potrzebne: pamięcią agenta nie jest okno kontekstu, lecz struktura projektu, którą czyta w jednym wywołaniu. W części 2 — na czym ono stoi: pliki YAML zamiast bazy, atomowy zapis i żywa synchronizacja z kanwą. W części 3 — jak zmusić agenta, żeby planował jak architekt: hierarchia, dziedziczone wymagania, User Story Map. W części 4 — cykl pracy od get_next_task do complete_task z dokumentacją jako częścią zadania. A dziś — ostatnia mila: to wszystko instaluje się dwiema komendami i aktualizuje jedną.

Wypróbować można na my-architect.app: konto, token, dwie komendy w Claude Code. Jeśli coś nie będzie się zgadzać z tym, co tu napisałem — napiszcie do mnie, takie wiadomości są cenniejsze niż pochwały.