Innenansicht von finestructure-ai/claude-plugin: ein Claude Code Plugin in sieben Dateien

Das ganze Repository sind sieben Dateien

Klonen Sie es, und der Dateibaum passt auf einen Bildschirm:

.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

Keine package.json, keine Lockdatei, kein CI, kein dist. Nichts wird kompiliert oder gebündelt, und es gibt keine Version dieses Repositorys, deren Build fehlschlagen könnte. Wer das Schreiben eines Plugins aufgeschoben hat, weil er eine Toolchain vermutete, bekommt hier die Korrektur: Das Format ist eine Verzeichniskonvention plus zwei JSON-Dateien, der Rest ist Prosa.

plugin.json ist ein Zeiger, kein Programm

Das Manifest trägt die üblichen Identitätsfelder (name, Version 0.1.0, description, author, homepage, repository, license, keywords) und danach einen einzigen Block, der die ganze interessante Arbeit leistet:

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

Zwei Schlüssel. Kein command, keine args, kein env. Vergleichen Sie das mit der Form, die die meisten MCP-Konfigurationen annehmen: ein lokaler Prozess (npx, uvx, ein Pfad zu einer Binärdatei), eine Argumentliste und eine env-Map mit einem API-Schlüssel. Stattdessen einen streamable HTTP Endpunkt zu deklarieren, verlagert den Server vom Rechner der Anwender weg, und deshalb stehen 105 Werkzeuge (die Zahl, die die Skill-Datei nennt) hinter einem Manifest von 686 Byte. Nichts an der Node- oder Python-Version der Anwender kann die Installation zerlegen, und serverseitige Änderungen gehen ohne Plugin-Release live. Der Preis ist die Reproduzierbarkeit: Die Werkzeugoberfläche lässt sich clientseitig nicht festnageln.

marketplace.json macht das Repository zu seinem eigenen Vertriebskanal

Claude Code installiert Plugins aus Marketplaces und nicht aus einer Paketregistry, und ein Marketplace ist eine JSON-Datei, die Plugins mit einem Quellpfad auflistet. Die zweite Datei in .claude-plugin tut genau das, und ihr einziger Plugin-Eintrag trägt "source": "./". Das Repository ist zugleich das Plugin und der Marketplace, der es ausliefert, also ist Veröffentlichen ein öffentlicher git push:

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

Die beiden identischen Tokens in der zweiten Zeile sind Plugin-Name bei Marketplace-Name, und sie fallen zusammen, weil beide finestructure heißen. Wer dieses Layout übernimmt, sollte sie unterschiedlich benennen. Die Installationsanweisung wird klarer, und es bleibt Platz, später ein zweites Plugin zu ergänzen.

Befehle sind Prompt-Vorlagen mit Frontmatter

Jede Datei in commands/ besteht aus YAML-Frontmatter plus Prosa. deploy.md deklariert ein description und einen argument-hint, die beiden Zeichenketten, die im Auswahlmenü erscheinen, und legt dann einen nummerierten Entscheidungsbaum aus: im Projektwurzelverzeichnis nach einer .finestructure.json mit einer app_id sehen, sonst list_apps aufrufen und nach einer Namensübereinstimmung suchen, sonst den Fall als ersten Rollout behandeln und $ARGUMENTS als App-Namen verwenden. fs-status.md wiegt 741 Byte und erledigt die Arbeit eines CLI-Unterbefehls: die App auflösen, get_app_status, get_app_links und get_errors aufrufen, zusammenfassen. fs-domain.md geht der Reihe nach durch add_custom_domain, get_domain_verification, check_domain_verification, get_domain_ssl_status und set_primary_domain.

Der Entwurfspunkt: Keine dieser Dateien ruft irgendetwas auf. Sie benennen Werkzeuge, legen eine Reihenfolge fest und beschreiben, was bei einem fehlgeschlagenen Schritt zu tun ist. Ausgeführt wird erst, wenn das Modell MCP-Werkzeuge aufruft. Ein Slash-Befehl ist ein eingecheckter Prompt, und ihn zu prüfen heißt daher nicht zu fragen, ob die Logik stimmt, sondern ob die Anweisung mehrdeutig ist.

Die besten Zeilen sind die verneinenden. deploy.md verbietet Löschwerkzeuge, sofern nicht ausdrücklich danach gefragt wurde. fs-domain.md hält fest, dass die DNS-Verbreitung Minuten bis Stunden dauert, und weist an, einen späteren Versuch vorzuschlagen, statt in einer Prüfschleife zu hängen. Das ist Wiederholungsrichtlinie und Leitplanke, in Sätzen geschrieben, und genau das lassen naive Plugins weg.

Skill gegen Command: ziehen gegen schieben

skills/fine-structure/SKILL.md hat zwei Frontmatter-Felder, name und description, und die description liest sich als Auslösebedingung statt als Zusammenfassung: zu verwenden, sobald jemand eine App ausrollen, anlegen oder aktualisieren, eine Domain verbinden oder Daten und Secrets verwalten will. Diese Formulierung ist Absicht. Ein Befehl feuert, weil ein Mensch ihn getippt hat. Ein Skill feuert, weil das Modell die Beschreibung mit der Lage abgeglichen hat.

