getshareout/shareout-skill

ShareOut Skill

ShareOut turns files into shareable web artifacts with persistent data, real-time collaboration, file storage, integrations, and automation. It supports HTML apps plus CSV, Markdown, JSON, and TXT viewers.

This is the canonical skill. Load it first for every ShareOut task.

Version Check — Mandatory First Step

Before doing anything else, confirm you have the latest skill. This file's frontmatter version is the version you currently hold (now 2.21.0).

1. GET https://shareout.site/v1/skill/version → { "version": "...", "updated_at": "..." }.
2. If the returned version is newer than this file's frontmatter version, you are stale: download GET https://shareout.site/v1/skill (a zip of the full skill folder), extract it, discard your old copy, and continue from the extracted files.
3. If they match, proceed.

Do not skip this check. Acting on a stale skill produces wrong endpoints and behavior.

Plan Model

ShareOut has two plans:

Plan	Use this skill behavior
Personal	Use this base skill only. Build, publish, update, automate, and manage the user's own artifacts.
Teams	Use this base skill first, then load the Teams overlay for workspace administration or Teams-only capabilities.

Teams is additive. Never use the Teams overlay instead of this base skill.

Agent Loading Protocol

1. Start with this file.
2. If the user mentions a team, workspace, members, internal workspace sharing, subdomain, workspace house style, workspace schedules, or admin controls, ask whether they are on the Teams plan if it is not already clear.
3. If the user is not on Teams, stay in Personal mode and do not load or apply Teams-only instructions.
4. If the user is on Teams, load team/SKILL.md. If a workspace slug/id and token are available, fetch GET /v1/skill?workspace={slugOrId} — the zip includes an extra workspace-context.md with house rules.
5. Use INDEX.md to load detailed files on demand.

First Questions

Before recommending an implementation, identify:

1. What are they building? Dashboard, form, report, tool, doc, data grid, presentation, or automation.
2. Who uses it? Just the owner, invited people, a Teams workspace, or the public.
3. What data does it need? None, simple state, structured records, files, live external data, or realtime collaboration.
4. What should happen after publish? Share link, collect data, send notifications, schedule delivery, alert on metrics, receive & act on inbound email, or let viewers chat with AI.

Mode Router

User intent	Load first	Then if needed
Publish HTML/CSV/Markdown/JSON/TXT	api/artifact-types.md	api/artifacts.md, core/source-editor.md, auth.md
Build an HTML app/page/dashboard/form	core/html-spec/overview.md	modules/ui/overview.md, patterns/overview.md
Make it look good / good design taste / avoid a generic AI look	modules/ui/taste.md	modules/ui/overview.md
Save simple state	sdk/json.md	core/html-spec/manifest.md
Store records/submissions	sdk/table.md	patterns/forms.md, patterns/tables.md
Editable spreadsheet grid	sdk/grid.md	sdk/table.md, integrations/google-sheets.md
Upload files/images	sdk/blobs.md	patterns/uploads.md
Use live external data	sdk/live-data.md	sdk/connections.md, integrations/overview.md
Build realtime collaboration	sdk/realtime.md	modules/_shared/permissions.md
Add comments	sdk/comments.md	modules/_shared/permissions.md
Add in-artifact AI chat	agents/overview.md	agents/context.md
Chat with pages from Telegram	agents/telegram.md	api/jobs.md
Chat with pages from Slack (DM bot)	agents/slack.md	integrations/slack.md, agents/telegram.md
Run Python in browser	sdk/python.md	sdk/overview.md
Send email or templates	sdk/email.md	api/templates.md
Receive email / forward mail to an artifact / trigger on inbound mail	integrations/inbound-email.md	api/jobs.md
Scheduled warehouse/json snapshot refresh (deterministic)	api/jobs.md	agents/crew.md, sdk/connections.md
Artifact crew (query → summarize → deliver)	agents/crew.md	api/jobs.md, integrations/slack.md
Request access to a private page	modules/_shared/permissions.md	core/access-policy.md
Schedule delivery or webhooks	api/jobs.md	api/destinations.md
Alert when a metric crosses a threshold	api/metric-alerts.md	patterns/dashboards.md
Teams workspace/admin/subdomain/context	team/SKILL.md	team/INDEX.md
Teams publish governance (member approval for public)	team/publish-governance.md	team/SKILL.md, modules/_shared/publishing.md
Teams skill marketplace (reusable playbooks)	team/skill-marketplace.md	team/workspace-context.md, agents/overview.md

Data Choice

Pick the smallest store that fits:

Simple state: theme, filters, last-opened -> sdk.json
Structured records: tasks, submissions, orders -> sdk.table()
Realtime editing: docs, boards, multiplayer UI -> sdk.realtime()
Files: images, PDFs, attachments -> sdk.blobs
Live external systems: REST, BigQuery, Mixpanel, warehouses -> sdk.connection / live-data

Do not confuse data choice with account plan. sdk.json, sdk.table(), and sdk.realtime() are data stores, not billing plans.

SDK Loading

<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>

Rules:

• Load https://shareout.site/sdk/shareout.js before calling ShareOut.create().
• Prefer await ShareOut.create() over new ShareOut() so the embedded Bearer token is ready.
• Published HTML runs in a sandboxed iframe on {hex}.shareoutcdn.site; use SDK methods, not raw fetch to /v1/data/.... See sdk/live-data.md.
• Link https://shareout.site/sdk/shareout.css and use .so- classes before writing custom CSS. See modules/ui/overview.md.
• Do not use cdn.jsdelivr.net ShareOut SDK URLs.

HTML Artifact Rules

