---
name: wix-readme
description: "What the Wix plugin holds and how to work with Wix through it: the flow the Wix MCP README returns, an index of the plugin's skills with what each does, and the Wix MCP tools with what each does. Use when the plugin was just installed or when the user asks what the Wix plugin can do or which skill or tool fits a task."
title: wix-readme
canonical_url: https://skilld.dev/gh/wix/skills/wix-readme
last_updated: 2026-11-12T13:12:59.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install wix/skills/wix-readme`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/wix-readme`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/wix/skills/wix-readme) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/wix-readme`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/wix-readme --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/wix-readme --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# The Wix plugin

The plugin is two things: skills, folders of instructions and shipped code for building on Wix, each with a `SKILL.md` at its root; and the Wix MCP server at `https://mcp.wix.com/mcp`, whose tools read and change the user's Wix sites and account. The skills say how; the tools do.

## How to work with Wix through the plugin

Every Wix task ends in one of two places: a call made now with the user's account, or code the user keeps that makes the same calls (an app, a headless site, a script). The way there is the same.

1. **Start with `WixREADME`**, once per conversation. It returns this flow in full and the account's sites with their installed apps.
2. **Pick the site.** The `siteId` comes from the site context; when several fit, ask. A business solution's API works only on a site with that app installed, and an app's version changes its endpoints, so check the site's apps first.
3. **Find the method.** The first source that gives it: an earlier tool result in the conversation; else the skill that covers the task (the index below says what each is for), whose example is the model when it matches the case; else the docs, `SearchWixRESTDocumentation` or `BrowseWixRESTDocsMenu` for REST, the SDK, CLI, headless and apps searches for code, then `ReadFullDocsArticle` on the method's page.
4. **Get the exact shape.** A request is modeled on an example that matches the case: a skill's recipe or template, or the method's docs page, when it shows the fields the case needs. That is enough. The schema is for what no example shows: a field, an enum, a filter or sort key (a closed list per method). `SearchWixAPISpec` on the method's docs URL returns the request and response schemas, the REST URL and the JavaScript SDK call; `ReadFullDocsMethodSchema` when it is not available.
5. **Make the call, or write the code.** To do it now: `ExecuteWixAPI`, one function holding every step of the task, the reads and the writes they feed. For code the user keeps: write the call from the shape found in step 4, REST or SDK. `wix-headless-templates` is that code already written and verified, one folder per business solution, and `wix-headless-kit` builds a site on it.

Throughout: nothing Wix-specific from memory. Every URL, id, setting location, product fact, request shape and field name comes from a skill, the docs tools, an earlier tool result or the user.

## Creating a site

A new Wix site is written in code and uploaded. `StartDeployWebsite` returns the guide for a site the agent writes or files the user brought; `StartHeadlessBuild` returns the guide for a site that needs Wix business features (a store, bookings, a CMS, members, payments and the rest). Each guide creates the site, uploads it and says what comes next; call one and follow it.

A Wix Studio Two site, which the user keeps designing in Wix Studio, is the exception: to create one, to change an existing Studio Two site's pages, theme or components, or to import another site or project into one, follow `wix-studio-two` instead.

What the guides stand on:

