When you add an App Skills extension to a Wix CLI or Wix-managed headless project, the CLI adds the following file to your project:
<your-extension-name>.extension.ts: The App Skills builder, which declares the skills your app offers to Aria, the Wix AI assistant.The CLI creates the file in the following default folder structure:
The CLI also registers the extension in src/extensions.ts, the entry point that lists every extension in your app. If you don't pass an extension to app().use(), it isn't part of your app:
You can move the file anywhere inside the src/ folder as long as you update its path in src/extensions.ts.
An app can have only 1 App Skills extension. To add more skills, add them to the skills array of the existing extension instead of generating a second extension.
The <your-extension-name>.extension.ts file declares the skills your app offers to Aria. After you build and release your app, Aria uses these declarations to discover which skills exist and decide when to use each one:
The extension has these top-level fields:
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Auto-generated UUID that uniquely identifies this extension. |
name | string | Yes | Name of the extension. |
skills | array | Yes | Array of skill declarations. Min: 1. Max: 100. |
Each object in skills has these fields:
| Field | Type | Required | Description |
|---|---|---|---|
slug | string | Yes | Unique identifier of the skill. Agents use it to refer to the skill they chose. Use lowercase words separated by hyphens, such as package-tracking. Max: 64 characters. |
displayName | string | No | Name shown to Wix users when they browse the site's skills. Min: 2. Max: 200 characters. |
description | string | Yes | What the skill does and when to use it. Agents decide whether a request fits the skill from this text. Min: 10. Max: 1,024 characters. |
guidelines | string | When activated is true | Instructions the agent follows after it chooses the skill, written in Markdown. Max: 20,000 characters. |
toolMethodNames | array of strings | No | The methodName of the App Tools your skill may call. Each name must exist in your App Tools extension. Max: 50, each 1 to 30 characters. |
activated | boolean | No | Whether agents can use the skill. Set to true to enable it. |
tags | array of strings | No | Lowercase keywords for agents that pick skills by topic. Max: 10, each 1 to 30 characters. |
examples | array of strings | No | Example Wix user requests the skill handles. This is the strongest signal an agent has when it matches a request to a skill. Max: 5, each 1 to 200 characters. |
inputModes | array of strings | No | MIME types, the standard labels for content formats such as text/plain, that the skill accepts as input. Leave empty to accept any input. Max: 10, each 3 to 100 characters. |
outputModes | array of strings | No | MIME types the skill produces, such as application/json. Leave empty to produce whatever the agent produces. Max: 10, each 3 to 100 characters. |
In Wix-managed projects, a skill can list the App Tools it may call to perform a task, in toolMethodNames. In the skill's guidelines tell Aria when to invoke each tool, what to collect from the Wix user first, and what to do with the result. A skill can list only the tools your app exposes in its App Tools extension. Each name in toolMethodNames must match a methodName in that extension.
Note: A Studio Two site declares skills without tools. The Studio Two skill schema has no toolMethodNames field.
Releasing a project with an invalid App Skills declaration can fail for the following reasons:
| Cause | Fix |
|---|---|
In a Wix-managed project, a skill's toolMethodNames includes a tool that your App Tools extension doesn't declare. | Add the tool to your App Tools extension, or remove it from toolMethodNames. |
A skill has activated set to true but no guidelines. | Add guidelines, or set activated to false until they're ready. |
A skill's guidelines or description fails the safety check. The check rejects text that tries to override the agent's rules, reach tools outside your app, collect data the skill doesn't need, hide instructions, or deceive Wix users. | Rephrase the text so it only describes how to do the job with your app's tools. |
| Your project already has an App Skills extension. | Add the skill to the skills array of the existing extension. |
Last updated: 2 November 2026