ShareOut-Skill

ShareOut Skill

ShareOut verwandelt Dateien in freigebbare Web-Artefakte mit persistenten Daten, Echtzeit-Zusammenarbeit, Dateispeicher, Integrationen und Automatisierung. Es unterstützt HTML-Apps sowie CSV-, Markdown-, JSON- und TXT-Viewer.

Dies ist das kanonische Skill. Lade es für jede ShareOut-Aufgabe zuerst.

Versionsprüfung – Obligatorischer erster Schritt

Führe vor irgendetwas anderem die Versionsprüfung durch, ob du die neueste Version des Skills hast. Die version im Frontmatter dieser Datei ist die Version, die du derzeit besitzt (aktuell 2.21.0).

1. GET https://shareout.site/v1/skill/version → { "version": "...", "updated_at": "..." }.
2. Wenn die zurückgegebene version neuer ist als das version im Frontmatter dieser Datei, bist du veraltet: lade GET https://shareout.site/v1/skill herunter (ein ZIP des gesamten Skill-Ordners), entpacke es, verwerfe deine alte Kopie und fahre mit den extrahierten Dateien fort.
3. Wenn sie übereinstimmen, fahre fort.

Diese Prüfung nicht überspringen. Die Arbeit mit einem veralteten Skill führt zu falschen Endpunkten und Verhalten.

Tarifmodell

ShareOut hat zwei Tarife:

Tarif	Dieses Skill-Verhalten verwenden
Personal	Nur dieses Basis-Skill verwenden. Eigene Artefakte des Benutzers erstellen, veröffentlichen, aktualisieren, automatisieren und verwalten.
Teams	Zuerst dieses Basis-Skill verwenden, dann das Teams-Overlay für die Arbeitsbereichsverwaltung oder Teams-spezifische Funktionen laden.

Teams ist additiv. Verwende niemals das Teams-Overlay anstelle dieses Basis-Skills.

Agenten-Ladeprotokoll

1. Mit dieser Datei beginnen.
2. Wenn der Benutzer ein Team, einen Arbeitsbereich, Mitglieder, internes Arbeitsbereich-Sharing, eine Subdomain, einen Arbeitsbereich-Hausstil, Arbeitsbereich-Zeitpläne oder Admin-Steuerung erwähnt, frage, ob er sich im Teams-Tarif befindet, falls dies nicht bereits klar ist.
3. Wenn der Benutzer nicht im Teams-Tarif ist, im Personal-Modus bleiben und keine Teams-spezifischen Anweisungen laden oder anwenden.
4. Wenn der Benutzer im Teams-Tarif ist, team/SKILL.md laden. Wenn ein Arbeitsbereich-Slug/ID und Token verfügbar sind, GET /v1/skill?workspace={slugOrId} abrufen – das ZIP enthält eine zusätzliche workspace-context.md mit Hausregeln.
5. Verwende INDEX.md, um bei Bedarf detaillierte Dateien zu laden.

Erste Fragen

Bevor du eine Implementierung empfiehlst, identifiziere:

1. Was wird gebaut? Dashboard, Formular, Bericht, Werkzeug, Dokument, Datentabelle, Präsentation oder Automatisierung.
2. Wer verwendet es? Nur der Besitzer, eingeladene Personen, ein Teams-Arbeitsbereich oder die Öffentlichkeit.
3. Welche Daten werden benötigt? Keine, einfacher Zustand, strukturierte Datensätze, Dateien, Live-Externdaten oder Echtzeit-Zusammenarbeit.
4. Was soll nach der Veröffentlichung passieren? Link teilen, Daten sammeln, Benachrichtigungen senden, Lieferung planen, bei Metriken alarmieren, eingehende E-Mails empfangen und darauf reagieren oder Zuschauer mit KI chatten lassen.

Modus-Router

