> For the complete documentation index, see [llms.txt](https://docs.zipchat.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zipchat.ai/developers-and-integrations/publish-a-skill-on-the-zipchat-skill-gallery.md).

# Publish a Skill on the Zipchat Skill Gallery

For developers and partners: build a Zipchat custom skill template, test and debug it, then publish it to the skill gallery so merchants install it in two clicks.

This page is for third-party developers and integration partners who want to publish a **skill template** to the Zipchat skill gallery, the way you would publish an app on an app store. Once published, every Zipchat merchant can install your integration in two clicks, with their own credentials.

## What is a custom skill?

{% embed url="<https://www.youtube.com/watch?v=G4NDj6BedF4>" %}

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 multi-step flow across several systems.

No code is hosted on Zipchat. A skill is 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 the 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 adds its instructions to the AI agent's instructions.
2. When a customer's request matches the skill, the agent runs the command or commands your instructions specify in a secure sandbox, typically `curl`, optionally piped through `jq` to reshape JSON, across several steps when the flow needs them. Each command's output comes back to the agent, which 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, such as `{ORDER_ID}` or `{EMAIL}`, are filled in by the agent. Your instructions tell it how to obtain each one.

The sandbox toolbox is small: `curl` for every HTTP call, `jq` to parse and reshape JSON, `ripgrep`/`fd` to search fetched text, and `unzip`. If an 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. Your instructions only need what is 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, for example `WOO_...` or `ZENDESK_...`, never a bare `API_KEY`.

## The publishing process

### Step 1: Create a free Zipchat account

1. Create an account on [zipchat.ai](https://www.zipchat.ai).
2. Contact <support@zipchat.ai> (or your partnership manager) and ask for a **free developer account**, so you can build and test without a subscription.

### Step 2: Build your custom skill on your dev shop

The fastest way to write a skill is with our [Claude Code](https://claude.com/claude-code) skill. It knows 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 works out the endpoints, auth and call sequence, drafts the instructions and defines the variables.
3. In your Zipchat dashboard, go to **Rules & skills**, click **Add** and add your own skill. 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](https://github.com/zipchat-ai/zipchat-custom-tool-skill) 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 to our Support AI.
* **RAW debug info:** the prompts the agent received, every command it ran and every API response it got back. Click **Copy debug info** and paste it into Claude Code: the zipchat-custom-tool skill knows how to read it and pinpoints the fix.

| Symptom in the transcript                                  | Likely fix                                           |
| ---------------------------------------------------------- | ---------------------------------------------------- |
| Your skill's block is missing from the instructions        | 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 or input resolution rules         |
| API error in the output (401, 404, 422)                    | Wrong credential value, path or parameters           |

Still stuck? Contact <support@zipchat.ai> and include the debug transcript.

### Step 4: Publish to the gallery

When it works, tell your partnership manager (or <support@zipchat.ai>) 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 or 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 handle updates with you the same way.

## FAQ

### Do I need to host any code?

No. A skill is instructions plus variables; the agent calls your public API from Zipchat's sandbox.

### Is publishing free?

Yes. Ask <support@zipchat.ai> for a free developer account to build and test.

### What can't a skill do?

Anything without an HTTP call behind it. If your system has no API for an action, a skill cannot perform it.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.zipchat.ai/developers-and-integrations/publish-a-skill-on-the-zipchat-skill-gallery.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
