@wix/agent-skills 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Wix.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# Wix Skills
+
+> ⚠️ **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.
+
+> **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.
+
+## Installation
+
+### Claude Code Plugin
+
+In [Claude Code](https://docs.anthropic.com/en/docs/claude-code), run:
+
+```bash
+/plugin marketplace add wix/skills
+/plugin install wix@wix
+```
+
+### Codex Plugin
+
+In a terminal, register the marketplace:
+
+```bash
+codex plugin marketplace add wix/skills
+```
+
+Then in Codex CLI, run `/plugins`, select **Wix**, and choose **Install Plugin**.
+
+### VS Code Plugin
+
+In VS Code, open the Command Palette (`CMD+SHIFT+P`), select **Chat: Install Plugin From Source**, and enter `https://github.com/wix/skills`.
+
+### Cursor Plugin
+
+Go to **Settings > Rules > New Rule > Add from Github** with `https://github.com/wix/skills.git`.
+
+### Gemini CLI
+
+Install using [Gemini CLI](https://geminicli.com):
+
+```bash
+gemini extensions install https://github.com/wix/skills
+```
+
+### Skills CLI
+
+Install using [skills CLI](https://github.com/vercel-labs/skills):
+
+```bash
+# Install all skills
+npx skills add wix/skills
+
+# Install globally
+npx skills add wix/skills -g
+```
+
+### npm Package (versioned distribution)
+
+For Wix-internal infrastructure that needs a pinned, versioned skills snapshot (e.g., App Builder, Studio 2, `@wix/cli`), `@wix/agent-skills` is also published to npm:
+
+```bash
+npm install @wix/agent-skills
+```
+
+The npm package contains the same skill bodies as the GitHub repo but pinned to a specific version. Consumers typically install it as a transitive dependency of `@wix/cli` rather than directly. See [CODEAI-505](https://wix.atlassian.net/browse/CODEAI-505) for context.
+
+## Available Skills
+
+| Skill                                    | Purpose                          | When to Use                                                                                                                         |
+| ---------------------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| [wix-app](skills/wix-app/SKILL.md)       | Build Wix app extensions         | Adding any extension — dashboard pages, site widgets, backend events, service plugins, embedded scripts, data collections, and more |
+| [wix-design-system](skills/wix-design-system/SKILL.md) | Wix Design System reference      | Looking up WDS component props, examples, icons                                                                                     |
+| [wix-manage](skills/wix-manage/SKILL.md) | Wix business solution management | REST API operations for configuring and managing Wix business solutions                                                             |
+| [wix-headless](skills/wix-headless/SKILL.md) | Build a complete Wix Managed Headless site | Building a new site end-to-end from a single prompt — discovery, design, feature wiring, and preview |
+
+## Supported Agents
+
+These skills work with any agent that supports the [Agent Skills specification](https://github.com/vercel-labs/add-skill):
+
+- Cursor
+- Claude Code
+- Gemini CLI
+- Codex CLI
+- GitHub Copilot
+- Windsurf
+- And [many more](https://github.com/vercel-labs/add-skill#available-agents)
+
+## Versioning
+
+`@wix/agent-skills` follows semver. Bumps target **AI-generated-code stability** — i.e., whether a change could cause an agent using these skills to produce broken code on the previous-major `wix-cli`:
+
+| Bump | Examples |
+| --- | --- |
+| **patch** | Wording fix, typo, link update, clarification of existing guidance |
+| **minor** | New skill added, new section in an existing skill, additive guidance for a non-breaking `wix-cli` feature |
+| **major** | Skill rename/removal, rewrite of guidance for a deprecated `wix-cli` API, anything that would cause AI-generated code to fail on the previous-major `wix-cli` |
+
+When a major bump is required (a breaking change in the underlying `wix-cli`), the previous major continues on a `release/<N>.x` maintenance branch and receives backports for genuine bugs only — no new features.
+
+## Releasing
+
+Releases run via the [`release` GitHub Actions workflow](.github/workflows/release.yml) using npm Trusted Publishing (no stored tokens). Triggered manually from the **Actions** tab: pick `version_strategy` and optionally `dry_run`. Modeled on [`wix/interact`](https://github.com/wix/interact/blob/master/.github/workflows/release-interact.yml)'s setup.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on adding new skills.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@wix/agent-skills",
+  "version": "1.0.0",
+  "description": "Wix Skills for AI coding agents — versioned npm distribution of the wix/skills content.",
+  "license": "MIT",
+  "homepage": "https://github.com/wix/skills",
+  "bugs": {
+    "url": "https://github.com/wix/skills/issues"
+  },
+  "files": [
+    "skills/**",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "echo \"no tests\" && exit 0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "wix": {
+    "artifact": {
+      "groupId": "com.wixpress.npm",
+      "artifactId": "agent-skills"
+    }
+  },
+  "falconPackageHash": "24f06f88a88f4df43f1a968af062b6ce06d39ba2dc0f48c2bdcc69c1"
+}

package/skills/wix-app/SKILL.md

@@ -0,0 +1,344 @@
+---
+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.
+---
+
+# 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.
+
+## ⚠️ MANDATORY WORKFLOW CHECKLIST ⚠️
+
+**Before reporting completion to the user, ALL boxes MUST be checked:**
+
+- [ ] **Step 1:** Determined extension type(s) needed
+  - [ ] Asked clarifying questions if requirements were unclear
+  - [ ] Checked for implicit Data Collection need — unless user provided a collection ID directly (see [Data Collection Inference](#data-collection-inference))
+  - [ ] Obtained app namespace if Data Collection extension is being created
+  - [ ] Determined full scoped collection IDs if Data Collection extension is being created (see [Collection ID Coordination](#collection-id-coordination))
+  - [ ] 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 5:** Ran validation (see [Validation](#validation))
+  - [ ] Dependencies installed
+  - [ ] TypeScript compiled
+  - [ ] Build succeeded
+  - [ ] Preview deployed
+- [ ] **Step 6:** Collected and presented ALL manual action items to user
+
+**🛑 STOP:** If any box is unchecked, do NOT proceed to the next step.
+
+---
+
+## ❌ ANTI-PATTERNS (DO NOT DO)
+
+| ❌ WRONG                                    | ✅ CORRECT                                     |
+| ------------------------------------------- | ---------------------------------------------- |
+| 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               |
+| Letting manual action items get buried      | Aggregate all manual steps at the very end     |
+
+---
+
+## Quick Decision Helper
+
+1. **What are you trying to build?**
+   - Admin interface → Dashboard Extensions
+   - Backend logic → Backend Extensions
+   - Data storage / CMS collections → Data Collection
+   - Editor React component → Site Extensions (app projects only)
+
+2. **Who will see it?**
+   - Admin users only → Dashboard Extensions
+   - Site visitors → Site Extensions
+   - Server-side only → Backend Extensions
+
+3. **Where will it appear?**
+   - Dashboard sidebar/page → Dashboard Page or Modal
+   - Existing Wix app dashboard (widget) → Dashboard Plugin
+   - Existing Wix app dashboard (menu item) → Dashboard Menu Plugin
+   - Anywhere on site → custom element widget
+   - Anywhere on site (with editor manifest) → Editor React component
+   - Wix business solution page → Site Plugin
+   - During business flow → Service Plugin
+   - After event occurs → Backend Event Extension
+
+## Decision Flow (Not sure?)
+
+- **Admin:** Need full-page UI? → Dashboard Page. Need popup/form? → Dashboard Modal. Extending Wix app dashboard with a visual widget? → Dashboard Plugin. Adding a menu item to a Wix app dashboard's more-actions or bulk-actions menu? → Dashboard Menu Plugin. **Modal constraint:** Dashboard Pages cannot use `<Modal />`; use a separate Dashboard Modal extension and `dashboard.openModal()`.
+- **Backend:** During business flow (checkout/shipping/tax)? → Service Plugin. After event (webhooks/sync)? → Backend Event Extension. Custom HTTP endpoints? → Backend API. Need CMS collections for app data? → Data Collection.
+- **Site:** User places anywhere (standalone)? → custom element widget. Editor React component with editor manifest (styling, content, elements)? → Editor React component. Fixed slot on Wix app page? → Site Plugin. Scripts/analytics only? → Embedded Script.
+
+---
+
+## 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)     |
+**Key constraints:**
+- Dashboard Page cannot use `<Modal />`; use a separate Dashboard Modal and `dashboard.openModal()`.
+
+## Extension Comparison
+
+| Custom element widget vs Editor React component vs Site Plugin | Dashboard Page vs Modal | Service Plugin vs Event |
+| -------------------------------------------------------------- | ----------------------- | ----------------------- |
+| Custom element widget: standalone interactive component. Editor React component: React with editor manifest (CSS/data/elements). Plugin: fixed slot in Wix app page. | Page: full page. Modal: overlay; use for popups. | Service: during flow. Event: after event. |
+
+---
+
+## Cross-Cutting References
+
+| Topic | Reference |
+| --- | --- |
+| Code Quality Requirements (applies to all generated code) | [CODE_QUALITY.md](references/CODE_QUALITY.md) |
+| Extension Registration | [EXTENSION_REGISTRATION.md](references/EXTENSION_REGISTRATION.md) |
+| App Validation | [APP_VALIDATION.md](references/APP_VALIDATION.md) |
+| App Market Review | [APP_MARKET_REVIEW.md](references/APP_MARKET_REVIEW.md) |
+| App Identifiers (Namespace, Code ID) | [APP_IDENTIFIERS.md](references/APP_IDENTIFIERS.md) |
+| Wix Stores Versioning (V1/V3) | [STORES_VERSIONING.md](references/STORES_VERSIONING.md) |
+| Official Documentation Links | [DOCUMENTATION.md](references/DOCUMENTATION.md) |
+
+---
+
+## Data Collection Inference
+
+**CRITICAL:** Data collections are often needed implicitly — don't wait for the user to explicitly say "create a CMS collection." Infer the need automatically.
+
+**Skip this section if the user provides a collection ID directly** (e.g., an existing site-level collection). In that case, use the provided ID as-is — no Data Collection extension or namespace scoping needed.
+
+**Always include a Data Collection extension when ANY of these are true:**
+
+| Indicator | Example |
+| --- | --- |
+| User mentions saving/storing/persisting app-specific data | "save the fee amount", "store product recommendations" |
+| A dashboard page will **manage** (CRUD) domain entities | "dashboard to manage fees", "admin page to edit rules" |
+| A service plugin reads app-configured data at runtime | "fetch fee rules at checkout", "look up shipping rates" |
+| User mentions "dedicated database/collection" | "save in a dedicated database collection" |
+| Multiple extensions reference the same custom data | Dashboard manages fees + service plugin reads fees |
+
+**Why this matters:** Without the Data Collection extension, the collection won't be created when the app is installed, the Wix Data APIs may not work (code editor not enabled), and collection IDs won't be properly scoped to the app namespace.
+
+**If data collection is inferred, follow the [App Namespace Requirement](#app-namespace-requirement) to obtain the namespace before proceeding.**
+
+### App Namespace Requirement
+
+When creating a Data Collection, you MUST ask the user for their app namespace from Wix Dev Center. This is a required parameter that must be obtained from the user's Dev Center dashboard and cannot be recommended or guessed.
+
+If the user hasn't provided their app namespace, read [APP_IDENTIFIERS.md](references/APP_IDENTIFIERS.md) and give the user the instructions to obtain it.
+
+### Collection ID Coordination
+
+**Applies ONLY when a Data Collection extension is being created.** If the user provides a collection ID directly, use it as-is — no namespace scoping, no Data Collection extension needed.
+
+When a Data Collection is created alongside other extensions that reference the same collections:
+
+1. **Get the app namespace** (see App Namespace Requirement above)
+2. **Determine the `idSuffix`** for each collection (the Data Collection reference documents the full ID format)
+3. **Use the full scoped collection ID** (`<app-namespace>/<idSuffix>`) in all extensions that reference the collection via Wix Data API calls
+
+---
+
+## Wix Stores Versioning Requirement
+
+**Applies when ANY Wix Stores API is used** (products, inventory, orders, etc.):
+
+1. **Read the Stores Versioning reference** — see [STORES_VERSIONING.md](references/STORES_VERSIONING.md). It contains the module map, permissions cheatsheet, copy-paste dual-catalog recipes (list/get/create/update/delete products, inventory, categories), the V1→V3 field map, webhook mapping, and the major V3 gotchas. **Use it before searching SDK docs** — it covers the common 80%.
+2. **All Stores operations must check catalog version first** using `getCatalogVersion()`
+3. **Use the correct module** based on version: `productsV3` (V3) vs `products` (V1)
+4. **Apps MUST support both V1 and V3** — single-version apps cannot list in the App Market and break on new sites
+5. **Request both V1 and V3 permission scopes** for every Stores operation
+
+This is non-negotiable — V1 and V3 are NOT backwards compatible.
+
+---
+
+## App Market Review
+
+**Applies when a user wants to submit their app to the Wix App Market, list it publicly, prepare for App Market review, audit decline risk, or fix App Market review feedback.** Not needed for private apps or routine version releases.
+
+Read [APP_MARKET_REVIEW.md](references/APP_MARKET_REVIEW.md) — it contains the full technical checklist, implementation notes with Wix doc links, and the review taxonomy IDs for traceability.
+
+---
+
+## Implementation Workflow
+
+### Step 1: Ask Clarifying Questions (if needed)
+
+Only ask for configuration values when **absolutely necessary** for the implementation to proceed. If a value can be configured later or added as a manual step, don't block on it.
+
+If unclear on approach (placement, visibility, configuration, integration), ask clarifying questions. If the answer could change the extension type, wait for the response before proceeding. Otherwise, proceed with the best-fit extension type.
+
+### Step 2: Make Your Recommendation
+
+Use the Extension Types Reference Table and decision content above. State extension type and brief reasoning (placement, functionality, integration).
+
+### Step 3: Read Extension Reference, Check API References, Then Discover (if needed)
+
+**Workflow: Read extension reference → Check API references → Use MCP only for gaps.**
+
+1. **Read the extension reference file** for the chosen extension type from the table above
+2. **Identify required APIs** from user requirements
+3. **Check relevant API reference files:**
+   - 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`
+4. **Verify the specific method/event exists** in references
+5. **ONLY use MCP discovery if NOT found** in reference files
+
+**Platform APIs (never discover - in references):**
+- Wix Data, Dashboard SDK, Event SDK (common events), Service Plugin SPIs
+
+**Vertical APIs (discover if needed):**
+- Wix Stores (**⚠️ MUST use Stores Versioning reference** — V1/V3 catalog check required), Wix Bookings, Wix Members, Wix Pricing Plans, third-party integrations
+
+**Decision table:**
+
+| User Requirement                     | Check References / Discovery Needed? | Reason / Reference File                             |
+| ------------------------------------ | ------------------------------------ | --------------------------------------------------- |
+| "Display store products"             | ✅ YES (MCP discovery)               | Wix Stores API — **include Stores Versioning reference** |
+| "Show booking calendar"              | ✅ YES (MCP discovery)               | Wix Bookings API not in reference files             |
+| "Send emails to users"               | ✅ YES (MCP discovery)               | Wix Triggered Emails not in reference files         |
+| "Get member info"                    | ✅ YES (MCP discovery)               | Wix Members API not in reference files              |
+| "Listen for cart events"             | Check `COMMON-EVENTS.md`             | MCP discovery only if event missing in reference    |
+| "Store data in collection"           | WIX_DATA.md ✅ Found                 | ❌ Skip discovery (covered by reference)             |
+| "Create CMS collections for my app"  | Data Collection reference            | ❌ Skip discovery (covered by dedicated reference)   |
+| "Show dashboard toast"               | DASHBOARD_API.md ✅ Found            | ❌ Skip discovery                                   |
+| "Show toast / navigate"              | DASHBOARD_API.md ✅ Found            | ❌ Skip discovery                                   |
+| "UI only (forms, inputs)"            | N/A (no external API)                | ❌ Skip discovery                                   |
+| "Settings page with form inputs"     | N/A (UI only, no external API)       | ❌ Skip discovery                                   |
+| "Dashboard page with local state"    | N/A (no external API)                | ❌ Skip discovery                                   |
+
+**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)
+
+### Step 4: Implement Extensions
+
+Follow the extension reference file to implement each extension. Key rules:
+
+- ⚠️ 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)).
+
+### Step 5: Run Validation
+
+After all implementation is complete, you MUST run validation. See [APP_VALIDATION.md](references/APP_VALIDATION.md) for the complete validation workflow:
+
+1. Package installation (detect package manager, run install)
+2. TypeScript compilation check (`npx tsc --noEmit`)
+3. Build validation (`npx wix build`)
+4. Preview deployment (`npx wix preview`)
+
+**Do NOT report completion to the user until validation passes.**
+
+If validation fails, fix the errors and re-validate until it passes.
+
+### Step 6: Report Completion
+
+Only after validation passes, provide a **concise summary section** at the top of your response:
+
+```markdown
+## ✅ Implementation Complete
+
+[1-2 sentence description of what was built]
+
+**Extensions Created:**
+- [Extension 1 Name] - [Brief purpose]
+- [Extension 2 Name] - [Brief purpose]
+
+**Build Status:**
+- ✅ Dependencies: [Installed / status message]
+- ✅ TypeScript: [No compilation errors / status]
+- ✅ Build: [Completed successfully / status]
+- ✅/⚠️ Preview: [Running at URL / Failed - reason]
+
+**⚠️ IMPORTANT: [X] manual step(s) required to complete setup** (see "Manual Steps Required" section below)
+```
+
+- If there are NO manual steps, state: "✅ No manual steps required — you're ready to go!"
+
+### Step 7: Surface Manual Action Items
+
+Present any manual steps the user must perform (e.g., configuring settings in the Wix dashboard, enabling permissions, setting up external services).
+
+**Format:**
+
+```markdown
+## 🔧 Manual Steps Required
+
+The following actions need to be done manually by you:
+
+### 1. [Action Category/Title]
+[Detailed description with specific instructions]
+
+### 2. [Action Category/Title]
+[Detailed description]
+```
+
+---
+
+## 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.
+
+---
+
+## Validation
+
+Execute these steps sequentially after all implementation is complete. See [APP_VALIDATION.md](references/APP_VALIDATION.md) for the complete guide.
+
+1. **Package Installation** — Detect package manager, run install
+2. **TypeScript Compilation** — `npx tsc --noEmit`
+3. **Build** — `npx wix build`
+4. **Preview** — `npx wix preview`
+
+Stop and report errors if any step fails. Check `.wix/debug.log` on failures.
+
+---
+
+## Cost Optimization
+
+- **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
+- **Invoke wix-design-system** first when using WDS (prevents import errors)
+
+## Documentation
+
+For links to official Wix CLI documentation for all extension types, see [DOCUMENTATION.md](references/DOCUMENTATION.md).

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

@@ -0,0 +1,35 @@
+# App Identifiers
+
+How to obtain required app identifiers from Wix Dev Center.
+
+## App Namespace
+
+Required when creating **Data Collections**. Scopes collection IDs to prevent conflicts between apps.
+
+### First, check if you already have an app namespace:
+1. Go to [Wix Dev Center](https://manage.wix.com/studio/custom-apps/)
+2. Open your app dashboard
+3. Click the three dots (...) menu button in the top-right corner (next to "Test App" button)
+4. Select "View ID & keys" from the dropdown menu
+5. In the modal that opens, scroll to the bottom to find the "Namespace" field
+6. If you see a Namespace value, copy it
+
+### If there is no app namespace, create one:
+1. Go to [Wix Dev Center](https://manage.wix.com/studio/custom-apps/)
+2. Select your app
+3. In the left menu, select **Develop > Extensions**
+4. Click **+ Create Extension** and find the **Data Collections** extension
+5. Click **+ Create**
+6. You will be prompted to create an app namespace - follow the prompts to set it up
+
+## Code Identifier
+
+Required when creating **Editor React components**. Used as the type prefix for Editor React component extensions (e.g. `type: '<CODE_IDENTIFIER>.ComponentName'`). Every Wix app has one automatically — there is no need to create it.
+
+### How to get the Code Identifier:
+1. Go to [Wix Dev Center](https://manage.wix.com/studio/custom-apps/)
+2. Open your app dashboard
+3. Click the three dots (...) menu button in the top-right corner (next to "Test App" button)
+4. Select "View ID & keys" from the dropdown menu
+5. In the modal that opens, find the "Code Identifier" field
+6. Copy the Code Identifier value