Publish a Skill on the Zipchat Skill Gallery

Build & Publish Custom Skill Templates

This page is for third-party developers and integration partners who want to publish a skill template to the Zipchat skill gallery — think of it as publishing an app on our app store. By the end, every Zipchat merchant will be able to install your integration in two clicks, with their own credentials.

What is a custom skill?

A custom skill lets a merchant's Zipchat AI agent perform a real action against an external HTTP API — look up an order, create a discount, fetch tracking, escalate a ticket, or run a richer multi-step flow across several systems.

There is no code hosted on Zipchat. A skill is just four inputs:

Input	What it is
Name	Short, human-readable (e.g. "Woo — Track orders"). Shown to the agent and the merchant.
Instructions	The core deliverable: a structured prompt that tells the agent when to act, which API calls to make, and how to present the result.
Variables	Secrets and per-merchant config (API keys, store URLs). Encrypted at rest, never shown to customers.
Setup note	Merchant-facing install instructions for gallery templates (e.g. "How to get your REST API key").

A skill template is a pre-packaged skill in our gallery: your icon, name, description, instructions, and setup note. Merchants install it and only fill in their own variable values.

How a skill executes

1. When a merchant installs your skill, Zipchat injects its instructions into the AI agent's system prompt, wrapped as:

   #### <skill name>
   <custom_tool_instructions>
   …your instructions…
   </custom_tool_instructions>

2. When a customer's request matches the skill, the agent runs the shell command(s) your instructions specify in a secure sandbox — typically curl, optionally piped through jq to reshape JSON, across multiple steps when the flow needs them. Each command's output comes back to the agent, which either runs the next step or replies to the customer in the brand's voice.

3. Variables are injected as environment variables. A variable named WOO_CONSUMER_KEY is referenced in your curl as $WOO_CONSUMER_KEY. The agent never sees the value.

4. Runtime values use {PLACEHOLDER} syntax. Values that come from the conversation — {ORDER_ID}, {EMAIL} — are filled in by the agent. Your instructions tell it how to obtain each one.

The sandbox toolbox is small and deliberate: curl (every HTTP call — the only thing that produces an effect), jq (parse and reshape JSON), ripgrep/fd (search fetched text), unzip. If a desired action has no HTTP call behind it, a skill can't do it.

Zipchat handles the guardrails for you. Command hygiene, fix-and-retry on malformed requests, no blind retries on genuine failures, honest failure messages in the brand's voice, and secret safety are all enforced platform-side — your instructions should only contain what's specific to your integration.

Variable naming rules

• Uppercase letters, digits, underscores; cannot start with a digit (^[A-Z_][A-Z0-9_]*$).

• Must be unique across all of a merchant's active skills — always prefix with your product: WOO_…, ZENDESK_…, never a bare API_KEY.

The publishing process

Step 1 — Create a free Zipchat account

1. Create an account on www.zipchat.ai.

2. Contact [e-mail] (or your partnership manager) and ask for a free developer account — we'll set you up so you can build and test without a subscription.

Step 2 — Build your custom skill on your dev shop

The fastest way to author a skill is with our Claude Code skill — it embeds everything about how skills execute, interviews you, and hands back every input ready to paste:

1. Add the skill to Claude Code:

   /plugin marketplace add zipchat-ai/zipchat-custom-tool-skill
   /plugin install zipchat-custom-tool@zipchat-tools

2. Point it at your API documentation and tell it what you want the agent to achieve. It will work out the endpoints, auth, and call sequence, draft the instructions, and define the variables.

3. In your Zipchat dashboard, go to AI training → Prompt and Skills → Add skill → Add your own, and paste in the name, instructions, and variables.

4. Open Test chat (top right) and talk to your agent like a customer would. Confirm the skill triggers when it should, the API calls succeed, and the replies read well.

You can also write everything by hand — the skill repository documents the full prompt structure with complete examples.

Step 3 — Debug with the Debug button

If the skill misbehaves, every AI reply (in Test chat and in Conversations) has a Debug action with two tabs:

• AI helper — describe what's wrong and send it straight to our Support AI.

• RAW debug info — the exact prompts the agent received, every command it ran, and every API response it got back. Click Copy debug info and paste the transcript into Claude Code — the zipchat-custom-tool skill knows how to read it and will pinpoint the fix.

Typical symptoms map cleanly:

Symptom in the transcript	Likely fix
Your skill's block missing from the system prompt	Skill inactive or not enabled for that channel
No tool call where you expected one	Sharpen the when-to-use wording in your instructions
Malformed command (empty $VAR, unfilled {PLACEHOLDER})	Fix variable names / input resolution rules
API error in the output (401, 404, 422)	Wrong credential value, path, or params

Still stuck? Contact [e-mail] — include the debug transcript.

Step 4 — Publish to the gallery

Happy with how it works? Tell your partnership manager (or [e-mail]) that you want it published. Hand over:

• The final name, description, and instructions

• The variable list, each with a note on where merchants get the value

• The setup note (merchant-facing install steps)

• Your logo/icon

We review the template, package it, and publish it to the skill gallery — from then on, any Zipchat merchant can install your integration with their own credentials. We'll handle updates with you the same way.