Building on Zid with AI coding tools: docs, MCP server and Agent Skill

Three ways to give your agent Zid context

AI coding agents write Zid code faster when they read Zid's documentation instead of guessing from general knowledge. Zid offers three ways to give them that context:

• Docs as Markdown: docs.zid.sa serves its pages as .md files, listed in an llms.txt index.
• The docs MCP server, zid-open-apis-mcp, which lets an MCP-capable IDE fetch documentation during a task.
• The Zid AI Agent Skill, an open-source set of instructions that teaches the agent Zid's OAuth, multi-tenant and error-handling patterns.

Docs your agent can read directly

https://docs.zid.sa/llms.txt is a plain-text index of the docs in two parts, Docs and API Docs, with each entry labelled by its place in the docs menu. Every entry links to the Markdown version of the page, and many API entries include a one-line description of the endpoint.

The .md version of an endpoint page includes its OpenAPI definition: method, path, required headers, the OAuth scope, and example responses. That's exactly what an agent needs, without the HTML around it.

# The index of every docs page, each linked as .md
curl -sL https://docs.zid.sa/llms.txt

# One endpoint page as Markdown (here: the Account API "Me" endpoint)
curl -sL https://docs.zid.sa/me-33664055e0.md

In practice, paste the .md URL of the endpoint into your prompt and ask the agent to follow it. That's the same approach Zid uses in its own theme migration prompts, which list the docs URLs the agent should work from.

The docs MCP server

The Our custom MCP server page documents the setup. Prerequisites: Node.js 18 or higher (latest LTS recommended), and an IDE that supports MCP. The page names Cursor and VS Code with the Cline extension, plus others. Add the server to your IDE's MCP servers JSON config:

{
  "mcpServers": {
    "zid-open-apis-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "zid-open-apis-mcp"
      ]
    }
  }
}

To verify, ask the AI in Agent mode: Based on the open apis doc, explain how merchant onboarding works. The connection works if the answer draws on the API documentation. The page doesn't give client-specific steps for other tools, so in any other MCP client, add the same npx -y zid-open-apis-mcp command through that client's MCP settings.

The Zid AI Agent Skill

Zid announced the skill on the partner changelog on September 8, 2026, as open source and available through Zid Docs and GitHub. It's Markdown only, with no runtime, SDK or package to install. SKILL.md is the entry point, and it's backed by reference files the agent loads only when needed: oauth-flow.md, multi-tenant-architecture.md, error-handling.md, endpoint-index.md and troubleshooting-tools.md.

To install it in Claude Code, clone it into the project or global skills directory, then restart or reload Claude Code:

# For the current project (run from the project root)
git clone https://github.com/zidsa/zid-agent-skill.git .claude/skills/zid-api-integration

# Or globally
git clone https://github.com/zidsa/zid-agent-skill.git ~/.claude/skills/zid-api-integration

• Claude: the docs point to a packaged .skill file on the Zid Agent Skill GitHub repository. At the time of writing the repository has no releases yet, and its README says you can zip the folder yourself. Then add it through your workspace's custom-skills workflow.
• opencode and other agents: clone or download the repository as a zid-api-integration folder, then place it in the directory the agent scans for skills.

The docs say the skill and the MCP server can be used together. The skill guides how the agent designs and writes the integration, and the MCP server helps it retrieve documentation during the task.

Keep the live docs as the source of truth

The skill's own rule: the Zid developer docs are the source of truth, and when they disagree with the skill, the docs win. Before the agent writes or ships an API call, have it check against the live endpoint page:

• HTTP method and URL.
• Required OAuth scopes.
• Authentication headers: Merchant API requests generally need both Authorization and X-Manager-Token, and they aren't interchangeable.
• Path and query parameters, and the request body schema.
• Response schema, supported values, rate-limit behavior and error responses.

If the agent produces an endpoint you can't find in the docs, don't use it. Ask the agent to locate the endpoint in the live docs first. If the skill doesn't load, check that the folder contains SKILL.md, that the directory structure wasn't flattened or renamed, and that you restarted the agent, or simply tell it: Use the Zid API integration skill for this task.

For theme developers

The Moving to Vitrin Using LLMs guide uses the same idea for themes. It gives two ready prompts: one converts a Twig theme to Jinja using a list of Vitrin docs URLs, and one updates settings to their new store.settings.* paths.

Zid recommends Claude Code for this migration, since most of its testing was done with it. The guide is also clear that results vary between LLMs and with context size, so re-prompt when the agent misses an instruction, then apply manual fixes and test visually, functionally and for performance.