Wewnątrz finestructure-ai/claude-plugin: wtyczka Claude Code w siedmiu plikach

Całe repozytorium to siedem plików

Sklonuj je, a drzewo plików zmieści się na jednym ekranie:

.claude-plugin/
  plugin.json        686 B
  marketplace.json   507 B
commands/
  deploy.md          3.3 KB
  fs-domain.md       905 B
  fs-status.md       741 B
skills/
  fine-structure/
    SKILL.md         4.0 KB
LICENSE              MIT
README.md            2.3 KB

Żadnego package.json, żadnego pliku blokady, żadnego CI, żadnego dist. Nic nie jest kompilowane ani pakowane i nie istnieje taka wersja tego repozytorium, której budowanie mogłoby się nie powieść. Jeśli odkładasz napisanie wtyczki, bo zakładasz, że potrzebny jest do tego łańcuch narzędzi, oto sprostowanie: format to konwencja katalogów plus dwa pliki JSON, a cała reszta to proza.

Plik plugin.json to wskaźnik, a nie program

Manifest niesie zwykłe pola tożsamości (name, wersja 0.1.0, description, author, homepage, repository, license, keywords), a po nich jeden blok, który wykonuje całą interesującą robotę:

"mcpServers": {
  "finestructure": {
    "type": "http",
    "url": "https://finestructure.ai/api/mcp"
  }
}

Dwa klucze. Żadnego command, żadnych args, żadnego env. Porównaj to z kształtem, jaki przyjmuje większość konfiguracji MCP: lokalny proces (npx, uvx, ścieżka do binarki), lista argumentów i mapa env z kluczem API. Zadeklarowanie zamiast tego punktu końcowego streamable HTTP wynosi serwer poza maszynę użytkownika i właśnie dlatego 105 narzędzi (tyle podaje plik skill) stoi za manifestem o wielkości 686 bajtów. Nic w wersji Node ani Python u użytkownika nie zepsuje instalacji, a zmiany po stronie serwera docierają bez wydania nowej wersji wtyczki. Ceną jest powtarzalność: zestawu narzędzi nie zamrozisz po stronie klienta.

Plik marketplace.json czyni z repozytorium jego własny kanał dystrybucji

Claude Code instaluje wtyczki z marketplace'ów, a nie z rejestru pakietów, a marketplace to plik JSON wymieniający wtyczki wraz ze ścieżką źródła. Drugi plik w katalogu .claude-plugin robi dokładnie to, a jego jedyny wpis wtyczki ma "source": "./". Repozytorium jest jednocześnie wtyczką i serwującym ją marketplace'em, więc publikacja sprowadza się do publicznego git push:

/plugin marketplace add finestructure-ai/claude-plugin
/plugin install finestructure@finestructure

Dwa identyczne tokeny w drugim wierszu to nazwa wtyczki przy nazwie marketplace'u, a kolidują, bo obie brzmią finestructure. Jeśli kopiujesz ten układ, nadaj im różne nazwy. Instrukcja instalacji staje się czytelniejsza, a tobie zostaje miejsce na dodanie później drugiej wtyczki.

Komendy to szablony promptów z frontmatterem

Każdy plik w katalogu commands/ to frontmatter w YAML plus proza. Plik deploy.md deklaruje description i argument-hint, czyli dwa napisy, które użytkownik widzi na liście wyboru, a potem rozkłada ponumerowane drzewo decyzyjne: sprawdź w katalogu głównym projektu, czy jest .finestructure.json z app_id, w przeciwnym razie wywołaj list_apps i poszukaj dopasowania nazwy, a jeśli i tego nie ma, potraktuj rzecz jako pierwsze wdrożenie i użyj $ARGUMENTS jako nazwy aplikacji. Plik fs-status.md waży 741 bajtów i wykonuje pracę podpolecenia CLI: ustal aplikację, wywołaj get_app_status, get_app_links i get_errors, podsumuj. Plik fs-domain.md przechodzi po kolei przez add_custom_domain, get_domain_verification, check_domain_verification, get_domain_ssl_status i set_primary_domain.

Sedno projektu: żaden z tych plików niczego nie wywołuje. Nazywają narzędzia, ustalają kolejność i opisują, co robić, gdy krok się nie powiedzie. Wykonanie następuje wtedy, gdy model sięga po narzędzia MCP. Komenda ze slashem to prompt trzymany w kontroli wersji, więc jej przegląd nie jest pytaniem, czy logika jest poprawna, tylko pytaniem, czy instrukcja nie jest dwuznaczna.

Najlepsze wiersze to te zakazujące. Plik deploy.md zabrania narzędzi usuwania, o ile użytkownik nie poprosi wprost. Plik fs-domain.md zauważa, że propagacja DNS trwa od minut do godzin, i każe zaproponować ponowną próbę później, zamiast kręcić się w pętli weryfikacji. To polityka ponawiania i barierki bezpieczeństwa zapisane zdaniami, i właśnie tego brakuje naiwnym wtyczkom.

skill kontra command: przyciąganie kontra popychanie

Plik skills/fine-structure/SKILL.md ma dwa pola frontmattera, name i description, przy czym description czyta się jak warunek uruchomienia, a nie streszczenie: używaj zawsze, gdy użytkownik chce wdrożyć, utworzyć lub zaktualizować aplikację, podpiąć domenę, zarządzać danymi albo sekretami. To sformułowanie jest celowe. Komenda odpala się, bo człowiek ją wpisał. Skill odpala się, bo model dopasował opis do tego, co się właśnie dzieje.