Die Aufteilung der Inhalte folgt daraus. SKILL.md ist ein Denkmodell, keine Aufgabenliste: was eine App hier ist (JSX-Seiten, gemeinsame Komponenten, Entity-Schemata, kein beliebiger Servercode), was Entitäten sind, welche Operationen Credits kosten. Danach Arbeitsabläufe als Werkzeugketten, von get_app_files über read_app_file und write_app_file zu validate_app und publish_app, mit Change Sets für Änderungen an mehreren Dateien. Danach die Fehlersemantik, die pro Byte das meiste Gewicht trägt: Authentifizierungsfehler heißen neu verbinden, Credit-Fehler heißen aufladen, und keiner von beiden ist wiederholbar. Ein Agent ohne dieses Wissen wiederholt einen nicht wiederholbaren Fehlschlag in einer Schleife, und auf einer abgerechneten Plattform kostet diese Schleife Geld.

Die Regel für das eigene Plugin ergibt sich sauber. Wenn eine Befehlsdatei erklärt, was das Produkt ist, gehört dieser Absatz in den Skill. Befehle bleiben Prozeduren.

OAuth ist der Grund, warum das Manifest keine Geheimnisse enthält

Der Endpunkt authentifiziert über OAuth 2.1 mit dynamischer Client-Registrierung, deshalb öffnet der erste Werkzeugaufruf eine Zustimmungsseite im Browser, und das Token landet im Credential-Store von Claude Code, nicht im Repository. Ein Fork ist bauartbedingt sicher, der Entzug erfolgt serverseitig statt als Konfigurationsänderung, die jede Maschine erreichen muss, und niemand wird gebeten, einen langlebigen Schlüssel in eine Datei zu kleben, die nur einen unachtsamen Commit von einem öffentlichen Diff entfernt liegt.

Was für das eigene Plugin zu übernehmen ist

Konkrete Hinweise, ungefähr in der Reihenfolge des Aufbaus:

• Beginnen Sie mit .claude-plugin/plugin.json und den Feldern name, version und description. Alles Weitere ist optional.
• Wer einen gehosteten MCP-Endpunkt betreibt, deklariert "type": "http" mit einer url statt eines lokalen Befehls. Das streicht die Laufzeitumgebung der Anwender aus der eigenen Supportfläche.
• Liefern Sie marketplace.json im selben Repository mit "source": "./" aus, solange es ein einziges Plugin gibt, und geben Sie ihr einen anderen Namen als dem Plugin.
• Geben Sie jedem Befehl im Frontmatter ein description und einen argument-hint, geschrieben als Antworten auf die Fragen was tut das und was tippe ich dahinter.
• Nutzen Sie $ARGUMENTS, statt eine positionsabhängige Syntax zu erfinden. Es gibt keinen Parser, nur Ersetzung.
• Schreiben Sie Befehlskörper als Entscheidungsbäume mit ausdrücklich benannten Werkzeugen. "Wenn die Konfigurationsdatei existiert, lies app_id, sonst rufe list_apps auf" hält besser als ein Absatz voller Absichten.
• Halten Sie die Fehlersemantik schriftlich fest: welche Fehler endgültig sind, welche wiederholbar, und was statt eines erneuten Versuchs zu sagen ist.
• Benennen Sie zerstörerische Werkzeuge in der Prosa und verbieten Sie sie, solange niemand danach fragt.
• Halten Sie das Domänenmodell in SKILL.md und die Prozedur im Befehl. Doppelungen zwischen beiden sind ein schlechtes Zeichen.
• Testen Sie mit /plugin marketplace add gegen einen lokalen Pfad oder Ihren Fork, bevor Sie jemanden auf main schicken.

Raue Kanten

Drei ehrliche, keine davon tödlich. Alles ist auf Englisch, und das Format bietet keinen Haken, um das zu ändern: Es gibt keinen locale-Schlüssel im Frontmatter, Lokalisierung bedeutet also doppelte Befehlsdateien oder das Hinnehmen der Diskrepanz.

Die Erzählung ohne API-Schlüssel hat ein Sternchen. SKILL.md räumt ein, dass die Werkzeuge zur Medienerzeugung außerhalb der OAuth-Verbindung liegen und ein statisches MCP-Token mit Medien-Scopes brauchen, erzeugt im Studio der Plattform und als bearer-Header geschickt. Das Plugin geht gut damit um und weist das Modell an, das Fehlen zu erklären, statt gegen eine Wand zu wiederholen, aber es ist ein zweiter Authentifizierungspfad, angeschraubt an einen Entwurf, dessen Verkaufsargument der eine Pfad ist.

Und es ist Version 0.1.0 ohne Changelog, Tests oder CI. Für markdown ist das vertretbar, obwohl eine JSON-Schema-Prüfung in einem pre-commit Hook genau die Fehlerklasse abfinge, die Installationen wirklich zerstört: ein fehlerhaftes Manifest. Die Einreichung ins Verzeichnis liegt zum Zeitpunkt des Schreibens in der Prüfung, installiert wird also vorerst über die Repository-Referenz.

Lesen Sie zuerst die drei Befehlsdateien, dann SKILL.md, dann die beiden JSON-Dateien. In dieser Reihenfolge erklärt sich das Format selbst: markdown entscheidet, was geschehen soll und in welcher Reihenfolge, der MCP-Server entscheidet, was tatsächlich läuft, und das Manifest ist die dünne Naht dazwischen.