Skills

Showly Skills

Showly Skills as the user-visible interface to agent capabilities.

Showly publishes an official Claude Code Skill that wraps the MCP server with task-oriented prompts. The Skill is the easiest way to use Showly from an agent: you install it, the agent automatically knows when to invoke Showly tools, and the prompts already encode the publish-loop conventions.

Why Skills

A raw MCP server gives an agent tools. A Skill teaches the agent _when_ and _why_ to use them. The Showly Skill includes:

  • A description that triggers on intent ("deploy", "publish", "preview", "showly").
  • Internal scripts that chain create_change_plan → apply_site_patch → create_preview → run_checks → request_publish so the agent doesn't have to.
  • Verification steps that read the preview URL and report back.
  • Refusal patterns for actions the agent shouldn't take on its own (production publishes always go to a human via the approval gate).

Installing the official Skill

In Claude Code (or Codex):

npx @showly/mcp-server install --to claude-code   # or --to codex

This installs from the @showly/mcp-server package and registers the Showly MCP server for you. There is no token to set: the first time you invoke a Showly tool, your agent opens a browser tab to sign in and approve access, and Showly issues a scoped token to the agent directly (standard MCP OAuth). See Installing the Skill for the full handshake and the no-browser fallback.

What the Skill does that raw MCP doesn't

  • Auto-discovers the active site from the current working directory by matching the repository's GitHub remote against the sites in your Showly workspace.
  • Renders previews inline with screenshots from mcp__playwright_browser_take_screenshot if Playwright MCP is also installed.
  • Refuses to request a publish without a recent passing preview; production publishes always route through request_publish and a human approval.

Auto-discovery

When you run an agent inside a checked-out repo, the Skill reads the repo's origin remote and looks for a site in your workspace whose repositoryUrl matches. The matched site's siteId becomes the target for get_site_context, apply_site_patch, create_preview, and the rest of the loop, so you rarely have to name a site by hand.

If no site matches the remote, the Skill asks you to pick or create one rather than guessing. If several sites share the remote, it asks you to disambiguate.

Publish guardrails

Production is never published directly from an agent. Before it will request a publish, the Skill checks that:

  • There is a recent ready preview deployment for the site.
  • run_checks has passed against that preview.

When those hold, the Skill calls request_publish, which returns a webApprovalUrl deep link. A human with admin rights approves the request in the web UI; the agent only polls the approval state. There is no agent path that promotes to production without that human step.

Next