Authoring custom skills

The official Showly Skill covers the canonical publish loop. Teams often have _additional_ workflows specific to their stack — branding QA, content compliance checks, automated localization. You can ship those as custom Skills that any Showly-connected agent will pick up.

When to write a Skill vs. just a script

Write a Skill when:

• The workflow is _intent-triggered_ (the user says "deploy" or "translate" and the agent should know).
• The workflow has refusal/safety patterns worth encoding (don't ship without checks, don't publish during freeze).
• It's reusable across team members or projects.

Just write a script when:

• The workflow runs in CI, not in an agent conversation.
• It's a one-off you'll throw away.

Anatomy of a Showly-aware Skill

A Skill is a manifest plus prompts. The minimum:

name: my-publish-with-localize
description: |
  Use when the user wants to publish a Showly site that has
  user-facing strings. This skill localizes new/changed strings,
  runs `run_checks`, then proposes a publish.
trigger:
  intents:
    - "publish"
    - "ship"
    - "release"
mcp:
  required:
    - showly
    - localizer
prompt: |
  1. Call mcp__showly__get_site_context to read the change.
  2. Identify new/changed strings in any *.tsx files.
  3. Call mcp__localizer__translate for each new string.
  4. Apply translations via mcp__showly__apply_site_patch.
  5. Call mcp__showly__create_preview.
  6. Call mcp__showly__run_checks (include `i18n-coverage`).
  7. If checks pass, call mcp__showly__request_publish.
  8. Refuse to call request_publish if any check failed.

Field reference

The prompt steps are not executed by Showly — they are instructions handed to the agent. The agent reads them in order and calls the named MCP tools itself (e.g. mcp__showly__get_site_context, then mcp__showly__apply_site_patch), applying any refusal checks you encode. Use the exact tool identifiers from the MCP tool reference so the agent calls real tools. The production path to a live site is always request_publish, which returns a webApprovalUrl for a human to complete the publish — the Skill cannot publish to production on its own.

For the full manifest schema (the typed manifest.json the official Skill ships), see Install the Skill.

Refusal patterns

The hardest part of a useful Skill is encoding _what not to do_. Examples from the official Showly Skill:

• No publish without a recent preview: if create_preview hasn't been called in this conversation, refuse request_publish.
• No publish during freeze: if the workspace policy says "merge freeze active", refuse and link the freeze announcement.
• No break-glass publish: MCP has no emergency bypass. If the user says the fix is urgent, still create a preview, run checks, and request approval.

Encode these in your prompt as bullets the agent must check before each tool call.

Distribution

Three options:

• Personal — drop the Skill in ~/.claude/skills/. Only you see it.
• Workspace — commit it to your Showly site repo under .showly/skills/. Anyone with workspace access auto-installs it.
• Public — publish your Skill as its own package and let others install it the same way the official Showly client is installed: npx @showly/mcp-server install --to <claude-code|codex|stdout>. This is the canonical install command — follow the same shape so authors and installers stay on one path.

The install paths above match Install the Skill: the canonical command is npx @showly/mcp-server install (the @showly/mcp-server package, bin showly-mcp). Use the same shape for your custom Skill so authors and installers follow one path.

Versioning

Skills follow semver. Breaking changes (renaming intents, removing tool steps) ship a new major. Run showly-mcp (the bin shipped by @showly/mcp-server) to install and update; re-running npx @showly/mcp-server install picks up the latest version.

Where to read next

• MCP tool reference — what each tool does and how to chain them.
• Skill model — why Skills exist and how they differ from raw tools.