Slidesfly

Slidesfly Skill

Publish a local HTML deck to Slidesfly and return a shareable link on slidesfly.xyz.

Trigger conditions

Do trigger when all of the following are true:

1. A local .html or .htm file already exists (or was just generated in this session).
2. The user wants to publish, share, or manage an existing Slidesfly deck.

Examples that should trigger:

• "Publish this deck and give me a link."
• "把这个 HTML 演示稿发到网上。"
• "Share the slides with my team."
• "List my Slidesfly decks."
• "Delete the deck we published yesterday."

Examples that should not trigger:

• "Make me a 10-slide deck about RAG." (generate HTML first, then publish)
• "Improve the typography on slide 3." (edit HTML first)
• "What is Slidesfly?" (answer directly, no CLI)
• "Convert this PDF to HTML." (different task)
• "Deploy this Next.js app." (not a single HTML deck file)

Prerequisites

1. HTML file on disk — single self-contained .html is best for v0.
2. Node.js 22+ — required for the bundled runner, PATH CLI, and MCP.
3. Prefer MCP when available — if the host has Slidesfly MCP configured (stdio @slidesfly/mcp or hosted https://slidesfly.com/api/mcp), use tools publish / list / versions / restore / claim / status (and set_api_key on stdio only) instead of shelling out to the CLI. Stdio shares ~/.slidesfly/config.json with the CLI; hosted uses Bearer sk_….
4. Use the bundled runner by default — resolve the directory containing this SKILL.md as SKILL_DIR, then require $SKILL_DIR/scripts/slidesfly.mjs. It is the complete official CLI built from the same source as the PATH command, not a second API implementation. It performs no remote code download and shares ~/.slidesfly/config.json with the PATH CLI.

test -f "$SKILL_DIR/scripts/slidesfly.mjs"
node "$SKILL_DIR/scripts/slidesfly.mjs" --version   # expect 0.1.5+
node "$SKILL_DIR/scripts/slidesfly.mjs" publish ./deck.html --title "My Deck" --json

For a legacy Cursor .mdc installation, the installer stores the runner in the sibling slidesfly/scripts/slidesfly.mjs directory. Resolve that exact path before executing it. If the bundled runner is absent, a reviewed PATH slidesfly >= 0.1.5 is a compatible fallback; do not download and execute a replacement during the task.

5. Install this skill locally (optional, for persistent agent guidance and the bundled runner):

slidesfly install --target auto
# or: slidesfly install --target cursor --scope project
# guidance-only legacy mode, without the bundled runner:
slidesfly install --target auto --skill-only

All slidesfly ... examples below describe the shared command contract. Agents should invoke them as node "$SKILL_DIR/scripts/slidesfly.mjs" ... unless a compatible PATH CLI was deliberately selected.

MCP (preferred when configured)

Stdio (local): @slidesfly/mcp — shares ~/.slidesfly/config.json with the CLI.

{
  "mcpServers": {
    "slidesfly": {
      "command": "npx",
      "args": ["-y", "@slidesfly/mcp"]
    }
  }
}

Hosted (remote Streamable HTTP): https://slidesfly.com/api/mcp with Authorization: Bearer sk_… (no set_api_key; publish sends content_base64 + filename).

Rules: never paste claim_token into chat (stdio MCP never returns it on success). Auth via set_api_key / prior slidesfly login (stdio) or Bearer key (hosted) — no browser PKCE inside MCP. Prefer MCP versions / restore for owned deck rollback; the bundled runner or compatible PATH CLI remains the fallback for Pro controls (expire / password / allowlist) and skill install.

HTTP reference (no MCP): OpenAPI. Publish create/update accept optional Idempotency-Key (CLI/MCP send a UUID automatically).

Reader navigation (optional)

Decks can include this script so swipe and keyboard navigation from the Slidesfly reader shell (slidesfly.xyz/d/...) reaches in-iframe slide decks via postMessage:

<script src="https://slidesfly.xyz/reader-host.js"></script>

The shell sends { source: 'slidesfly', action: 'next' | 'prev' | ... }; the host script dispatches keyboard events and Reveal.js API calls when present.

Deck runtime constraints (sandbox)

Published decks render inside a sandboxed iframe with an opaque origin (allow-scripts allow-popups allow-popups-to-escape-sandbox allow-forms, no allow-same-origin). When generating deck HTML, respect these constraints:

• JS, forms, and popups work. Inline <script> runs normally; keyboard/slide navigation is fine.
• localStorage, sessionStorage, and IndexedDB THROW (SecurityError) on access; cookies are inert — never rely on browser storage. If a library touches storage, wrap access in try/catch or feature-detect; do not persist viewer state.
• CLI preflight runs before upload. Runner/CLI 0.1.5 safely inlines eligible local classic .js files into the upload copy while leaving the source deck unchanged. It blocks remote, missing, oversized, module/async/defer/integrity-sensitive, <base href>-ambiguous, or otherwise unsafe script references before any network request. The server still rejects disallowed script sources and blocklisted domains with MALICIOUS_CONTENT. Behavior keywords (eval(, document.cookie, javascript:, onerror=, onload=) are accepted but logged as risk signals for async review; published decks are also re-scanned asynchronously (Cloudflare Security DNS by default; optional Google Safe Browsing) and taken down if flagged.
• Self-contained is safest: inline all CSS/JS/images (data URIs) in one file. Multi-file decks may reference their own relative assets only.

Anonymous-first workflow (default)

No login is required for the first publish. The bundled runner posts to the anonymous API, stores claim_token locally, and returns a URL on the content domain:

slidesfly publish ./deck.html --title "Q4 Plan" --json

Example response:

{
  "ok": true,
  "data": {
    "deck_id": "v0c8Kf3sQ1MnEa7bYj9wHt",
    "url": "https://slidesfly.xyz/d/v0c8Kf3sQ1MnEa7bYj9wHt",
    "title": "Q4 Plan",
    "visibility": "unlisted",
    "size_bytes": 184320,
    "anonymous": true
  },
  "warnings": [{
    "code": "ANONYMOUS_LOCAL_ONLY",
    "message": "This deck is managed only on this machine via ~/.slidesfly/config.json. Run slidesfly login to claim it to your account."
  }]
}

Agent obligations after publish:

1. Show the full https://slidesfly.xyz/d/... URL to the user.
2. Explain visibility (unlisted = link-only access by default).
3. Repeat the ANONYMOUS_LOCAL_ONLY warning when present.
4. Never paste claim_token or raw ~/.slidesfly/config.json into chat.

Authenticated publish (when logged in)

After slidesfly login, the shared runner/CLI stores an API key in ~/.slidesfly/config.json. Subsequent publish calls use the owned-deck API (no local claim_token, no anon_decks entry):

slidesfly login --json
slidesfly publish ./deck.html --title "Q4 Plan" --visibility public --json
slidesfly publish ./deck.html --id v0c8Kf3sQ1MnEa7bYj9wHt --json   # update owned deck
slidesfly delete v0c8Kf3sQ1MnEa7bYj9wHt --json
slidesfly visibility v0c8Kf3sQ1MnEa7bYj9wHt public --json

Owned publish supports --visibility public|unlisted|private (plan limits apply). Use --id <deck_id> to upload a new version of an existing owned deck; add --title to rename it in the same call. delete, visibility, versions, and restore work on owned decks by deck ID when logged in, even if the deck is not in local anon_decks. Restore copies a prior version into a new live version (single-file and multi-file).

Link controls (Pro plan, owned decks)

slidesfly expire v0c8Kf3sQ1MnEa7bYj9wHt 7d --json        # link stops working in 7 days
slidesfly expire v0c8Kf3sQ1MnEa7bYj9wHt off --json       # remove expiry
slidesfly password v0c8Kf3sQ1MnEa7bYj9wHt "s3cret" --json # viewers must enter password
slidesfly password v0c8Kf3sQ1MnEa7bYj9wHt off --json      # remove password
slidesfly allowlist v0c8Kf3sQ1MnEa7bYj9wHt a@x.com b@y.com --json # email-gated access
slidesfly allowlist v0c8Kf3sQ1MnEa7bYj9wHt off --json     # remove allowlist

expire accepts durations (7d, 24h, 30m), ISO-8601 timestamps, or off. These commands require login and a Pro plan; on Free they fail with FORBIDDEN ("requires the Pro plan") — suggest upgrading at slidesfly.com/pricing instead of retrying. Never echo the password back into chat.

Command reference

Global flag: --api-key <key> on any command. The bundled runner and PATH CLI intentionally expose the same command names, arguments, JSON envelope, config path, auth flows, and error codes.

Always pass --json when parsing stdout programmatically. Non-TTY stdout auto-emits JSON.

Common workflows

Publish a new deck

slidesfly publish ./deck.html --title "RAG 101" --json

Update or rename a published deck

When logged in, update an owned deck in place (same URL, new content); add --title to rename it:

slidesfly publish ./deck.html --id v0c8Kf3sQ1MnEa7bYj9wHt --json
slidesfly publish ./deck.html --id v0c8Kf3sQ1MnEa7bYj9wHt --title "Q4 Plan (final)" --json

When logged out, republish creates a new anonymous deck. After login + claim, use authenticated publish/update instead.

Restore a previous version

Owned decks keep version history (including multi-file zips after --id updates). List versions, then restore (creates a new live version; the share URL stays the same):

slidesfly versions v0c8Kf3sQ1MnEa7bYj9wHt --json
slidesfly restore v0c8Kf3sQ1MnEa7bYj9wHt 2 --json

Quarantined decks and expiry-purged content cannot be restored this way — re-publish with --id instead.

Protect or expire a shared link (Pro)

slidesfly password v0c8Kf3sQ1MnEa7bYj9wHt "launch-day" --json
slidesfly expire v0c8Kf3sQ1MnEa7bYj9wHt 7d --json

Manage local anonymous decks

slidesfly list --json
slidesfly delete v0c8Kf3sQ1MnEa7bYj9wHt --json

The shared runner/CLI reads the local claim_token and sends it in X-Slidesfly-Claim-Token. Never put this credential in a query string or hand-build an anonymous management URL.

Upgrade to account (claim)

When the user needs public visibility, analytics, or cross-machine management:

slidesfly login --json          # opens browser; auto-claims local anon decks
slidesfly login --no-claim --json   # login only, skip auto-claim
slidesfly claim --json            # claim manually if needed

Fallback when browser/loopback login is blocked (SSH, remote devbox, no local browser):

slidesfly login --code --json
# CLI prints /cli/code URL; user opens it in any browser, copies 8-char code, pastes in terminal
slidesfly claim --json

Fallback when no browser access at all:

slidesfly login --api-key "$KEY" --json
slidesfly claim --json

Error handling matrix

Parse error.code from JSON output. Follow retry rules strictly.

Network errors: wait 5s, retry once, then stop.

Global rules:

• Never auto-rewrite HTML after INVALID_HTML or MALICIOUS_CONTENT.
• Do not retry other 4xx errors (except one 429 retry).
• Retry 5xx at most once.

Output contract

Success:

{ "ok": true, "data": { ... }, "warnings": [ ... ] }

Failure:

{ "ok": false, "error": { "code": "...", "message": "...", "hint": "..." } }

Human TTY mode prints minimal text (usually the URL). Agents should always use --json.

Sandbox notes

If the bundled runner is unavailable:

1. Check for a preinstalled slidesfly binary on PATH (~/.slidesfly/bin after website install).
2. Continue only if slidesfly --version is 0.1.5 or newer.
3. Otherwise stop and direct the user to the official technical quickstart. Do not download or execute a remote installer, ad-hoc cli.mjs, or unverified npm package from this Skill.
4. Do not hand-build a multipart publish request: use the bundled runner, a compatible PATH CLI, or configured MCP so claim_token stays off chat transcripts.

If loopback login is blocked, use slidesfly login --code (headless device flow) or slidesfly login --api-key with a key from the dashboard.

Example dialogues

Success: User asks to publish an existing deck.html → run publish with --json → return https://slidesfly.xyz/d/... + anonymous warning.

Quota exceeded: Surface QUOTA_EXCEEDED, suggest slidesfly login, do not spam retries.

Malicious content: Surface MALICIOUS_CONTENT verbatim, do not modify HTML and retry.

Cross-machine: slidesfly list empty → explain local-only anon decks; offer slidesfly login + claim on original machine.

Go public: When logged out, visibility public on anon deck → ANONYMOUS_LIMITED → suggest slidesfly login + claim, or publish with --visibility public after login.

Privacy & security

• Do not expose ~/.slidesfly/config.json, API keys, or claim_token.
• Anonymous update/delete requests carry claim_token only in the X-Slidesfly-Claim-Token header; credential-bearing routes reject every query parameter. Account claim sends tokens only in its JSON body.
• Prefer the bundled runner. Install a PATH CLI only through the official technical quickstart or a reviewed binary—never ad-hoc /tmp + cli.mjs.
• Anonymous publish --json must not print claim_token (runner/CLI ≥ 0.1.3 keeps it in local config only).
• Default visibility is unlisted unless the user explicitly asks for public.
• Share URLs live on slidesfly.xyz; SaaS dashboard lives on slidesfly.com.