HTML artifacts work whether or not they carry ShareOut's structural markers — publishing is never blocked. But the more the artifact declares, the more the visual editor can do with it (outline navigation, inline editing, add/remove rows). Aim for editor-ready by default; skip it only for a deliberate throwaway static page.

Editor-readiness checklist (what the editor looks for):

• A script type="shareout/manifest" tag in the document head, with valid JSON.
• Every sdk.json key and sdk.table() name used is declared in the manifest sources.
• Dynamic content carries data-shareout-binding, and each binding references a declared source.
• Pages use data-shareout-page (drives the editor outline); repeating content uses data-shareout-template.
• Interactive targets resolve: data-shareout-link / data-shareout-action point at real pages/sections/modals/tabs; modals have an open trigger; forms have a submit.
• Declare default sample data on sources — json, tables, and connections (live connectors like BigQuery/Snowflake/Sheets: sources.connections.<name>.default is an array of sample rows). The visual editor previews data with no live fetch or query (it resolves all SDK reads — including sdk.connection(...).query() — from these defaults, or empty), so an artifact that gates its UI behind await sdk.table(...).exec() / a connector query still renders and stays editable. A source with no default previews empty.

Every publish of an HTML artifact returns an advisory editor_readiness profile (see api/artifacts.md) that grades these and names what each gap disables. Share a one-line summary with the user, but treat it as guidance, not a gate — they can publish exactly what they want.

Full spec: core/html-spec/overview.md.

Design Taste

Editor-readiness is about structure, not looks. Looks are a separate, deliberate decision — and the default for AI-built pages is "templated and generic." Before building anything visual, read modules/ui/taste.md: it distills how to ship artifacts that look professionally designed instead of auto-generated. The short version:

• Use the design system (.so- classes + tokens) — it ships brand fonts, a warm light palette, and harmonized spacing/shadow, so you inherit good taste for free. See modules/ui/overview.md.
• Taste is restraint: one accent color, one font system, one primary action per screen, generous whitespace, motion only when motivated.
• Avoid the AI-slop tells: purple/neon glows, three-equal-cards rows, eyebrow spam, fake-perfect numbers, marketing clichés, missing empty/error states. Full ban list and a pre-ship checklist live in modules/ui/taste.md.

Artifact Types

ShareOut auto-detects type from MIME type or file extension:

Type	Extensions	Use
html	.html, .htm	Full SDK apps, dashboards, tools, presentations
csv	.csv	Sortable/filterable data grids
markdown	.md, .markdown	Docs with rendered HTML and TOC
json	.json	Collapsible tree viewer
txt	.txt	Plain text/log viewer

Details: api/artifact-types.md.

First Run — Get a Token

Every authenticated action needs a token. If ~/.shareout/credentials does not exist yet, the user has no account — bootstrap one before publishing or any other authenticated call:

1. POST https://shareout.site/v1/auth/create-account (the only unauthenticated endpoint, no body) → { "token": "so_…", "user_id": "usr_…" }.
2. Save the token to ~/.shareout/credentials as { "token": "so_…" } (chmod 600).
3. All later requests use Authorization: Bearer so_….

Account creation is rate-limited per IP (code: RATE_LIMIT_EXCEEDED, 429). The account is anonymous and headless — no email required to publish.

Then ask the user if they want to connect Gmail/Google. The bootstrap account has no email, so it can only be used via the stored token. Linking an email lets them sign in to the web UI at https://shareout.site (home dashboard, visual editor, self-serve API tokens). Offer both paths:

• Google: open GET https://shareout.site/v1/auth/link-google (Bearer token) in a browser to link their Google account.
• Email code: POST /v1/auth/link-email/start { "email" } → POST /v1/auth/link-email/verify { "email", "code" } (6-digit code, 10-min expiry).

If they decline, the token-only flow keeps working. See auth.md for the full onboarding and linking reference.

Publishing

ShareOut is protected by Cloudflare. Python requests can trigger a 1010 block. Build payloads however you want, then pipe to curl:

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 @-

Full API: api/overview.md.

Teams Boundary

Personal artifacts can still be private, shared with collaborators, public, or unlisted. Only load Teams docs for Teams plan workspace capabilities:

• Workspace members and roles.
• Internal workspace visibility (visibility: "workspace").
• Workspace membership policy by email/domain.
• Workspace subdomains.
• Workspace context files for house style.
• Workspace-level schedules, automations, feature flags, and admin views.

Important term distinction:

Term	Meaning
access_policy	Row-level artifact data filtering: each viewer sees only allowed rows. See core/access-policy.md.
Workspace membership policy	Teams email/domain membership rules: who can join a workspace. See team/SKILL.md.
Collaborator role	Artifact-level owner, editor, viewer.
Workspace role	Teams workspace owner, admin, member.

Version Checking

Run the mandatory version check before each task. Three equivalent ways to compare your held version against live:

GET  https://shareout.site/v1/skill/version   # → { "version", "updated_at" } (preferred)
HEAD https://shareout.site/v1/skill           # → X-Skill-Version, X-Skill-Updated-At headers
GET  https://shareout.site/v1/skill           # with If-None-Match: "<version>" → 304 if unchanged

If live is newer, download GET /v1/skill (zip bundle), extract it, and continue from those files.

Non-Negotiable Rules

• Prefer documented ShareOut endpoints over inventing request shapes.
• Confirm the user has a ShareOut token before authenticated actions; if ~/.shareout/credentials is missing, run First Run — Get a Token first.
• Verify artifact identifiers before updates/deletes.
• Use ShareOut.create() plus SDK APIs for live artifact data.
• Use shareout.css and .so- classes for default artifact UI.
• Apply design taste on anything visual — restraint over decoration, and avoid the AI-slop tells.
• Load Teams docs only when the user is on Teams or the task is explicitly Teams workspace administration.