> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: App Skills Extension Files and Code

## Article: App Skills Extension Files and Code

## Article Link: https://dev.wix.com/docs/go-headless/wix-managed-headless/full-integration-astro/extensions/backend/app-skills/app-skills-extension-files-and-code.md

## Article Content:

# App Skills Extension Files and Code

When you add an [App Skills](https://dev.wix.com/docs/overview/extensions-framework/backend-extensions/app-skills.md) 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](#app-skills-builder), which declares the skills your app offers to [Aria](https://dev.wix.com/docs/overview/ai-the-wix-platform/about-aria.md), the Wix AI assistant.

The CLI creates the file in the following default folder structure:

```bash
src/
  └── extensions/
      └── backend/
          └── app-skills/
              └── <your-extension-name>/
                  └── <your-extension-name>.extension.ts
```

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:

```typescript
import { app } from '@wix/astro/builders';

import shippingSkills from './extensions/backend/app-skills/shipping-skills/shipping-skills.extension.ts';

export default app().use(shippingSkills);
```

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.

## App Skills builder

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:

```typescript
import { extensions } from '@wix/astro/builders';

export default extensions.appSkills({
  id: string,       // Auto-generated UUID. Don't change this manually.
  name: string,     // Name of the extension.
  skills: [         // Array of skill declarations. Min 1, max 100.
    {
      slug: string,                 // Required. Unique identifier for this skill.
      displayName: string,          // Optional. Name shown to users.
      description: string,          // Required. Used by agents to decide when to use the skill.
      guidelines: string,           // Required when activated is true. Instructions in Markdown.
      toolMethodNames: string[],    // Optional. App Tools the skill may call.
      activated: boolean,           // Optional. Whether agents can use this skill.
      tags: string[],               // Optional. Keywords for choosing skills by topic.
      examples: string[],           // Optional. Example Wix user requests.
      inputModes: string[],         // Optional. MIME types the skill accepts.
      outputModes: string[]         // Optional. MIME types the skill produces.
    }
  ]
});
```

Here's an example file with a single skill declaration. The skill uses a `getPackageTracking` tool from the app's App Tools extension:

```typescript
import { extensions } from '@wix/astro/builders';

export default extensions.appSkills({
  id: '<generated-by-the-cli>',
  name: 'shipping-skills',
  skills: [
    {
      slug: 'package-tracking',
      displayName: 'Package tracking',
      description:
        'Answers questions about where a shipment is and when it will arrive. ' +
        'Use when the user asks about the status, location, or delivery date of an order or package.',
      guidelines:
        '# Package tracking\n\n' +
        '1. Ask for the carrier tracking number if the user has not given one.\n' +
        '2. Call `getPackageTracking` with the tracking number exactly as the user wrote it.\n' +
        '3. Report the status, the last known location, and the estimated delivery date.\n\n' +
        'Do not use this skill to place, change, or cancel orders.',
      toolMethodNames: ['getPackageTracking'],
      tags: ['shipping', 'delivery status'],
      examples: ['Where is my package?', 'When will order #4521 arrive?'],
      activated: true
    }
  ]
});
```

### App Skills extension configuration

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. |

## Use tools in a skill

A skill can list only the tools your app exposes in its [App Tools](https://dev.wix.com/docs/overview/extensions-framework/backend-extensions/app-tools.md) 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.

## Common errors

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. |

## How skills reach agents

After you release your app version and a site installs it, the skill appears in that site's [List App Skills](https://dev.wix.com/docs/api-reference/app-management/app-skills/list-app-skills.md) response. The [Get App Skill](https://dev.wix.com/docs/api-reference/app-management/app-skills/get-app-skill.md) 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.

## See also

- [App Skills](https://dev.wix.com/docs/overview/extensions-framework/backend-extensions/app-skills.md)
- [App Skills Extension Config](https://dev.wix.com/docs/api-reference/app-management/app-skills/app-skills-extension-config.md)
- [About the App Skills API](https://dev.wix.com/docs/api-reference/app-management/app-skills/introduction.md)
- [Add App Tools Extensions with the Wix CLI](https://dev.wix.com/docs/go-headless/wix-managed-headless/full-integration-astro/extensions/backend/app-tools/add-app-tools-extensions-with-the-wix-cli.md)