Benutzerabsicht	Zuerst laden	Dann falls nötig
HTML/CSV/Markdown/JSON/TXT veröffentlichen	api/artifact-types.md	api/artifacts.md, core/source-editor.md, auth.md
Eine HTML-App/Seite/Dashboard/Formular erstellen	core/html-spec/overview.md	modules/ui/overview.md, patterns/overview.md
Gut aussehen / guten Designgeschmack / generischen KI-Look vermeiden	modules/ui/taste.md	modules/ui/overview.md
Einfachen Zustand speichern	sdk/json.md	core/html-spec/manifest.md
Datensätze/Übermittlungen speichern	sdk/table.md	patterns/forms.md, patterns/tables.md
Bearbeitbare Tabellenkalkulation	sdk/grid.md	sdk/table.md, integrations/google-sheets.md
Dateien/Bilder hochladen	sdk/blobs.md	patterns/uploads.md
Live-Externdaten verwenden	sdk/live-data.md	sdk/connections.md, integrations/overview.md
Echtzeit-Zusammenarbeit erstellen	sdk/realtime.md	modules/_shared/permissions.md
Kommentare hinzufügen	sdk/comments.md	modules/_shared/permissions.md
KI-Chat im Artefakt hinzufügen	agents/overview.md	agents/context.md
Mit Seiten über Telegram chatten	agents/telegram.md	api/jobs.md
Mit Seiten über Slack chatten (DM-Bot)	agents/slack.md	integrations/slack.md, agents/telegram.md
Python im Browser ausführen	sdk/python.md	sdk/overview.md
E-Mails oder Vorlagen senden	sdk/email.md	api/templates.md
E-Mails empfangen / E-Mail an ein Artefakt weiterleiten / bei eingehender Mail auslösen	integrations/inbound-email.md	api/jobs.md
Geplantes Warehouse/JSON-Snapshot-Refresh (deterministisch)	api/jobs.md	agents/crew.md, sdk/connections.md
Artefakt-Crew (Abfrage → zusammenfassen → liefern)	agents/crew.md	api/jobs.md, integrations/slack.md
Zugriff auf eine private Seite anfordern	modules/_shared/permissions.md	core/access-policy.md
Lieferung oder Webhooks planen	api/jobs.md	api/destinations.md
Alarmieren, wenn eine Metrik einen Schwellwert überschreitet	api/metric-alerts.md	patterns/dashboards.md
Teams-Arbeitsbereich/Admin/Subdomain/Kontext	team/SKILL.md	team/INDEX.md
Teams-Veröffentlichungs-Governance (Mitgliedergenehmigung für öffentlich)	team/publish-governance.md	team/SKILL.md, modules/_shared/publishing.md
Teams-Skill-Marktplatz (wiederverwendbare Playbooks)	team/skill-marketplace.md	team/workspace-context.md, agents/overview.md

Datenauswahl

Wähle den kleinsten passenden Speicher:

Einfacher Zustand: Theme, Filter, zuletzt geöffnet -> sdk.json
Strukturierte Datensätze: Aufgaben, Übermittlungen, Bestellungen -> sdk.table()
Echtzeit-Bearbeitung: Dokumente, Boards, Multiplayer-UI -> sdk.realtime()
Dateien: Bilder, PDFs, Anhänge -> sdk.blobs
Live-Externe Systeme: REST, BigQuery, Mixpanel, Warehouses -> sdk.connection / live-data

Verwechsle die Datenauswahl nicht mit dem Abrechnungstarif. sdk.json, sdk.table() und sdk.realtime() sind Datenspeicher, keine Abrechnungspläne.

SDK-Laden

<head>
  <link rel="stylesheet" href="https://shareout.site/sdk/shareout.css">
  <script src="https://shareout.site/sdk/shareout-ui.js" defer></script>
  <script src="https://shareout.site/sdk/shareout.js"></script>
</head>
<script>
(async () => {
  const sdk = await ShareOut.create();
})();
</script>

Regeln:

• Lade https://shareout.site/sdk/shareout.js bevor du ShareOut.create() aufrufst.
• Bevorzuge await ShareOut.create() gegenüber new ShareOut(), damit das eingebettete Bearer-Token bereit ist.
• Veröffentlichtes HTML wird in einem sandboxed Iframe auf {hex}.shareoutcdn.site ausgeführt; verwende SDK-Methoden, nicht rohes fetch zu /v1/data/.... Siehe sdk/live-data.md.
• Verlinke https://shareout.site/sdk/shareout.css und verwende .so- Klassen, bevor du eigenes CSS schreibst. Siehe modules/ui/overview.md.
• Verwende keine cdn.jsdelivr.net ShareOut SDK-URLs.

