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 file uses the following schema:
Here's an example file with a single skill declaration. The skill uses a getPackageTracking tool from the app's App Tools extension:
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 | Identifier of the skill, unique within your app. 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 values of the App Tools your skill may call. Each name must exist in your App Tools extension. A skill without tools is allowed, such as a checklist skill. Max: 50 names, 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. |
A skill can list only the tools your app exposes in its App Tools extension. Before you list tool names in an App Skill, make sure you set up the configuration for the App Tools extension and its Tools Provider service plugin.
Releasing a project with an invalid App Skills declaration can fail for the following reasons:
| Cause | Fix |
|---|---|
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 app already has an App Skills extension. | Add the skill to the skills array of the existing extension. |
After you release your app version and a site installs it, the skill appears in that site's List App Skills response. The Get App Skill method returns the skill's guidelines. Each site sees the skills from the app version it's on, so a change reaches a site when that site moves to the new version.
Last updated: 2 November 2026