Communitygithub.com

AntTheLimey/gm-apprentice

Veröffentliche einen gm-apprentice-Kampagnen-Vault als statische Website auf GitHub Pages oder Cloudflare Pages und führe die Änderungsanforderungsschleife am Tisch aus, mit der Spieler während des Spiels Blattänderungen beantragen können.

Was ist gm-apprentice?

Dieses Skill ermöglicht es Spielleitern (SL), einen gm-apprentice-Vault als statische, für Spieler zugängliche Website zu veröffentlichen. Es unterstützt die Hosting-Plattformen Cloudflare Pages (empfohlen für neue Einrichtungen) und GitHub Pages (voll unterstützt). Der Build-Prozess identifiziert Änderungen am Vault, aktualisiert die Seiten entsprechend und stellt sie bereit. Der Skill automatisiert die Ersteinrichtung über ein Schritt-für-Schritt-Wizard, führt Routine-Updates durch, behebt Build-Fehler und verwaltet Schema-Migrationen. Ein besonderes Highlight ist die Änderungsanforderungsschleife (Change-Request-Loop), die es Spielern ermöglicht, während einer Sitzung saubere Änderungen an ihren Charakterblättern (unterstützt GURPS 4e und CoC 7e) einzureichen. Der Skill zielt darauf ab, die technischen Details für nicht-technische SL zu verbergen, indem er Befehle wie `npm`, `git` oder Terminal-Aufrufe erklärt und den gesamten Veröffentlichungsprozess von der Ersteinrichtung bis zur Fehlerbehebung begleitet.

Funktioniert mit✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/AntTheLimey/gm-apprentice/tree/HEAD/skills/publish-site

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Website veröffentlichen

Du verwandelst gm-apprentice-Vault-Inhalte in teilbare statische Websites für TTRPG-SL, gehostet auf Cloudflare Pages (empfohlen für neue Einrichtungen) oder GitHub Pages (voll unterstützt). Die erstellte Website ist in beiden Fällen identisch; host in vault.config.json (cloudflare-pages oder github-pages; fehlt bedeutet github-pages) entscheidet über die Bereitstellung.

Führe SL in einfacher Sprache durch Einrichtung, regelmäßige Aktualisierungen und Fehlerbehebung. Die meisten sind nicht technisch versiert – erkläre, was npm, git oder ein Terminal-Befehl tut, anstatt davon auszugehen, dass sie es wissen.

Versionsprüfung: Führe beim ersten Aufruf python3 "${CLAUDE_PLUGIN_ROOT}/skills/shared/scripts/vault_check.py" <Vault> version aus. OK/SETUP → fortfahren. MISMATCH → die Zeile melden, das references/migration-procedure.md von campaign-organizer ausführen, dann fortfahren. AHEAD → die Zeile melden, den SL bitten, das Plugin zu aktualisieren, anhalten. ERROR → die Zeile melden (defekte Plugin-Installation), anhalten. Keine Ergebniszeile plus einen not a directory Fehler → den SL nach dem korrekten Vault-Pfad fragen.

Das Build-Tool

Die gesamte Build-Logik befindet sich im gm-apprentice-publish-Tool, das in diesem Plugin enthalten ist (niemals aus der npm-Registry installieren und niemals seine Logik replizieren):

<Plugin-Cache-Pfad>/gm-apprentice/<Plugin-Version>/tools/publish

<Plugin-Version> stammt aus .claude-plugin/plugin.json (oder dem eigenen Cache-Pfad dieses Skills). Einmalige Befehle werden aus dem Cache ausgeführt:

TOOL="<Plugin-Cache-Pfad>/gm-apprentice/<Plugin-Version>/tools/publish/bin/gm-publish.js"
node "$TOOL" init <Zielverzeichnis>   # neue Website erstellen (pinnt sich automatisch auf diese Version)
node "$TOOL" update-pin --site <Verzeichnis>                       # umleiten + npm install für eine veraltete Website (außerhalb des Plugins: --tag publish-vX.Y.Z hinzufügen, um auf ein Release-Tarball zu pinnen)
node "$TOOL" manifest diff --config <Verzeichnis>/vault.config.json    # Vault-Dateien mit dem Manifest vergleichen
node "$TOOL" manifest apply --config <Verzeichnis>/vault.config.json ...  # Manifest bearbeiten
node "$TOOL" manifest publish-played --config <Verzeichnis>/vault.config.json  # gespielte Sitzungen registrieren
node "$TOOL" deploy --verify --config <Verzeichnis>/vault.config.json  # Build, Bereitstellung, URL prüfen
node "$TOOL" doctor --site --config <Verzeichnis>/vault.config.json    # Vault auf Veröffentlichungsfehler prüfen
node "$TOOL" explain "<Relativer Vault-Pfad>" --config <Verzeichnis>/vault.config.json  # Veröffentlichungskette einer Datei
node "$TOOL" --version
node "$TOOL" --help

