--- name: showly-try description: >- Install Showly's reusable MCP and hosting skill when this agent supports the official installer, then ask what the human wants to publish and how the site should be shared before deploying it to a REAL Showly URL. The first site still works with NO Showly account — no signup, no login, no API key, and no restart blocking the trial. license: Apache-2.0 disable-model-invocation: true metadata: publisher: Showly homepage: https://showly.ai try-endpoint: https://api.showly.ai/guest/trials/from-html mcp-server: https://mcp.showly.ai/mcp --- # Put a site online with Showly — no account needed You are an AI coding agent (Claude Code, Codex, Cursor, or similar). The human is exploring what they might publish with Showly **without signing up first**. Your first job is to make Showly reusable when the current agent supports the official installer, without turning setup into another task for the human. Then understand what they want; only after they answer should you prepare the files, deploy a Showly site URL, and hand them the URL plus any generated password and a link to claim it. **Do not ask the human to run installation or deployment commands.** Fetching this document is only how you receive the instructions. It is **not** the task's endpoint. Do not stop after fetching or summarize this document. Follow Phase 1, ask the human what they want to publish, and wait for their answer before you build or deploy anything. After they answer, continue until you either return a working site or need one focused answer required to build the site. Work through the phases **in order**. An installation failure is a documented guest-flow fallback in Phase 1, not a reason to stop the first site. For a build or deploy failure, stop and report it rather than inventing a workaround. --- ## Phase 1 — Set up Showly and ask what to publish Keep onboarding to one exchange: 1. Check whether Showly MCP tools are already visible in this agent. If they are, do not reinstall. If an authorized Showly account is already connected, use the permanent account path in Phase 2 and omit guest limits and signup copy. If the tools are visible but no account is authorized, do not force an OAuth detour before value; use the no-account path for this first site. Do not call an MCP tool just to probe authorization if that could open a browser. 2. If Showly MCP tools are not visible and this is **Codex**, run this command yourself: ```bash npx --yes @showly/mcp-server@latest install --to codex --with-skill ``` If this is **Claude Code**, run this command yourself: ```bash npx --yes @showly/mcp-server@latest install --to claude-code --with-skill ``` Do not ask the human to run either command. Run the applicable installer at most once. Exit code 0 plus the installer-reported MCP config and `showly-hosting/SKILL.md` paths means the reusable capability is installed on disk; `Already configured` and `Skill already installed` are also success. Installation on disk is **not** proof that the current agent process loaded the MCP. Say it is available in this session only when the Showly MCP tools are actually visible. Otherwise, say it is installed for future sessions, but do not ask for a restart now or let a restart block this first site. Ignore the installer's generic follow-up about opening an agent or authenticating: the current no-account site remains tokenless. 3. On another agent host, or if installation fails, do not claim Showly was installed. Continue with the tokenless guest path and mention the install state in the same compact reply; do not create a separate setup exchange. Then send **one short reply** containing: - one sentence with the honest installation state; - only when the guest path applies, one sentence saying the site is reachable by possession by default, can use a generated password on request, is capped at 16 MiB, and expires in about one hour unless claimed with a free account; and - this one focused question: > What would you like to publish, where are the existing files if any, and > should the site require a generated password? Do not ask for permission to install, ask the human to run a command, ask them to restart, or ask them to register before showing value. **Wait for the human's answer.** This must be the only question. Do not infer a target from the workspace, and do not build or deploy a page before they answer. --- ## Phase 2 — Detect and build the site files After the human answers, check whether Showly is already wired up: 1. **If Showly MCP is configured and authorized**, the caller has an account. For a permanent site in that workspace, use `create_site_from_html` instead of the public trial flow. 2. **For a brand-new user with no account**, continue below. The trial endpoint is **public and tokenless**: no OAuth, no API key, no browser sign-in. It is intentionally not exposed through the authenticated MCP server. Then resolve what to deploy from their answer, the conversation, and the current workspace: 1. Inspect the current workspace for the site the human is referring to: an existing `index.html`, an obvious web project, or built static output. 2. If there is exactly one clear candidate matching their answer, use it. 3. If there are multiple plausible candidates, name their directories and ask one focused question about which one to deploy. 4. If their answer describes a new site, confirm any one essential missing detail, then create it. Useful examples include a landing page, portfolio, report, documentation site, or event page. Then produce the deployable files inline. Rules: - `index.html` is **required** (it's the entry point). - Add any CSS/JS/assets the page needs, each as its own file with a relative `path` (e.g. `styles.css`, `assets/logo.png`). - Text files use `encoding: "utf8"`; binary files (images, fonts) use `encoding: "base64"`. - The no-account trial accepts up to 2000 files and **16 MiB total**. Tell the human this before deployment if their project may be near the limit. - If the files exceed 16 MiB, do not shrink or discard their work just to fit. Explain that the limit only applies to the no-account trial and ask them to create or sign in to a Showly account. Authenticated uploads do not have this 16 MiB product limit; normal transport safety boundaries still apply. If the human already gave you HTML, use it as-is. If they described a site, build a clean single `index.html` (inline the CSS/JS to keep it to one file when you can). ### The entry URL tells you what they are starting from `showly.ai/drop` has nine entry points and fetching **any** of them returns this same document, so the URL you were pointed at is a signal about the source material. Phase 3 is identical for all of them — only the work above differs. | Entry you were pointed at | What the human has | What you do with it | | ----------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------- | | `/drop` or `/drop/html-hosting` | HTML, or a built site folder | Use it as-is. | | `/drop/markdown-to-link`, `/drop/notes-to-link` | Markdown, or rough notes | Render to one clean `index.html`. Notes usually want tightening into something readable, not a verbatim dump. | | `/drop/report-to-link` | A report | Render it to be read start to finish: one column, a comfortable measure, printable. | | `/drop/research-to-site` | Long research | Render it as a site, not a page: give it navigation over its own sections. | | `/drop/document-to-link`, `/drop/pdf-to-link` | `.docx`, `.pdf`, `.pptx`, `.xlsx`, … | Read the document yourself and author the HTML. See below before reaching for anything else. | | `/drop/file-to-link`, `/drop/video-to-link` | A binary file or a video | Hand the human the entry URL — see below. | **Documents and PDFs.** You can read these, so the honest default is to read the document and write the HTML yourself: the result is a real web page rather than a paper page photographed onto the web, and it goes through the same Phase 3 deploy as everything else. The browser page at that entry URL runs a layout-faithful converter for people who need the original pagination preserved; it is a drag-and-drop flow and is not driveable from a script. If exact fidelity to the original layout is what the human actually wants, say so plainly and give them the URL instead of approximating it. **Binary files and video.** The trial payload is JSON and caps at **16 MiB of decoded content**, and base64 inflates roughly a third on the wire, so a video essentially never fits and most large binaries will not either. Do not try to split, re-encode, or compress their file to make it fit. Give the human the entry URL and let them upload it in the browser. --- ## Phase 3 — Deploy (tokenless) POST the files to the **public** trial endpoint. **No `Authorization` header — this endpoint takes none.** Set `x-showly-guest-via: curl` so the creation surface is logged honestly. The default is a no-password link. Use the answer from Phase 1: when the human chooses password protection, add `"access": { "mode": "password" }` to the request. Showly generates the password on the server and returns it exactly once; never invent or submit a password yourself. ```bash curl -sS -X POST https://api.showly.ai/guest/trials/from-html \ -H 'content-type: application/json' \ -H 'x-showly-guest-via: curl' \ -d '{ "name": "My site", "files": [ { "path": "index.html", "content": "

