@wix/agent-skills 1.5.0 → 1.7.0

package/README.md

@@ -2,9 +2,9 @@
 
 > ⚠️ **EXPERIMENTAL**: This project is in early development. APIs, skill definitions, and behavior may change without notice. Use at your own risk.
 
-Agent skills for building Wix applications with AI coding assistants.
+Agent skills for building Wix app extensions, managing Wix business solutions, developing headless sites, and using the Wix Design System with AI agents.
 
-> **Note**: These skills are designed for the **new Wix CLI**. See [About the Wix CLI](https://dev.wix.com/docs/wix-cli/guides/about-the-wix-cli) to learn more.
+> **Note**: These skills are designed for the **new Wix CLI**. See [About the Wix CLI](https://dev.wix.com/docs/wix-cli/guides/about-the-wix-cli) to learn more. For an overview of how skills work with AI tools, see [About Wix Skills](https://dev.wix.com/docs/api-reference/articles/ai-tools/about-wix-skills).
 
 ## Installation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/agent-skills",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "Wix Skills for AI coding agents — versioned npm distribution of the wix/skills content.",
   "license": "MIT",
   "repository": {

package/skills/wix-app/SKILL.md

@@ -1,13 +1,15 @@
 ---
 name: wix-app
 description: "Build and review Wix CLI app extensions — dashboard pages, modals, plugins, menu plugins, custom element widgets, Editor React components, site plugins, embedded scripts, backend APIs, backend events, service plugins, data collections, and App Market readiness. Use when building ANY feature or extension for a Wix CLI app or preparing a Wix app for App Market review. Triggers on: add, build, create, implement, help me, dashboard, widget, plugin, backend, API, event, collection, embedded script, service plugin, Editor React component, checkout, shipping, tax, discount, SPI, CMS, schema, tracking, popup, admin panel, menu item, modal, validate, test, verify, register extension, App Market, app review, submission readiness."
-compatibility: Requires Wix CLI development environment.
+compatibility: requires `@wix/cli` >= 1.1.192.
 ---
 
 # Wix App Builder
 
 Helps build extensions for Wix CLI applications. Covers all extension types: dashboard pages, modals, plugins, menu plugins, custom element widgets, Editor React components, site plugins, embedded scripts, backend APIs, events, service plugins, and data collections.
 
+**Scaffolding is owned by the Wix CLI.** For every extension type except Backend API, files, folders, builder boilerplate, UUIDs, and `src/extensions.ts` registration are generated by `wix generate --params`. This skill provides the decision logic, API guidance, configuration semantics, and business-logic patterns that fill in the generated stubs.
+
 ## ⚠️ MANDATORY WORKFLOW CHECKLIST ⚠️
 
 **Before reporting completion to the user, ALL boxes MUST be checked:**
@@ -20,10 +22,9 @@ Helps build extensions for Wix CLI applications. Covers all extension types: das
   - [ ] Explained recommendation with reasoning
 - [ ] **Step 2:** Read extension reference file(s) for the chosen type(s) and the project-wide [CODE_QUALITY.md](references/CODE_QUALITY.md)
 - [ ] **Step 3:** Checked API references; used MCP discovery only for gaps
-- [ ] **Step 4:** Implemented all extensions
-  - [ ] All files created
-  - [ ] Extension(s) registered in extensions.ts
-  - [ ] Invoked `wix-design-system` skill ONLY before writing the first `.tsx`/`.jsx` file that imports `@wix/design-system`. Skip this skill entirely for backend-only or data-only extensions.
+- [ ] **Step 4a:** Scaffolded each CLI-supported extension via `wix generate --params`
+- [ ] **Step 4b:** Filled in business logic in the generated files
+  - [ ] Invoked `wix-design-system` skill ONLY before editing the first `.tsx`/`.jsx` file that imports `@wix/design-system`. Skip for backend-only or data-only extensions.
 - [ ] **Step 5:** Ran validation (see [Validation](#validation))
   - [ ] Dependencies installed
   - [ ] TypeScript compiled
@@ -39,6 +40,7 @@ Helps build extensions for Wix CLI applications. Covers all extension types: das
 
 | ❌ WRONG                                    | ✅ CORRECT                                     |
 | ------------------------------------------- | ---------------------------------------------- |
+| Hand-writing builder files, folders, UUIDs, or extension registration | Run `wix generate --params` — it owns scaffolding |
 | Implementing without reading the extension reference | Always read the relevant reference file first |
 | Using MCP discovery without checking refs   | Check reference files first                    |
 | Reporting done without validation           | Always run validation at the end               |
@@ -79,23 +81,26 @@ Helps build extensions for Wix CLI applications. Covers all extension types: das
 
 ## Extension Types Reference Table
 
-| Extension Type        | Category  | Visibility  | Use When                              | Reference File                                          |
-| --------------------- | --------- | ----------- | ------------------------------------- | ------------------------------------------------------- |
-| Dashboard Page        | Dashboard | Admin only  | Full admin pages                      | [DASHBOARD_PAGE.md](references/DASHBOARD_PAGE.md)       |
-| Dashboard Modal       | Dashboard | Admin only  | Popup dialogs                         | [DASHBOARD_MODAL.md](references/DASHBOARD_MODAL.md)     |
-| Dashboard Plugin      | Dashboard | Admin only  | Extend Wix app dashboards             | [DASHBOARD_PLUGIN.md](references/DASHBOARD_PLUGIN.md)   |
-| Dashboard Menu Plugin | Dashboard | Admin only  | Add menu items to Wix app dashboards  | [DASHBOARD_MENU_PLUGIN.md](references/DASHBOARD_MENU_PLUGIN.md) |
-| Service Plugin        | Backend   | Server-side | Customize business flows              | [SERVICE_PLUGIN.md](references/SERVICE_PLUGIN.md)       |
-| Backend Event Extension | Backend | Server-side | React to events                       | [BACKEND_EVENT.md](references/BACKEND_EVENT.md)         |
-| Backend API           | Backend   | API         | Custom HTTP handlers                  | [BACKEND_API.md](references/BACKEND_API.md)             |
-| Data Collection       | Backend   | Data        | CMS collections for app data          | [DATA_COLLECTION.md](references/DATA_COLLECTION.md)     |
-| Editor React component | Site     | Public      | Editor React components with editor manifests | [EDITOR_REACT_COMPONENT.md](references/EDITOR_REACT_COMPONENT.md) |
-| Custom element widget | Site      | Public      | Standalone widgets                    | [CUSTOM_ELEMENT_WIDGET.md](references/CUSTOM_ELEMENT_WIDGET.md) |
-| Site Plugin           | Site      | Public      | Extend Wix business solutions         | [SITE_PLUGIN.md](references/SITE_PLUGIN.md)             |
-| Embedded Script       | Site      | Public      | Inject scripts/analytics              | [EMBEDDED_SCRIPT.md](references/EMBEDDED_SCRIPT.md)     |
+| Extension Type | Category | `extensionType` (for `wix generate --params`) | Reference File |
+| --- | --- | --- | --- |
+| Dashboard Page | Dashboard | `DASHBOARD_PAGE` | [DASHBOARD_PAGE.md](references/DASHBOARD_PAGE.md) |
+| Dashboard Modal | Dashboard | `DASHBOARD_MODAL` | [DASHBOARD_MODAL.md](references/DASHBOARD_MODAL.md) |
+| Dashboard Plugin | Dashboard | `DASHBOARD_PLUGIN` | [DASHBOARD_PLUGIN.md](references/DASHBOARD_PLUGIN.md) |
+| Dashboard Menu Plugin | Dashboard | `DASHBOARD_MENU_PLUGIN` | [DASHBOARD_MENU_PLUGIN.md](references/DASHBOARD_MENU_PLUGIN.md) |
+| Service Plugin | Backend | `SERVICE_PLUGIN` | [SERVICE_PLUGIN.md](references/SERVICE_PLUGIN.md) |
+| Backend Event Extension | Backend | `EVENT` | [BACKEND_EVENT.md](references/BACKEND_EVENT.md) |
+| Backend API | Backend | — (manual, see banner below) | [BACKEND_API.md](references/BACKEND_API.md) |
+| Data Collection | Backend | `DATA_COLLECTION` | [DATA_COLLECTION.md](references/DATA_COLLECTION.md) |
+| Editor React component | Site | `EDITOR_REACT_COMPONENT` | [EDITOR_REACT_COMPONENT.md](references/EDITOR_REACT_COMPONENT.md) |
+| Custom element widget | Site | `CUSTOM_ELEMENT` | [CUSTOM_ELEMENT_WIDGET.md](references/CUSTOM_ELEMENT_WIDGET.md) |
+| Site Plugin | Site | `SITE_PLUGIN` | [SITE_PLUGIN.md](references/SITE_PLUGIN.md) |
+| Embedded Script | Site | `EMBEDDED_SCRIPT` | [EMBEDDED_SCRIPT.md](references/EMBEDDED_SCRIPT.md) |
+
 **Key constraints:**
 - Dashboard Page cannot use `<Modal />`; use a separate Dashboard Modal and `dashboard.openModal()`.
 
+> **⚠️ Backend API is the only extension type the CLI does NOT scaffold.** `wix generate` has no `BACKEND_API` handler. Create files directly per [BACKEND_API.md](references/BACKEND_API.md).
+
 ## Extension Comparison
 
 | Custom element widget vs Editor React component vs Site Plugin | Dashboard Page vs Modal | Service Plugin vs Event |
@@ -200,7 +205,7 @@ Use the Extension Types Reference Table and decision content above. State extens
    - Backend events → `references/backend-event/COMMON-EVENTS.md`
    - Wix Data → `references/data-collection/WIX_DATA.md`
    - Dashboard SDK → `references/dashboard-page/DASHBOARD_API.md`
-   - Service Plugin SPIs → `references/service-plugin/*.md`
+   - Service Plugin SPIs → read `references/SERVICE_PLUGIN.md` together with the matching `references/service-plugin/<NAME>.md` leaf
 4. **Verify the specific method/event exists** in references
 5. **ONLY use MCP discovery if NOT found** in reference files
 
@@ -230,15 +235,29 @@ Use the Extension Types Reference Table and decision content above. State extens
 **MCP Tools for discovery (when needed):**
 
 - `SearchWixSDKDocumentation` - SDK methods and APIs (**Always use maxResults: 5**)
-- `ReadFullDocsArticle` - Full documentation when needed (only if search results need more detail)
+- `ReadFullDocsMethodSchema` - Full type schema for a specific SDK method (parameters, return type, permissions)
+- `ReadFullDocsArticle` - Prose guides and conceptual articles only (not for SDK method signatures)
+
+### Step 4a: Scaffold via the CLI
+
+For each extension **except Backend API**, run `npx wix generate --params '<json>'`. The command returns `{"success":true,"extensionType":"...","newFiles":[...]}` on success.
+
+If the command fails because of unknown or invalid params, run `npx wix schema generate --type <extensionType>` to print the JSON Schema for that extension type, fix the `--params` payload, and retry. Do not fall back to manual scaffolding.
+
+**What the CLI does automatically:**
+- Creates folders and stub files
+- Generates a fresh UUID for the extension `id`
+- Updates `src/extensions.ts` with the import and `.use()` call
+- Enforces naming rules (kebab-case, hyphen-required custom elements, etc.)
 
-### Step 4: Implement Extensions
+**Backend API exception:** Create `src/pages/api/*.ts` files manually per [BACKEND_API.md](references/BACKEND_API.md).
 
-Follow the extension reference file to implement each extension. Key rules:
+### Step 4b: Fill in business logic
 
-- ⚠️ MANDATORY when using WDS: Invoke the `wix-design-system` skill before writing your first `.tsx`/`.jsx` file that imports `@wix/design-system`. Do NOT invoke it preemptively for backend-only or data-only jobs — it adds large content to context that you won't use.
-- ⚠️ MANDATORY when using Data Collections: Use EXACT collection ID from `idSuffix` (case-sensitive). Example: If `idSuffix` is "product-recommendations", use `<app-namespace>/product-recommendations` NOT `productRecommendations`.
-- Register all extensions in `src/extensions.ts` (see [Extension Registration](#extension-registration)).
+Open every path returned in `newFiles` and replace stubbed handler bodies / UI / queries with the user's actual logic, guided by the extension reference file's API and configuration sections.
+
+- ⚠️ MANDATORY when using WDS: Invoke the `wix-design-system` skill **before editing your first `.tsx`/`.jsx` file that imports `@wix/design-system`**. Do NOT invoke it preemptively for backend-only or data-only jobs — it adds large content to context that you won't use.
+- ⚠️ MANDATORY when using Data Collections: Use the EXACT collection ID from `idSuffix` (case-sensitive). If `idSuffix` is `"product-recommendations"`, use `<app-namespace>/product-recommendations` NOT `productRecommendations`.
 
 ### Step 5: Run Validation
 
@@ -299,21 +318,7 @@ The following actions need to be done manually by you:
 
 ## Extension Registration
 
-After creating any extension file, you must update the main `src/extensions.ts` file to register the extension with the app. See [EXTENSION_REGISTRATION.md](references/EXTENSION_REGISTRATION.md) for the complete guide.
-
-**Quick pattern:**
-
-```typescript
-import { app } from "@wix/astro/builders";
-import { dashboardpageMyPage } from "./extensions/dashboard/pages/my-page/extensions.ts";
-import { embeddedscriptMyScript } from "./extensions/site/embedded-scripts/my-script/extensions.ts";
-
-export default app()
-  .use(dashboardpageMyPage)
-  .use(embeddedscriptMyScript);
-```
-
-Without registration, extensions will not appear or function in the Wix dashboard/editor/site.
+`wix generate --params` updates `src/extensions.ts` automatically for every CLI-supported extension type. The only case that still requires manual editing is Backend API. For background, troubleshooting, and the manual recovery pattern when `src/extensions.ts` drifts, see [EXTENSION_REGISTRATION.md](references/EXTENSION_REGISTRATION.md).
 
 ---
 
@@ -332,11 +337,13 @@ Stop and report errors if any step fails. Check `.wix/debug.log` on failures.
 
 ## Cost Optimization
 
+- **Let the CLI scaffold** — don't burn tokens describing folder layouts or builder boilerplate
+- **Only run `wix schema generate --type <extensionType>`** when `wix generate --params` fails — don't pre-fetch it
 - **Read extension reference first** — always read the relevant extension reference file before implementing
 - **Check API references first** — read relevant API reference files before using MCP discovery
 - **Skip discovery** when all required APIs are in reference files
 - **maxResults: 5** for all MCP SDK searches
-- **ReadFullDocsArticle** only when search results need more context
+- **ReadFullDocsMethodSchema** for SDK method schemas; **ReadFullDocsArticle** for prose guides only
 - **Invoke wix-design-system** first when using WDS (prevents import errors)
 
 ## Documentation

package/skills/wix-app/references/BACKEND_EVENT.md

@@ -1,20 +1,19 @@
 
 # Wix CLI Backend Event Extension
 
-Creates event extensions for Wix CLI applications. Events are triggered when specific conditions occur—on a Wix user's site for app projects, or on your project's site for headless projects. Your project responds using event extensions built on JavaScript SDK webhooks; the CLI subscribes your project to these webhooks.
+Event extensions run custom logic when something happens on a site — a contact is created, an order is placed, a booking is confirmed, a blog post is published. Each extension is built on a Wix JavaScript SDK webhook; the CLI subscribes your project to it.
 
-Common use cases: run logic when a contact is created, an order is placed, a booking is confirmed, or a blog post is published.
+Common use cases: react to CRM events, sync data on order creation, send notifications when a booking is confirmed.
 
-## Quick Start Checklist
+## Scaffold
 
-Follow these steps in order when creating an event extension.
+Use `wix generate --params` with all required fields:
 
-1. [ ] Create event folder: `src/extensions/backend/events/<event-name>/`
-2. [ ] Create `<event-name>.ts` with the SDK event import and handler function
-3. [ ] Create `<event-name>.extension.ts` with `extensions.event()` and a unique UUID
-4. [ ] Update `src/extensions.ts` to import and use the new extension
+```bash
+wix generate --params '{"extensionType":"EVENT","folder":"<folder>"}'
+```
 
-**User (manual):** Configure app permissions for the event in the app dashboard if required; release a version and trigger the event to test.
+`folder` must be lowercase alphanumeric and hyphens. The CLI generates the folder, both files, the UUID, and the `src/extensions.ts` registration. The scaffolded handler file imports a sample SDK event (CRM Contact Created) — replace the import and the handler body with the event you actually want.
 
 ## References
 
@@ -22,63 +21,9 @@ Follow these steps in order when creating an event extension.
 | --- | --- |
 | Common events (CRM, eCommerce, Bookings, Blog) | [COMMON-EVENTS.md](backend-event/COMMON-EVENTS.md) |
 
-## Output Structure
-
-Two files per event ([docs](https://dev.wix.com/docs/wix-cli/guides/extensions/backend-extensions/events/event-extension-files-and-code)). Only **one** handler per event allowed in the app (including dashboard handlers).
-
-```
-src/extensions/backend/events/<event-name>/
-├── <event-name>.extension.ts   # Builder: extensions.event({ id, source }) – id is unique GUID
-└── <event-name>.ts             # Handler: imports SDK event (e.g. onContactCreated), runs on trigger
-```
-
-## Implementation Pattern
-
-### Event builder (`<event-name>.extension.ts`)
-
-Use `extensions.event()` from `@wix/astro/builders`. Required fields: `id` (unique GUID), `source` (path to the handler file).
-
-```typescript
-import { extensions } from "@wix/astro/builders";
-
-export const eventContactCreated = extensions.event({
-  id: "{{GENERATE_UUID}}",
-  source: "./extensions/backend/events/contact-created/contact-created.ts",
-});
-```
-
-**CRITICAL: UUID Generation**
-
-The `id` must be a unique, static UUID v4 string. Generate a fresh UUID for each extension—do NOT use `randomUUID()` or copy UUIDs from examples. Replace `{{GENERATE_UUID}}` with a freshly generated UUID like `"a1b2c3d4-e5f6-7890-abcd-ef1234567890"`.
-
-### Event handler (`<event-name>.ts`)
-
-Import the event from the correct SDK module and pass a handler. Wix invokes the handler with the event payload and metadata when the event occurs. Handler signatures are documented in the [JavaScript SDK reference](https://dev.wix.com/docs/sdk).
-
-```typescript
-import { contacts } from "@wix/crm";
-
-export default contacts.onContactCreated((event) => {
-  console.log("Contact created:", event.entity);
-  // Custom logic: sync to CRM, send welcome email, etc.
-});
-```
-
-Handler can be `async`; ensure errors are caught and logged so one failing handler does not break others.
-
-## Extension Registration
-
-**Two steps required.**
-
-### Step 1: Event builder file
-
-Create `<event-name>.extension.ts` inside the event folder (and `<event-name>.ts` for the handler) as shown in [Implementation Pattern](#implementation-pattern) above.
-
-### Step 2: Register in main extensions.ts
-
-**CRITICAL:** Read [Extension Registration reference](EXTENSION_REGISTRATION.md) and add the event extension to `src/extensions.ts` (import and `.use(eventContactCreated)` or equivalent). Without this, the event extension is not active.
+## Handler implementation
 
-Naming: export names follow `event{CamelCaseName}` (e.g. `eventContactCreated`, `eventOrderPaid`).
+Each handler imports an event from the relevant `@wix/*` SDK module and is `default`-exported (e.g., `export default contacts.onContactCreated((event) => { ... })`). See [COMMON-EVENTS.md](backend-event/COMMON-EVENTS.md) for the SDK module, handler name, payload shape, and required permission for each common event. Handlers can be `async`; wrap logic in try/catch so one failing handler doesn't break others.
 
 ## Elevating Permissions for API Calls