HTML-Artefakt-Regeln

HTML-Artefakte funktionieren, unabhängig davon, ob sie ShareOuts strukturelle Marker tragen – die Veröffentlichung wird nie blockiert. Aber je mehr das Artefakt deklariert, desto mehr kann der visuelle Editor damit machen (Gliederungsnavigation, Inline-Bearbeitung, Zeilen hinzufügen/entfernen). Ziel ist es, standardmäßig Editor-bereit zu sein; überspringe dies nur für eine bewusst wegwerfbare statische Seite.

Checkliste für Editor-Bereitschaft (worauf der Editor achtet):

• Ein script type="shareout/manifest" Tag im head des Dokuments, mit gültigem JSON.
• Jeder sdk.json-Schlüssel und jeder sdk.table()-Name, der verwendet wird, ist im Manifest sources deklariert.
• Dynamischer Inhalt trägt data-shareout-binding, und jede Bindung verweist auf eine deklarierte Quelle.
• Seiten verwenden data-shareout-page (treibt die Editor-Gliederung); sich wiederholender Inhalt verwendet data-shareout-template.
• Interaktive Ziele werden aufgelöst: data-shareout-link / data-shareout-action zeigen auf echte Seiten/Abschnitte/Modals/Tabs; Modals haben einen Öffnungsauslöser; Formulare haben einen Absende-Button.
• Deklariere default-Beispieldaten auf sources – json, tables, und connections (Live-Connectors wie BigQuery/Snowflake/Sheets: sources.connections.<name>.default ist ein Array von Beispielzeilen). Der visuelle Editor zeigt Daten ohne Live-Abruf oder -Abfrage an (er löst alle SDK-Lesevorgänge – einschließlich sdk.connection(...).query() – aus diesen Standardwerten oder leer auf), sodass ein Artefakt, das seine UI hinter await sdk.table(...).exec() / einer Connector-Abfrage platziert, trotzdem rendert und bearbeitbar bleibt. Eine Quelle ohne default zeigt leer an.

Jede Veröffentlichung eines HTML-Artefakts gibt ein beratendes editor_readiness-Profil zurück (siehe api/artifacts.md), das diese bewertet und benennt, welche Lücke was deaktiviert. Teile dem Benutzer eine einzeilige Zusammenfassung mit, behandle es jedoch als Leitfaden, nicht als Hindernis – sie können genau das veröffentlichen, was sie wollen.

Vollständige Spezifikation: core/html-spec/overview.md.

Designgeschmack

Editor-Bereitschaft betrifft die Struktur, nicht das Aussehen. Das Aussehen ist eine separate, bewusste Entscheidung – und der Standard für KI-erstellte Seiten ist „vorlagenhaft und generisch". Bevor du etwas Visuelles baust, lies modules/ui/taste.md: es fasst zusammen, wie man Artefakte liefert, die professionell gestaltet aussehen, statt automatisch generiert. Die Kurzfassung:

• Verwende das Designsystem (.so- Klassen + Tokens) – es liefert Markenschriftarten, eine warme helle Palette und harmonisierte Abstände/Schatten, sodass du guten Geschmack gratis erbst. Siehe modules/ui/overview.md.
• Geschmack ist Zurückhaltung: eine Akzentfarbe, ein Schriftsystem, eine primäre Aktion pro Bildschirm, großzügiger Weißraum, Bewegung nur, wenn motiviert.
• Vermeide die KI-Schlamm-Anzeichen: lila/neon Glühen, Drei-gleiche-Karten-Reihen, Eyebrow-Spam, falsch-perfekte Zahlen, Marketing-Floskeln, fehlende Leer/Fehlerzustände. Die vollständige Verbotsliste und eine Vor-Veröffentlichungs-Checkliste befinden sich in modules/ui/taste.md.

Artefakt-Typen

ShareOut erkennt den Typ automatisch anhand des MIME-Typs oder der Dateierweiterung:

Typ	Erweiterungen	Verwendung
html	.html, .htm	Vollständige SDK-Apps, Dashboards, Werkzeuge, Präsentationen
csv	.csv	Sortierbare/filterbare Datentabellen
markdown	.md, .markdown	Dokumente mit gerendertem HTML und Inhaltsverzeichnis
json	.json	Zusammenklappbarer Baum-Viewer
txt	.txt	Klartext-/Log-Viewer