Za tym idzie podział treści. Plik SKILL.md to model myślowy, a nie lista zadań: czym jest tu aplikacja (strony JSX, wspólne komponenty, schematy encji, żadnego dowolnego kodu serwerowego), czym są encje, które operacje kosztują kredyty. Dalej przepływy pracy jako łańcuchy narzędzi: get_app_files, potem read_app_file, potem write_app_file, potem validate_app, potem publish_app, ze zbiorami zmian dla edycji obejmujących wiele plików. Dalej semantyka błędów, która na bajt waży najwięcej: błędy uwierzytelniania oznaczają ponowne połączenie, błędy kredytów oznaczają doładowanie, i żadnego z nich nie ma sensu ponawiać. Agent bez tej wiedzy ponawia w pętli awarię, której ponawiać nie warto, a na platformie z licznikiem taka pętla ma swoją cenę.

Reguła dla twojej własnej wtyczki wychodzi z tego czysto. Jeśli plik komendy tłumaczy, czym jest twój produkt, ten akapit należy do skilla. Komendy zostają procedurami.

OAuth to powód, dla którego w manifeście nie ma sekretów

Punkt końcowy uwierzytelnia się przez OAuth 2.1 z dynamiczną rejestracją klienta, więc pierwsze wywołanie narzędzia otwiera w przeglądarce stronę zgody, a token ląduje w magazynie poświadczeń Claude Code, nie w repozytorium. Fork jest bezpieczny z konstrukcji, unieważnienie dostępu dzieje się po stronie serwera, a nie jako zmiana konfiguracji, która musi dotrzeć do każdej maszyny, i nikt nie jest proszony o wklejenie długowiecznego klucza do pliku, któremu do publicznego diffa brakuje jednego nieuważnego commita.

Co skopiować do własnej wtyczki

Konkretne wskazówki, mniej więcej w kolejności budowania:

• Zacznij od .claude-plugin/plugin.json z name, version i description. Cała reszta jest opcjonalna.
• Jeśli prowadzisz hostowany punkt końcowy MCP, zadeklaruj "type": "http" z url zamiast lokalnej komendy. To usuwa środowisko uruchomieniowe użytkownika z obszaru twojego wsparcia.
• Dopóki masz jedną wtyczkę, dołóż marketplace.json w tym samym repozytorium z "source": "./" i nadaj mu nazwę inną niż nazwa wtyczki.
• Daj każdej komendzie description i argument-hint we frontmatterze, napisane jako odpowiedzi na pytania, co to robi i co wpisać po tym.
• Używaj $ARGUMENTS zamiast wymyślać składnię pozycyjną. Nie ma tu parsera, jest tylko podstawienie.
• Pisz treść komend jako drzewa decyzyjne z jawnie nazwanymi narzędziami. Zdanie "jeśli plik konfiguracyjny istnieje, odczytaj app_id, w przeciwnym razie wywołaj list_apps" broni się lepiej niż akapit o intencjach.
• Zapisz semantykę awarii: które błędy są ostateczne, które można ponowić, co powiedzieć zamiast ponawiania.
• Nazwij swoje destrukcyjne narzędzia w tekście i zabroń ich, dopóki nikt o nie nie poprosi.
• Trzymaj model dziedziny w SKILL.md, a procedurę w komendzie. Duplikacja między nimi to zły znak.
• Przetestuj przez /plugin marketplace add na lokalnej ścieżce albo na własnym forku, zanim skierujesz kogokolwiek na main.

Chropowate krawędzie

Trzy uczciwie wskazane, żadna nie jest zabójcza. Wszystko jest po angielsku, a format nie daje żadnego zaczepienia, żeby to naprawić: we frontmatterze nie ma klucza locale, więc lokalizacja oznacza albo duplikowanie plików komend, albo pogodzenie się z niedopasowaniem.

Opowieść o braku kluczy API ma gwiazdkę. Plik SKILL.md przyznaje, że narzędzia do generowania mediów są poza połączeniem OAuth i potrzebują statycznego tokenu MCP z zakresami mediów, tworzonego w Studio platformy i wysyłanego w nagłówku bearer. Wtyczka radzi sobie z tym dobrze, każe modelowi wyjaśnić brak zamiast ponawiać próby pod ścianą, ale to druga ścieżka uwierzytelniania przykręcona do projektu, którego atutem jest posiadanie jednej.

No i to wersja 0.1.0 bez changeloga, testów i CI. Dla markdownu jest to do obrony, choć sprawdzenie schematu JSON w hooku pre-commit wyłapywałoby jedyną klasę błędów, która naprawdę psuje instalacje, czyli zniekształcony manifest. Zgłoszenie do katalogu jest w chwili pisania w recenzji, więc na razie instaluje się przez odwołanie do repozytorium.

Przeczytaj najpierw trzy pliki komend, potem SKILL.md, a na końcu dwa pliki JSON. W tej kolejności format tłumaczy się sam: markdown decyduje, co ma się zdarzyć i w jakiej kolejności, serwer MCP decyduje, co faktycznie się wykonuje, a manifest to cienki szew między nimi.