- **One site, created once**, by the provision call (`POST .../headless-business-setup/v1/headless-business/provision`, `origin: 'agent'`), which returns `metaSiteId`, the id every later call takes. A site made earlier is found with `ListWixSites` and uploaded to again; the URL never changes.
- **Static pages are dropped, a Wix Astro build is released.** A drop through `UploadHeadlessWebsiteFiles` sends the whole site the first time and then the files that change, each one complete; a drop over REST sends the complete file set each time. A build (`.wix/build-metadata.json` beside `dist/`) is released to Wix hosting, server-rendered, through `UploadHeadlessWebsiteFiles` only: as an attachment, or in two calls (`prepare: true` with the zip's `size`, then `uploadKey`) from a shell that reaches the internet. The project's source is stored with the release, and a later session continues the site from it.
- **`UploadHeadlessWebsiteFiles`** takes `siteId` and the files, as `attachments` or the `files` text bundle, and returns the live URL and the dashboard. Without the MCP, the same drop is a `curl` multipart call, with or without a login.
- **Business features** come from `wix-headless-kit`'s run on the same site and `appId`: apps installed and content seeded, the Astro project built from `wix-headless-templates`, the build released.

To read more: the recipe, `wix-manage/references/sites/upload-static-site.md` (https://www.wix.com/skills/wix-manage/references/sites/upload-static-site.md): the calls for every route, drop and release, finding and changing a site, limits and failures. Publishing with no Wix login, and changing or claiming that site: `wix-manage/references/sites/publish-without-a-wix-account.md` (https://www.wix.com/skills/wix-manage/references/sites/publish-without-a-wix-account.md). The cold start (https://www.wix.com/skills/headless-cold-start/headless-kit.md): the headless build from a cold environment to the released site.

## Two ways to Wix

### The plugin with the Wix MCP

The preferred way. The plugin's MCP configuration connects the Wix MCP server at `https://mcp.wix.com/mcp`; the client signs the user in on the first call and the tools below are in the tool list, with nothing to install. The flow above runs on them: `WixREADME` for the context, the documentation tools to find a method and its shape, `ExecuteWixAPI` to call it, `StartDeployWebsite` and `StartHeadlessBuild` with `UploadHeadlessWebsiteFiles` to create a site and put it live. The skills are read from the plugin's folder, and `ReadFullDocsArticle` reads them online when they are not there.

Context first:

| Tool | What it does |
|---|---|
| `WixREADME` | The context every other tool assumes. Call it once per conversation before a Wix task; for another site later, call `GetSiteContext` instead. |
| `ListWixSites` | Lists the user's sites, with an optional name filter. Needs no `WixREADME` first. |
| `GetSiteContext` | Deep context for one site, by name or id: its apps, settings and data, as markdown. |

Building and deploying a site:

| Tool | What it does |
|---|---|
| `StartDeployWebsite` | Returns the guide to create a site on Wix and put files on it: HTML, CSS and JS, a static build, a zip, another builder's export. Updates keep the site and URL. Works with or without a Wix login. |
| `StartHeadlessBuild` | Returns the headless guide, for a site that needs Wix business features: a store, bookings, events, a restaurant menu, a blog, pricing plans, donations, forms, members, a CMS, payments. |
| `UploadHeadlessWebsiteFiles` | The upload step of those two guides: puts a static site or a Wix Astro build onto an existing Wix Headless site by its metaSiteId, as files, as attachments, or in two calls with presigned URLs. |
| `GetSuggestedDomains` | Domain name suggestions for a site. |

Calling Wix APIs:

| Tool | What it does |
|---|---|
| `ExecuteWixAPI` | Reads and changes a site's or account's data with one JavaScript function over the Wix REST API: chained calls, pagination, loops, the reads that feed the writes. The preferred way to call Wix APIs. |
| `SearchWixAPISpec` | Inspects the Wix REST API spec and each method's JavaScript SDK call by running JavaScript against the index: the exact request and response shape, enums, the SDK import and signature. |

Documentation:

| Tool | What it does |
|---|---|
| `SearchWixRESTDocumentation` | Searches the Wix REST API docs. The starting point for finding an endpoint. |
| `BrowseWixRESTDocsMenu` | Browses the REST docs as a menu, category by category. |
| `SearchWixSDKDocumentation` | Searches the Wix JavaScript SDK docs. |
| `SearchWixHeadlessDocumentation` | Searches the Wix Headless docs. |
| `SearchWixCLIDocumentation` | Searches the Wix CLI docs: commands, local development, authentication. |
| `SearchWixWDSDocumentation` | Searches the Wix Design System docs. |
| `SearchBuildAppsDocumentation` | Searches the Wix Build Apps docs. |
| `SearchDevelopmentDocumentation` | Broad Wix developer docs: platform concepts and guides, after the specific searches return nothing. |
| `SearchWixHelpCenter` | Searches the Wix Help Center: how site owners do things by hand in the dashboard and editors. |
| `ReadFullDocsArticle` | Reads a page in full by URL: a docs article or method page, a skill's `SKILL.md` or any of its files, a Help Center article. |
| `ReadFullDocsMethodSchema` | The full request and response schema of one method, by its docs URL. |

Media and feedback:

| Tool | What it does |
|---|---|
| `UploadImageToWixSite` | Uploads images, video, audio and documents to a site's Media Manager and returns their URLs and media ids. |
| `PickImagesForWixMedia` | Shows the user a file picker to upload images, video, audio and documents from their device to the Media Manager. |
| `ReportIssueToWix` | Reports one problem with Wix's tools, APIs or docs to the Wix team, when the user asks for it. |

### The Wix CLI

The other way, from a shell. `@wix/cli` is Wix's command-line tool: it signs in to a Wix account, creates and manages Wix projects on disk, a Wix app or a Wix Headless site, builds them and releases them to Wix, and mints tokens for REST calls. Its session lives on the machine. All as `npx @wix/cli@latest <command>`:

| Command | What it does |
|---|---|
| `login` | Signs in with a device code and writes the session to `~/.wix/auth/account.json`. |
| `whoami` | Shows the signed-in account. |
| `create` | Creates a Wix project with its site: for a headless site, the site, its OAuth app and hosting, and the project's `wix.config.json` (`siteId`, `appId`). |
| `env pull` | Writes the project's environment to `.env.local`: the site's client id and the values the build reads. |
| `build` | Builds the project for Wix: for an Astro site, `dist/` and `.wix/build-metadata.json`. |
| `release` | Releases the build to Wix; the site keeps its URL. |
| `token`, `token --site <siteId>` | Mints an admin token, account-scoped or site-scoped, for REST calls from a shell: `Authorization: Bearer <token>` (`wix-docs/references/CALLING.md`). |

`wix-headless-kit` builds a Wix Headless site through the MCP's tools or through the CLI; without the MCP's tools its run is the CLI route, where `install/setup.mjs` runs `create`, and `build` then `release` put the site live.

Without the MCP, each tool is a plain HTTP call to the same backend. `wix-docs` covers these, with the request bodies, as its `curl` lane:

| Tool | Without the MCP |
|---|---|
| `SearchWixRESTDocumentation`, `SearchWixSDKDocumentation`, `SearchWixHeadlessDocumentation`, `SearchWixCLIDocumentation`, `SearchWixWDSDocumentation`, `SearchBuildAppsDocumentation`, `SearchDevelopmentDocumentation` | `POST https://www.wixapis.com/mcp-docs-search/v1/docs/search` (or `/search/markdown`) with `search_term` and the `document_type` of that corpus. |
| `BrowseWixRESTDocsMenu` | `POST https://www.wixapis.com/mcp-docs-search/v1/docs/menu/browse`. |
| `ReadFullDocsArticle` | Append `.md` to any `https://dev.wix.com/docs/...` URL; a skill's file is `https://www.wix.com/skills/<skill>/<path>`. |
| `SearchWixAPISpec`, `ReadFullDocsMethodSchema` | `POST https://mcp.wix.com/api/code-mode/search` with the same JavaScript. |
| `ExecuteWixAPI` | The REST call itself, to `https://www.wixapis.com`, with a token: which identity a method takes and how to mint the token are in `wix-docs/references/CALLING.md`. |
| `StartDeployWebsite`, `StartHeadlessBuild`, `UploadHeadlessWebsiteFiles` | `create`, `build` and `release` from a shell; the `wix-manage` recipe `references/sites/upload-static-site.md` creates a site and drops files over REST. |

## Skills

Each skill is a folder with a `SKILL.md` at its root that says what it does and which of its files to read when. A skill may already be on disk, in the plugin's folder or under `.agents/skills/<skill>/` after `npx skills add wix/skills`, or served by the client's skill tool; read it from there. Otherwise every file is online at `https://www.wix.com/skills/<skill>/<path>`, read with `ReadFullDocsArticle` or `curl`; `https://www.wix.com/skills/<skill>/` with the trailing slash lists the skill's files. Paths below are inside the skill's folder.

### wix-headless-kit

Online: https://www.wix.com/skills/wix-headless-kit/SKILL.md. On disk: the plugin's `skills/wix-headless-kit/`, or `.agents/skills/wix-headless-kit/`.

Builds Wix Headless sites with business features from the ready-made code in `wix-headless-templates`: per business solution, a data layer, hooks, components, Astro pages and a seed script, with a REST layer for plain HTML pages and stacks that can't run the rest. It also publishes HTML files or a static build the user already has, with or without a Wix account, and adds business features to them later. The agent designs the presentation and releases to Wix hosting. Runs from a shell with the Wix CLI, or through the MCP's tools.

**The cold start**, `wix-headless-cold-start/headless-kit.md` (https://www.wix.com/skills/headless-cold-start/headless-kit.md, what `StartHeadlessBuild` returns), carries the whole run through the plugin's tools alone: the site provisioned through `ExecuteWixAPI` with the solution in `seedOptions`, the apps, the content created through `ExecuteWixAPI` from the vertical's `SEED.md`, pages that read the site as a visitor, uploaded with `UploadHeadlessWebsiteFiles`. A machine with the kit on its disk (the plugin's folder, or installed with `CI=1 npx skills@latest add wix/skills --skill wix-headless-kit --skill wix-docs --skill wix-manage --yes`), Node 22.12 or later, `npm` reaching the registry, and a way to get a build to the upload tool (an attachment, or `curl` to its upload URLs) releases the kit's Astro build instead of written pages; that run is wix-headless-kit's `SKILL.md`. A machine with a logged-in Wix CLI and no plugin takes the CLI route, `install/bootstrap.mjs` for the login.

- `SKILL.md`: the steps of a build and the table of business solutions.
- `guides/capabilities.md`: which Wix product owns which feature, and what ships for it.
- `guides/existing-site.md`: a new frontend for a Wix site that already has its content, and continuing a site built in an earlier session.
- `guides/migration.md`: a site moving to code after "Go Headless" in its dashboard.
- `guides/reference-mode.md`: a stack that cannot run the shipped React code.
- `guides/seo.md`: the SEO tags every page carries, on each stack.
- `guides/feedback.md`: sending the user's feedback on building with Wix.
- `install/`: the scripts of a run (`setup.mjs`, `attach.mjs`, `deploy.mjs`, `install.mjs`, `templates.mjs`, `context.mjs`, `bootstrap.mjs`, `check.mjs`) and `pins.json`, the pinned CLI and templates versions.

### wix-headless-templates

Online: https://www.wix.com/skills/wix-headless-templates/SKILL.md. On disk: the plugin's `skills/wix-headless-templates/`, or `.agents/skills/wix-headless-templates/`.

The code wix-headless-kit builds from, one folder per business solution: `storefront`, `bookings`, `rentals`, `blog`, `cms`, `forms`, `members`, `events`, `restaurants`, `donations`, `pricing-plans`, `portfolio`, `faq`, plus `blank` and `shared`. Each folder holds:

- `INSTRUCTIONS.md`: the playbook, with the contracts.
- `app/`: the typed, framework-agnostic data layer over `@wix/sdk`, React hooks and reference components.
- `app-astro/`: the Astro pages with owner-editable SEO.
- `rest/`: the same data layer as plain REST calls, for a site without a bundler.
- `seed/`: the seed script that fills the site from a plan, `SEED.md` as the plan's contract, and a reader of what the site already holds.
- `project/`: the solution composed into the CLI's Astro scaffold.

`compose.mjs` at the root composes a solution's layers into a project.

### wix-manage

Online: https://www.wix.com/skills/wix-manage/SKILL.md. On disk: the plugin's `skills/wix-manage/`, or `.agents/skills/wix-manage/`.

REST recipes to configure and manage a site's business solutions, one recipe per task with the exact endpoints, request bodies and order of steps. `SKILL.md` is the index of every recipe by area, each a link. The recipes are under `references/<area>/`: `app-installation`, `stores`, `ecommerce`, `bookings`, `calendar`, `donations`, `get-paid`, `pricing-plans`, `restaurants`, `events`, `blog`, `cms`, `rich-content`, `forms`, `contacts`, `automations`, `marketing`, `google-ads`, `google-business-profile`, `analytics`, `seo`, `media`, `sites`, `domains`, `site-properties`, `collaborators`, `custom-apps`, `dashboard-navigation`, `accessibility`. Each recipe is also a docs article under its API's section.

### wix-studio-two

Online: https://www.wix.com/skills/wix-studio-two/SKILL.md. On disk: the plugin's `skills/wix-studio-two/`, or `.agents/skills/wix-studio-two/`.

Creates a Wix Studio Two site, or opens an existing one, and builds or changes it with no local files: the site is exported to a remote Dev Machine, edited and previewed there, and saved to Wix when the user asks. Studio Two sites only; never publishes.

### wix-docs

Online: https://www.wix.com/skills/wix-docs/SKILL.md. On disk: the plugin's `skills/wix-docs/`, or `.agents/skills/wix-docs/`.

Looks up the Wix API and SDK documentation to confirm an endpoint, method, request and response shape, field, enum or error before writing Wix code. `SKILL.md` has the two lanes, plain `curl` and the MCP's documentation tools, with the search, browse and read requests. `references/API_SPEC_SEARCH.md`: the spec index and its queries. `references/CALLING.md`: the identities a call runs as and how each token is minted. `references/EXTRACTING.md`: reading only the needed part of a big menu or method page with `curl` and `grep`.

### wix-readme

This index.