Details: api/artifact-types.md.

Erster Start – Token holen

Jede authentifizierte Aktion benötigt ein Token. Wenn ~/.shareout/credentials noch nicht existiert, hat der Benutzer kein Konto – erstelle eines vor der Veröffentlichung oder jedem anderen authentifizierten Aufruf:

1. POST https://shareout.site/v1/auth/create-account (der einzige nicht authentifizierte Endpunkt, kein Body) → { "token": "so_…", "user_id": "usr_…" }.
2. Speichere das token in ~/.shareout/credentials als { "token": "so_…" } (chmod 600).
3. Alle späteren Anfragen verwenden Authorization: Bearer so_….

Die Kontenerstellung ist pro IP ratenbegrenzt (code: RATE_LIMIT_EXCEEDED, 429). Das Konto ist anonym und kopflos – keine E-Mail erforderlich zum Veröffentlichen.

Frage den Benutzer dann, ob er Gmail/Google verbinden möchte. Das Bootstrap-Konto hat keine E-Mail, daher kann es nur über das gespeicherte Token verwendet werden. Das Verknüpfen einer E-Mail ermöglicht es ihnen, sich im Web-UI unter https://shareout.site anzumelden (Start-Dashboard, visueller Editor, Self-Service-API-Tokens). Biete beide Wege an:

• Google: Öffne GET https://shareout.site/v1/auth/link-google (Bearer-Token) in einem Browser, um ihr Google-Konto zu verknüpfen.
• E-Mail-Code: POST /v1/auth/link-email/start { "email" } → POST /v1/auth/link-email/verify { "email", "code" } (6-stelliger Code, 10 Min. Gültigkeit).

Wenn sie ablehnen, funktioniert der Nur-Token-Fluss weiter. Siehe auth.md für die vollständige Onboarding- und Verknüpfungsreferenz.

Veröffentlichen

ShareOut wird durch Cloudflare geschützt. Python requests können einen 1010-Block auslösen. Erstelle Payloads wie du möchtest, leite sie dann an curl weiter:

TOKEN=$(python3 -c "import json,os; print(json.load(open(os.path.expanduser('~/.shareout/credentials')))['token'])")
python3 build_payload.py | curl -sS -X POST 'https://shareout.site/v1/publish' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  --data-binary @-

Vollständige API: api/overview.md.

Teams-Grenze

Persönliche Artefakte können trotzdem privat, mit Mitarbeitern geteilt, öffentlich oder nicht gelistet sein. Lade Teams-Dokumente nur für Teams-Plan-Arbeitsbereichsfunktionen:

• Arbeitsbereichsmitglieder und -Rollen.
• Interne Arbeitsbereichssichtbarkeit (visibility: "workspace").
• Arbeitsbereichsmitgliedschaftsrichtlinie nach E-Mail/Domain.
• Arbeitsbereichs-Subdomains.
• Arbeitsbereichskontextdateien für Hausstil.
• Arbeitsbereichsweite Zeitpläne, Automatisierungen, Feature-Flags und Admin-Ansichten.

Wichtige Begriffsklärung:

Begriff	Bedeutung
access_policy	Row-Level-Artefakt-Datenfilter: jeder Zuschauer sieht nur erlaubte Zeilen. Siehe core/access-policy.md.
Arbeitsbereichsmitgliedschaftsrichtlinie	Teams-E-Mail/Domain-Mitgliedschaftsregeln: wer einem Arbeitsbereich beitreten kann. Siehe team/SKILL.md.
Mitarbeiterrolle	Artefakt-Ebene owner, editor, viewer.
Arbeitsbereichsrolle	Teams-Arbeitsbereich owner, admin, member.

Versionsprüfung

Führe die obligatorische Versionsprüfung vor jeder Aufgabe durch. Drei gleichwertige Möglichkeiten, deine gehaltene version mit der Live-Version zu vergleichen:

GET https://shareout.site/v1/skill/version
Authorization: Bearer so_...

Vergleiche die zurückgegebene version mit der version im Frontmatter dieser Datei (2.21.0).