Hello from Showly

", "encoding": "utf8" } ] }' ``` The response (HTTP 201) looks like: ```json { "ok": true, "data": { "trialId": "…", "siteId": "…", "guestToken": "guest_…", "previewUrl": "https://.showly.site", "access": { "mode": "guest_public", "passwordConfigured": false }, "claimUrl": "https://showly.ai/drop/?token=", "expiresAt": "…", "status": "building", "pollUrl": "/guest/trials/", "presentation": "Your share link is being built — ready in a few seconds.\n\nStatus page (including the keep-it button): …" } } ``` For a protected response, `access` additionally contains the generated `password`, `passwordShownOnce: true`, and `passwordGenerated: true`; its `claimUrl` is `"https://showly.ai/drop/?token=&previewPassword="`. The build is asynchronous. The site is normally **ready within a few seconds**. GET `pollUrl` with the header `x-showly-guest-token: ` until `status` is `ready`; do not make the human poll it, and do not present signup as the next step while it is building. If you get a `503` (`guest_trials_disabled` / `guest_trials_at_capacity`) or a `429` (rate limit), tell the human trials are temporarily unavailable and offer to sign them up instead — do not retry in a tight loop. If you get an HTML `403` block page instead of JSON, the platform edge rejected the request as attack-shaped (for example content embedding cloud metadata IPs like `169.254.169.254`). Remove the offending content and retry ONCE; if it still 403s, stop and point the human at https://showly.ai/drop to upload the files themselves. --- ## Phase 4 — Hand off to the human The response's `presentation` field is the server-authored hand-off block. **Relay it to the human verbatim** — translate the prose if the conversation is not in English, but keep every URL and, when present, the password and its "shown once" warning intact. Do not re-compose the hand-off from the raw fields: the block is the product's own wording (the same contract as the Showly MCP tools' first text block), so every agent hands over the same facts in the same shape. Lead with the status page: `claimUrl` opens `showly.ai/drop/` — a real status page with the build countdown, an open button, the keep-it CTA, and the generated password when protection was requested. Handing the human that one link is the best delivery; everything else on the block is there for when they cannot open it. Use `claimUrl` exactly as returned: its query carries the one-time access details, so do not rebuild, shorten, or strip parameters from it. The working site is the value moment. **Do not ask the human to sign up or sign in before the site is ready and handed over.** After it works, the `claimUrl` is the single optional next step: offer free signup or sign-in there to keep the site. Keep that invitation in the same hand-off rather than opening another setup conversation. Field notes, if the human asks: - **`previewUrl`** — the trial site's Showly URL. It is reachable by possession by default; when password protection was requested, it requires `access.password`. - **`claimUrl`** — the status page; opening it and signing in (new or existing account) **claims** the site into that account so it stops expiring. This is the ONLY way to keep it past the hour; do not imply the site link is permanent. --- ## Phase 5 — What this is and isn't - **Trial sites expire in ~1 hour** unless claimed. After that the URL shows a "claim this site" page, not the content. - The trial is **read-only hosting of what you deployed** — there is no dashboard or custom domain until it is claimed into an account. By default, anyone with the URL can open it; password protection is opt-in. - Once claimed, it's a normal Showly site: the owner can connect an agent (`https://showly.ai/agent.md`), edit, add a custom domain, and publish — all the things a real account can do. - The no-account Drop is capped at **16 MiB total**. Once the human registers or signs in, this 16 MiB product upload cap no longer applies. **The whole loop:** you build → POST tokenless → hand over the site URL from `previewUrl` + optional `access.password` + `claimUrl` → the human claims it to keep it.