> 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/publish-a-skill-on-the-zipchat-skill-gallery.md). # 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? {% embed url="" %} 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: ``` #### …your 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](https://www.zipchat.ai). 2. Contact (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](https://claude.com/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](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 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 — include the debug transcript. #### Step 4 — Publish to the gallery Happy with how it works? Tell your partnership manager (or ) 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. --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.zipchat.ai/publish-a-skill-on-the-zipchat-skill-gallery.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.