Vor jedem Build oder Deployment, den dieser Skill ausführt, führe node "$TOOL" manifest publish-played --config <Verzeichnis>/vault.config.json selbst aus, damit eine Website niemals ohne eine gespielte Sitzung veröffentlicht wird (#277). Es hakt einen geprüften Sitzungsindex nur zusammen mit einem verlinkten Wrap-Up ein, das veröffentlicht wird, sodass die Website den Hub-Text zurückhält. Es überspringt ausgeschlossene Einträge und tut nichts ohne ein Manifest im Spielermodus. Melde die Pfade, die es eingehakt hat. Jede andere gespielte Sitzung wird als "unklar" mit ihrem Grund aufgelistet (kein Wrap-Up, Wrap-Up noch nicht geprüft, ein ausgeschlossener oder nicht veröffentlichter, oder ein veralteter Website-Pin). Frage den SL einmal, in einer einzigen Frage, und liste sie mit ihren Gründen auf. Bei einer ohne Wrap-Up, die veröffentlicht wird, sage, dass ihr Index-Text wie geschrieben veröffentlicht wird, und schlage vor, zuerst Keeper-Notizen abzuschirmen. Registriere jede genehmigte mit manifest publish-played --config <Verzeichnis>/vault.config.json --session "<Index>" plus --include-unreviewed, wenn sie ein Wrap-Up hat (ungeprüft, oder ein veralteter Pin: es verzichtet nur auf die Prüfungsüberprüfung, also gib jeden Grund weiter, den es trotzdem angibt) oder --publish-body, wenn sie keines hat. Hake niemals einen Sitzungsindex mit manifest apply ein. Hake sie nicht stumm ein; wenn der SL sagt "noch nicht", lasse sie und frage in diesem Durchlauf nicht noch einmal. Wenn ein Grund besagt, dass die Website auf ein älteres Tool gepinnt ist, biete zuerst update-pin --site <Verzeichnis> an. Der Build selbst bleibt schreibgeschützt für den Vault, also lebt dies im Skill, nicht in build/deploy.

Innerhalb einer erstellten Website wird mit npm gebaut (es löst das Tool aus dem file:-Pin der Vorlage auf – keine Registry, kein Netzwerk):

npm install      # verknüpft das gepinnte Build-Tool (Abhängigkeiten werden mitgeliefert)
npm run build    # generiert docs/ aus dem Vault
# Das Blatt eines NSC ausgeben – benötigt vault.config.json, also hier ausführen
npx gm-apprentice-publish sheet show --pc <Name> [--player-safe] [--json]

Node 22+ ist erforderlich; bei einem Versionsfehler schicke den SL zu https://nodejs.org (LTS).

Website-Verzeichnis: Fähigkeiten 2 und 4 lesen publish.site_dir aus _meta/vault-config.md; ein relativer Wert ist relativ zum Vault. Wenn nicht gesetzt, frage nach dem absoluten Pfad zum Website-Repo und biete an, es dort zu speichern. Wenn es überhaupt keine Website gibt, gibt es nichts zu registrieren, also überspringe publish-played.

Neun Fähigkeiten

1. Ersteinrichtung

("meine Kampagne veröffentlichen", "eine Website einrichten", "ich möchte, dass Spieler meine Kampagne sehen")

Folge Schritt für Schritt references/setup-wizard.md – es ist maßgeblich (zuerst Preflight-Doctor, Cloudflare-Standard, fährt von publish.setup_progress fort). Improvisiere nicht und überspringe keine Schritte.

2. Routine-Updates

("meine Website aktualisieren", "neubauen", "ich habe den Vault aktualisiert")

  1. Lokalisiere das Website-Verzeichnis (oben).
  2. node "$TOOL" update-pin --site <Verzeichnis> – melde seine eine Zeile.
  3. node "$TOOL" manifest diff --config <Verzeichnis>/vault.config.json. Wenn es neue/entfernte Dateien auflistet, präsentiere sie; nach Bestätigung durch den SL, node "$TOOL" manifest apply --config <Verzeichnis>/vault.config.json --publish <Pfad>... --exclude "<Pfad>=<Grund>"... --prune. Lasse gespielte Sitzungsindizes aus --publish heraus: publish-played (oben) registriert sie.
  4. node "$TOOL" deploy --verify --config <Verzeichnis>/vault.config.json – gib seine letzte Zeile wörtlich weiter. Bei einem Exit-Code ungleich Null, gehe zu Fähigkeit 3. Fehlende Cloudflare-Anmeldeinformationen werden von deploy inline erklärt; um sie direkt zu setzen, führe node "$TOOL" doctor --set-cloudflare-creds aus.

3. Fehlerbehebung

(Fehlermeldungen, "Build abgestürzt", "Porträts werden nicht angezeigt", "Seite fehlt", "Links sind kaputt")

Führe zuerst node "$TOOL" doctor --site --config <Verzeichnis>/vault.config.json aus; bei einer fehlenden Seite, node "$TOOL" explain "<Relativer Vault-Pfad>". Dann verwende references/troubleshooting.md: nenne die Fehlerart, erkläre die Ursache klar, führe Schritt für Schritt durch die Behebung und biete an, sie anzuwenden.

4. Schema-Migrationen

("Ich habe einen neuen Entitätstyp hinzugefügt", "campaign-organizer wurde aktualisiert", "neuer Ordner im Vault", "Seiten fehlen nach einem Update")

  1. Lokalisiere das Website-Verzeichnis und lese seine vault.config.json.
  2. Vergleiche folderMap mit den Ordnern des Vaults; schlage Ergänzungen von folderMap / excludeDirs vor.
  3. Wende nach Bestätigung an, dann führe npm run build zur Bestätigung aus.
  4. Sage kurz, wie der neue Typ dargestellt wird (eigene Vorlage oder Smart-Wiki-Fallback – references/schema-reference.md).

5. Multi-Site-Verwaltung

("Ich habe zwei Kampagnen", "alle meine Websites aktualisieren")

Verfolge jeden Website-Repo-Pfad und seinen Vault-Pfad im Gespräch, biete an, Routine-Updates für alle durchzuführen, und bestätige jede Website vor dem Pushen.

6. Inhaltsfilterung

("nur Spieler-Inhalte veröffentlichen", "SL-Notizen verstecken", "was werden Spieler sehen", "ohne Spoiler veröffentlichen")

Lies references/content-filtering.md § Inhalts-Sichtbarkeitsmodell und § Manifest-Format. Im mode: player veröffentlicht eine Datei nur als geprüfter Eintrag unter ## Publishing – das Prüfen unter ## Excluded oder ## Needs Decision veröffentlicht sie nicht; mode: full ignoriert das Manifest.

  1. Lese _meta/vault-config.md. Ohne publish:-Abschnitt, folge zuerst content-filtering.md § Einrichtungsfragefluss (Thema, Bild, 404) und schreibe die anfängliche Konfiguration. Bestätige, dass mode player ist – wenn es full ist, stoppe und bitte den SL, es zu ändern, bevor das Manifest erstellt wird.
  2. Kategorisiere jede Vault-Datei gemäß dem Sichtbarkeitsmodell und schreibe _meta/publish-manifest.md.
  3. Fasse zusammen, führe dann den SL durch mehrdeutige Einträge und zeichne jede Entscheidung im Manifest auf (geprüft unter ## Publishing, oder verschoben nach ## Excluded mit einem Grund).

Spätere Veröffentlichungen nehmen neue und entfernte Dateien durch Fähigkeit 2s Manifest-Diff auf.

7. Änderungsanforderungsschleife (am Tisch)

("starte deine Prüfschleife", "nimm die Änderungsanfragen auf", "öffne das Postfach", "überwache auf Blattänderungen")

Folge references/change-request-loop.md – eine unbeaufsichtigte, selbstgesteuerte Schleife, die saubere Spieler-Blattbearbeitungen (GURPS 4e und CoC 7e) anwendet und Randfälle markiert.

8. Live-Statusleiste einrichten (Tier 2a) / 9. Postfach einrichten am Tisch (Tier 2b)

("Statusleiste aktivieren", "Spielern erlauben, HP/FP live zu aktualisieren" / "Postfach einrichten", "Spielern erlauben, Änderungen einzureichen")

Nur Cloudflare Pages. Führe vom Website-Verzeichnis aus node "$TOOL" setup-status-bar oder node "$TOOL" setup-inbox (--config <Pfad> wenn nicht ./vault.config.json) aus. Beide sind vorab geprüft, idempotent und verwalten KV selbst – siehe references/cloudflare-pages.md § Der schnelle Weg. setup-inbox ist nur Infrastruktur; die Sitzung am Tisch ist Fähigkeit 7.

Referenzen

  • references/configuration.md – alle Einstellungen. _meta/vault-config.md (Filterung, Design) gewinnt über vault.config.json (Pfade, URLs, Anzeige), wenn beide etwas festlegen.
  • references/schema-reference.md – welche Felder jeder Entitätstyp rendert.
  • references/cloudflare-pages.md – Cloudflare-Token, Anmeldeinformationen (doctor --set-cloudflare-creds), erstes Deployment, benutzerdefinierte Domains.
  • references/github-pages.md – manuelle GitHub Pages-Aktivierung. Beide Hosts können parallel aus demselben docs/ laufen.

Begleitfähigkeiten

campaign-organizer erstellt die Vault-Struktur, die dieser Skill liest – fehlende Seiten oder Schema-Unterschiede sind meist darauf zurückzuführen. Für neue Inhalte schicke den SL zu ttrpg-expert, dann baue neu. Ein campaign-qa-Durchlauf vor der Veröffentlichung hält defekte Links von der Live-Website fern.

Urheberrecht

Veröffentlichte Websites sind öffentlich. Erinnere den SL vor dem Veröffentlichen daran, dass lizenzierte TTRPG-Inhalte im Vault innerhalb ihrer Lizenz bleiben müssen (siehe ATTRIBUTION.md im gm-apprentice-Repo). Setze niemals lizenzierten Regeltext in generierte Seiten; wenn eine Vault-Notiz wörtlichen Regeltext enthält, markiere sie für den SL zum Umschreiben.

Verwandte Skills