@wix/agent-skills 1.8.0 → 1.10.0

package/skills/wix-manage/references/app-installation/install-wix-apps.md

@@ -4,7 +4,7 @@ description: Installs Wix apps on a site using Apps Installer API. Covers enabli
 ---
 # Install Wix Apps on a Site
 
-This recipe guides you through installing Wix apps on a site using the Apps Installer REST API, including enabling Velo (Wix Code) when needed.
+This recipe guides you through installing Wix apps on a site using the Apps Installer REST API.
 
 ## Prerequisites
 
@@ -51,30 +51,8 @@ Use the returned `appId` as the `appDefId` in Step 2.
 - The `appDefId` field in the install request and the `appId` field returned here are the same value
 - If multiple results come back, match on `basicInfo.name` to confirm you have the right app before installing
 - Only listings with `status: "PUBLISHED"` can be installed
-## Step 1: Enable Velo (Wix Code) if Needed
 
-If you receive the error `WDE0110: Wix Code not enabled`, you must first enable Velo on the site.
-
-**Endpoint**: `POST https://www.wixapis.com/mcp-serverless/v1/velo/provision`
-
-**Request**:
-```bash
-curl -X POST \
-  'https://www.wixapis.com/mcp-serverless/v1/velo/provision/' \
-  -H 'Authorization: <AUTH>' \
-  -H 'Content-Type: application/json' \
-  -d '{}'
-```
-
-**Response**: Empty body on success.
-
-### IMPORTANT NOTES:
-- Only call this endpoint if you receive the `WDE0110` error
-- This is a one-time operation per site
-
----
-
-## Step 2: Install the Wix App
+## Install the Wix App
 
 Use the Apps Installer API to install any Wix app on a site.
 
@@ -122,6 +100,7 @@ Some common apps:
 | Wix Blog | `14bcded7-0066-7c35-14d7-466cb3f09103` |
 | Wix Events | `140603ad-af8d-84a5-2c80-a0f60cb47351` |
 | Wix Pricing Plans | `1522827f-c56c-a5c9-2ac9-00f9e6ae12d3` |
+| Wix CMS | `e593b0bd-b783-45b8-97c2-873d42aacaf4` |
 
 ### IMPORTANT NOTES:
 - NEVER guess the `appDefId`. For Wix-built apps, use the table above. For any other app, resolve the ID using Step 0 (Search Market Listings).
@@ -135,9 +114,6 @@ Some common apps:
 ### App Not Installed Error
 If you receive an error indicating a required app is not installed, use this recipe to install it before proceeding.
 
-### WDE0110: Wix Code not enabled
-Call the Velo provision endpoint (Step 1) first, then retry the original operation.
-
 ---
 
 ## Next Steps

package/skills/wix-manage/references/bookings/create-appointment-service.md

@@ -0,0 +1,254 @@
+---
+name: "Create Appointment Service"
+description: "Create an appointment booking service — e.g. 'set up consultations', 'create a 1-on-1 session', 'add a personal training appointment', 'create a meeting service for $25'. Handles staff assignment (required), session duration, pricing, and 1-on-1 capacity defaults via bulkCreateServices API."
+---
+
+# Create Appointment Service from Prompt
+
+## When to Use
+
+- User wants to create an appointment-based service: "set up consultations", "create a 1-on-1 session", "add a personal training appointment", "create a meeting service"
+- The service type is APPOINTMENT — customer picks an available time slot during staff working hours
+- For general service creation where the type is ambiguous, see [Create Booking Service from Prompt](./create-booking-service-from-prompt.md)
+
+## Prerequisites
+
+- **Wix Bookings app installed** (App ID: `13d21c63-b5ec-5912-8397-c3a5ddb27a97`). Use [List Installed Apps](../app-installation/list-installed-apps.md) to verify, and [Install Wix Apps](../app-installation/install-wix-apps.md) to install if missing.
+- For full API field definitions, validation rules, and troubleshooting, see [Create and Update Booking Services](./create-and-update-booking-services.md)
+
+---
+
+## Step 1: Gather Business Context
+
+Run these queries to collect site data for informed defaults.
+
+### 1a. Query Staff Members (CRITICAL for Appointments)
+
+```bash
+curl -X POST 'https://www.wixapis.com/bookings/v1/staff-members/query' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "query": {},
+    "fields": ["RESOURCE_DETAILS"]
+  }'
+```
+
+Save each staff member's `resourceId` (not `id`). Note which one has `default: true`.
+
+**APPOINTMENT services REQUIRE at least one staff member.** If no staff members exist, create one first using [Bookings Staff Setup](./bookings-staff-setup.md).
+
+### 1b. Query Service Categories
+
+```bash
+curl -X POST 'https://www.wixapis.com/bookings/v2/categories/query' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{ "query": {} }'
+```
+
+### 1c. Get Site Currency
+
+```bash
+curl -X GET 'https://www.wixapis.com/site-properties/v4/properties' \
+  -H 'Authorization: <AUTH>'
+```
+
+Extract `properties.paymentCurrency`. Fall back to `USD` if unavailable.
+
+### 1d. Query Existing Services (Duplicate Check)
+
+```bash
+curl -X POST 'https://www.wixapis.com/bookings/v2/services/query' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{ "query": { "paging": { "limit": 100 } } }'
+```
+
+Warn the user if a service with a similar name already exists.
+
+---
+
+## Step 2: Apply Appointment Defaults
+
+For any fields the user did not explicitly specify:
+
+| Field | Default | Notes |
+|---|---|---|
+| Duration | 60 minutes | Set via `schedule.availabilityConstraints.sessionDurations` |
+| Capacity | 1 | Appointments are typically 1-on-1 |
+| Staff | Auto-assign | Use `default: true` staff, or first available |
+| Online booking | Enabled | `onlineBooking.enabled: true` |
+
+### Pricing (if not specified)
+
+- Use the site's currency from Step 1c
+- If user specifies a price → `rateType: "FIXED"`
+- If user says "free" → `rateType: "NO_FEE"`, `options.inPerson: true`, `options.online: false`
+- If no price mentioned → infer from context (consultations ~$50-100, sessions ~$30-60) or default to free
+
+### Staff Assignment
+
+- **1 staff member** → auto-assign using their `resourceId`
+- **Multiple staff members** → use the one with `default: true`, or the first one
+- **No staff members** → create one first using [Bookings Staff Setup](./bookings-staff-setup.md), then proceed
+
+### Category
+
+- If categories exist → assign the most relevant one
+- If no categories exist → create a "General" category:
+```bash
+curl -X POST 'https://www.wixapis.com/bookings/v2/categories' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{ "category": { "name": "General" } }'
+```
+
+### Service Name & Description
+
+- Use the user's wording for the service name
+- Generate a brief, professional description (1-2 sentences)
+
+---
+
+## Step 3: Create the Appointment Service
+
+**Paid appointment:**
+
+```bash
+curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "services": [{
+      "name": "<SERVICE_NAME>",
+      "description": "<GENERATED_DESCRIPTION>",
+      "type": "APPOINTMENT",
+
+      "onlineBooking": { "enabled": true },
+      "staffMemberIds": ["<RESOURCE_ID>"],
+      "schedule": {
+        "availabilityConstraints": {
+          "sessionDurations": [<DURATION_MINUTES>]
+        }
+      },
+      "payment": {
+        "rateType": "FIXED",
+        "options": { "online": true, "inPerson": false },
+        "fixed": {
+          "price": { "value": "<PRICE>", "currency": "<CURRENCY>" }
+        }
+      },
+      "category": {
+        "id": "<CATEGORY_ID>"
+      }
+    }]
+  }'
+```
+
+**Free appointment:**
+
+```bash
+curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "services": [{
+      "name": "<SERVICE_NAME>",
+      "description": "<GENERATED_DESCRIPTION>",
+      "type": "APPOINTMENT",
+
+      "onlineBooking": { "enabled": true },
+      "staffMemberIds": ["<RESOURCE_ID>"],
+      "schedule": {
+        "availabilityConstraints": {
+          "sessionDurations": [<DURATION_MINUTES>]
+        }
+      },
+      "payment": {
+        "rateType": "NO_FEE",
+        "options": { "online": false, "inPerson": true }
+      },
+      "category": {
+        "id": "<CATEGORY_ID>"
+      }
+    }]
+  }'
+```
+
+### APPOINTMENT-Specific Reminders
+
+- `staffMemberIds` is **required** — uses `resourceId` values, not staff member `id`
+- `schedule.availabilityConstraints.sessionDurations` sets the appointment length
+- Availability is based on the assigned staff member's working hours schedule
+
+Save the `serviceId` from the response: `results[0].item.service.id`
+
+---
+
+## Step 4: Summary Message
+
+Provide a summary including:
+
+1. **What was created** — service name, price, duration, assigned staff member
+2. **Assumptions made** — list defaults used (e.g., "I set the duration to 60 minutes since you didn't specify")
+3. **Next steps** — "Click Save to finalize, then set up your availability"
+4. **Offer to adjust** — "Want me to change the price, duration, or staff assignment?"
+
+**Example:**
+
+> I created **"Strategy Consultation"**:
+>
+> - **Type**: Appointment (1-on-1)
+> - **Price**: $75 per session
+> - **Duration**: 60 minutes
+> - **Staff**: Assigned to Sarah Johnson
+> - **Category**: Consulting
+>
+> I assumed a 60-minute duration since you didn't specify. You can review and adjust the details in the service form.
+
+---
+
+## Error Handling
+
+| Error | Cause | Action |
+|---|---|---|
+| 428 "App not installed" | Bookings not installed | Install using [Install Wix Apps](../app-installation/install-wix-apps.md) |
+| 400 "staffMemberIds required" | No staff assigned | Query staff; if none exist, create one via [Bookings Staff Setup](./bookings-staff-setup.md) |
+| 400 "INVALID_PAYMENT_OPTIONS" | Payment misconfigured | Free: `inPerson: true`, `online: false`. Paid: price > 0 |
+| 403 | Permission denied | Inform user they lack permission |
+
+---
+
+## Payment Validation Quick Reference
+
+| rateType | `options.online` | `options.inPerson` | Valid? |
+|----------|------------------|-------------------|--------|
+| FIXED    | true             | false             | ✓      |
+| FIXED    | false            | true              | ✓      |
+| FIXED    | true             | true              | ✓      |
+| NO_FEE   | false            | true              | ✓      |
+| NO_FEE   | true             | false             | ✗      |
+| Any      | false            | false             | ✗      |
+
+---
+
+## What This Skill Does NOT Cover
+
+- **Schedule/availability setup** — staff working hours need separate configuration. See [Bookings Staff Setup](./bookings-staff-setup.md)
+- **Pricing plans** — memberships and session packs are separate. See [Create and Update Pricing Plans](../pricing-plans/create-and-update-pricing-plans.md)
+- **Service images** — requires Media Manager API (see [create-and-update-booking-services.md](./create-and-update-booking-services.md))
+
+---
+
+## API Documentation Reference
+
+- [Bulk Create Services](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/bulk-create-services)
+- [Query Services](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/query-services)
+- [Query Categories](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/categories-v2/query-categories)
+- [Create Category](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/categories-v2/create-category)
+- [Query Staff Members](https://dev.wix.com/docs/api-reference/business-solutions/bookings/staff-members/staff-members/query-staff-members)
+- [Create Staff Member](https://dev.wix.com/docs/api-reference/business-solutions/bookings/staff-members/staff-members/create-staff-member)
+- [Site Properties](https://dev.wix.com/docs/api-reference/business-management/site-management/site-properties/properties/read)
+- [About Service Types](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/about-service-types)
+- [About Service Payments](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/about-service-payments)

package/skills/wix-manage/references/bookings/create-booking-service-from-prompt.md

@@ -0,0 +1,37 @@
+---
+name: "Create Booking Service from Prompt"
+description: "Create a booking service from a user prompt — e.g. 'create a yoga class for $50', 'set up consultations for $75', 'add a personal training appointment', 'create a 6-week photography workshop'. Determines the service type (APPOINTMENT, CLASS, or COURSE) and delegates to the type-specific recipe."
+---
+
+# Create Booking Service from Natural Language Prompt
+
+## When to Use
+
+- User describes a service they want to create using natural language (e.g., "create a yoga class for $50", "set up consultation sessions", "add a personal training appointment")
+- The intent is autonomous creation — fill in reasonable defaults rather than asking the user for every field
+
+## Prerequisites
+
+- **Wix Bookings app installed** (App ID: `13d21c63-b5ec-5912-8397-c3a5ddb27a97`)
+- If Bookings is not installed, use [Install Wix Apps](../app-installation/install-wix-apps.md) to install it first
+
+---
+
+## Step 1: Determine Service Type
+
+| User mentions | Type | Recipe |
+|---|---|---|
+| consultation, appointment, meeting, 1-on-1, one-on-one, session | `APPOINTMENT` | [Create Appointment Service](./create-appointment-service.md) |
+| class, yoga, pilates, group session, group workout, bootcamp class | `CLASS` | [Create Class Service](./create-class-service.md) |
+| workshop, program, course, training program, multi-session | `COURSE` | [Create Course Service](./create-course-service.md) |
+| (unclear or unspecified) | `APPOINTMENT` | [Create Appointment Service](./create-appointment-service.md) |
+
+## Step 2: Follow the Type-Specific Recipe
+
+Once the service type is determined, follow the corresponding recipe linked above. Each recipe covers:
+
+1. Gathering business context (staff, categories, currency, duplicate check)
+2. Applying type-specific defaults (pricing, capacity, duration, staff assignment)
+3. Creating the service via `bulkCreateServices`
+4. Navigating to the service form for user review
+5. Providing a summary of what was created and assumptions made

package/skills/wix-manage/references/bookings/create-class-service.md

@@ -0,0 +1,233 @@
+---
+name: "Create Class Service"
+description: "Create a class booking service — e.g. 'create a yoga class for $50', 'set up a pilates class', 'add a group fitness session', 'create a weekly meditation class'. Handles group capacity, recurring session defaults, and pricing via bulkCreateServices API. Staff assignment is not used for classes."
+---
+
+# Create Class Service from Prompt
+
+## When to Use
+
+- User wants to create a group class: "create a yoga class", "set up a pilates class", "add a group fitness session", "create a weekly meditation class"
+- The service type is CLASS — a single event or recurring series that multiple customers can book
+- Customers can sign up for one, several, or all sessions in a class series
+- For general service creation where the type is ambiguous, see [Create Booking Service from Prompt](./create-booking-service-from-prompt.md)
+
+## Prerequisites
+
+- **Wix Bookings app installed** (App ID: `13d21c63-b5ec-5912-8397-c3a5ddb27a97`). Use [List Installed Apps](../app-installation/list-installed-apps.md) to verify, and [Install Wix Apps](../app-installation/install-wix-apps.md) to install if missing.
+- For full API field definitions, validation rules, and troubleshooting, see [Create and Update Booking Services](./create-and-update-booking-services.md)
+
+---
+
+## Step 1: Gather Business Context
+
+Run these queries to collect site data for informed defaults.
+
+### 1a. Query Service Categories
+
+```bash
+curl -X POST 'https://www.wixapis.com/bookings/v2/categories/query' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{ "query": {} }'
+```
+
+### 1b. Get Site Currency
+
+```bash
+curl -X GET 'https://www.wixapis.com/site-properties/v4/properties' \
+  -H 'Authorization: <AUTH>'
+```
+
+Extract `properties.paymentCurrency`. Fall back to `USD` if unavailable.
+
+### 1c. Query Existing Services (Duplicate Check)
+
+```bash
+curl -X POST 'https://www.wixapis.com/bookings/v2/services/query' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{ "query": { "paging": { "limit": 100 } } }'
+```
+
+Warn the user if a service with a similar name already exists.
+
+> **Note:** Staff queries are optional for CLASS services since `staffMemberIds` is ignored by the API. However, querying staff can still be useful for context (e.g., mentioning instructors in the description).
+
+---
+
+## Step 2: Apply Class Defaults
+
+For any fields the user did not explicitly specify:
+
+| Field | Default | Notes |
+|---|---|---|
+| Capacity | 10 | `defaultCapacity` — required for CLASS |
+| Online booking | Enabled | `onlineBooking.enabled: true` |
+
+### Pricing (if not specified)
+
+- Use the site's currency from Step 1b
+- If user specifies a price → `rateType: "FIXED"` (per session)
+- If user says "free" → `rateType: "NO_FEE"`, `options.inPerson: true`, `options.online: false`
+- If no price mentioned → infer from context (yoga/fitness classes ~$15-30, art/music ~$20-40) or default to free
+
+### Capacity (if not specified)
+
+- Default: 10 participants
+- If user mentions capacity (e.g., "small group of 6", "up to 20") → use their number
+- Typical ranges: small group 4-8, standard 10-20, large 20-50
+
+### Category
+
+- If categories exist → assign the most relevant one (e.g., "Fitness", "Wellness")
+- If no categories exist → create one:
+```bash
+curl -X POST 'https://www.wixapis.com/bookings/v2/categories' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{ "category": { "name": "General" } }'
+```
+
+### Service Name & Description
+
+- Use the user's wording for the service name
+- Generate a brief, professional description (1-2 sentences) mentioning it's a group class
+
+---
+
+## Step 3: Create the Class Service
+
+**CRITICAL: CLASS services do NOT use `staffMemberIds` or `sessionDurations`.** These fields are ignored. Use `defaultCapacity` instead.
+
+**Paid class:**
+
+```bash
+curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "services": [{
+      "name": "<SERVICE_NAME>",
+      "description": "<GENERATED_DESCRIPTION>",
+      "type": "CLASS",
+
+      "onlineBooking": { "enabled": true },
+      "defaultCapacity": <CAPACITY>,
+      "payment": {
+        "rateType": "FIXED",
+        "options": { "online": true, "inPerson": false },
+        "fixed": {
+          "price": { "value": "<PRICE>", "currency": "<CURRENCY>" }
+        }
+      },
+      "category": {
+        "id": "<CATEGORY_ID>"
+      }
+    }]
+  }'
+```
+
+**Free class:**
+
+```bash
+curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "services": [{
+      "name": "<SERVICE_NAME>",
+      "description": "<GENERATED_DESCRIPTION>",
+      "type": "CLASS",
+
+      "onlineBooking": { "enabled": true },
+      "defaultCapacity": <CAPACITY>,
+      "payment": {
+        "rateType": "NO_FEE",
+        "options": { "online": false, "inPerson": true }
+      },
+      "category": {
+        "id": "<CATEGORY_ID>"
+      }
+    }]
+  }'
+```
+
+### CLASS-Specific Reminders
+
+- Do **NOT** include `staffMemberIds` — it is ignored for CLASS services
+- Do **NOT** include `schedule.availabilityConstraints.sessionDurations` — not used for CLASS
+- `defaultCapacity` is **required** — sets max participants per session
+- After creation, class sessions must be scheduled separately via `bulkCreateEvents` using the returned `service.schedule.id` (see [Create and Update Booking Services](./create-and-update-booking-services.md))
+
+Save the `serviceId` from the response: `results[0].item.service.id`
+
+---
+
+## Step 4: Summary Message
+
+Provide a summary including:
+
+1. **What was created** — service name, price per session, capacity
+2. **Assumptions made** — list defaults used (e.g., "I set the capacity to 10 participants since you didn't specify")
+3. **Schedule note** — remind the user that class sessions still need to be scheduled
+4. **Next steps** — "Click Save to finalize, then set up the class schedule"
+5. **Offer to adjust** — "Want me to change the price, capacity, or description?"
+
+**Example:**
+
+> I created **"Vinyasa Yoga Class"**:
+>
+> - **Type**: Class (group session)
+> - **Price**: $25 per session
+> - **Capacity**: 10 participants
+> - **Category**: Fitness
+>
+> I assumed a capacity of 10 since you didn't specify. You can review and adjust the details in the service form.
+>
+> **Next step:** You'll need to set up the class schedule (days and times) in the service form.
+
+---
+
+## Error Handling
+
+| Error | Cause | Action |
+|---|---|---|
+| 428 "App not installed" | Bookings not installed | Install using [Install Wix Apps](../app-installation/install-wix-apps.md) |
+| 400 "INVALID_PAYMENT_OPTIONS" | Payment misconfigured | Free: `inPerson: true`, `online: false`. Paid: price > 0 |
+| 403 | Permission denied | Inform user they lack permission |
+
+---
+
+## Payment Validation Quick Reference
+
+| rateType | `options.online` | `options.inPerson` | Valid? |
+|----------|------------------|-------------------|--------|
+| FIXED    | true             | false             | ✓      |
+| FIXED    | false            | true              | ✓      |
+| FIXED    | true             | true              | ✓      |
+| NO_FEE   | false            | true              | ✓      |
+| NO_FEE   | true             | false             | ✗      |
+| Any      | false            | false             | ✗      |
+
+---
+
+## What This Skill Does NOT Cover
+
+- **Class schedule setup** — recurring events (days/times) must be configured separately via Calendar Events API. See [Create and Update Booking Services](./create-and-update-booking-services.md) Step 3.
+- **Pricing plans** — memberships and class packs are separate. See [Create and Update Pricing Plans](../pricing-plans/create-and-update-pricing-plans.md)
+- **Instructor assignment** — `staffMemberIds` is ignored for CLASS. Staff association is managed through calendar events.
+- **Service images** — requires Media Manager API (see [create-and-update-booking-services.md](./create-and-update-booking-services.md))
+
+---
+
+## API Documentation Reference
+
+- [Bulk Create Services](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/bulk-create-services)
+- [Query Services](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/query-services)
+- [Query Categories](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/categories-v2/query-categories)
+- [Create Category](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/categories-v2/create-category)
+- [Bulk Create Events](https://dev.wix.com/docs/api-reference/business-management/calendar/events-v3/bulk-create-event)
+- [Site Properties](https://dev.wix.com/docs/api-reference/business-management/site-management/site-properties/properties/read)
+- [About Service Types](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/about-service-types)
+- [About Service Payments](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/about-service-payments)