> 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: Introduction

## Article: Introduction

## Article Link: https://dev.wix.com/docs/api-reference/app-management/app-skills/introduction.md

## Article Content:

# About the App Skills API

The App Skills API retrieves the skills that apps declare for AI agents working on a Wix site, such as [Aria](https://dev.wix.com/docs/overview/ai-the-wix-platform/about-aria.md). A skill packages the know-how for one job: what the job is, when it applies, the step-by-step guidelines an agent follows while doing it, and which of the app's own [App Tools](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/app-tools/about-app-tools-extensions.md) it may call along the way.

An app declares its skills in the app dashboard as an App Skills extension. The API serves those declarations for the apps installed on a site: [List App Skills](https://dev.wix.com/docs/api-reference/app-management/app-skills/list-app-skills.md) returns the site's catalog of skills, and [Get App Skill](https://dev.wix.com/docs/api-reference/app-management/app-skills/get-app-skill.md) returns one skill with its guidelines. For how to declare skills, see [App Skills Extension Config](https://dev.wix.com/docs/api-reference/app-management/app-skills/app-skills-extension-config.md).

## How agents use skills

An agent works in two steps:

1. Browse: the agent calls [List App Skills](https://dev.wix.com/docs/api-reference/app-management/app-skills/list-app-skills.md) to retrieve every activated skill of the apps installed on the site. The list carries the fields an agent chooses a skill by, such as the display name, description, tags and example requests, but not the guidelines, so it stays small.
2. Run: when the user picks a skill or a request matches one, the agent calls [Get App Skill](https://dev.wix.com/docs/api-reference/app-management/app-skills/get-app-skill.md) to load the skill's guidelines, follows them, and calls the app's tools with [Invoke Tool](https://dev.wix.com/docs/api-reference/app-management/app-tools/tools-host/invoke-tool.md) from the Tools Host API.

For a ready-made agent recipe that covers the whole workflow, from listing the site's skills and tools to running the chosen skill's tools, see [Use App Skills and App Tools](https://dev.wix.com/docs/api-reference/app-management/app-tools/skills/use-app-skills-and-app-tools.md).

## How skills reach a site

Skills aren't stored by this API. Both methods read the declarations of the apps installed on the site, at the app version each site is on, so a change to a skill reaches a site when that site moves to the app version that contains it. Uninstalling the app or deactivating the skill removes it from the next read.

A skill's ID is derived from the app ID and the skill's slug, so a skill keeps the same ID on every site and across app versions.

## Handling APP_SKILL_NOT_FOUND

[Get App Skill](https://dev.wix.com/docs/api-reference/app-management/app-skills/get-app-skill.md) returns `APP_SKILL_NOT_FOUND` when the skill the agent chose is no longer valid for the site: the app was uninstalled, the skill was deactivated or removed in a newer app version, or the call carries no site context. Treat it as "list again and choose again", not as an error to show the user verbatim.

## Keep a skill's scope

Guidelines are written by the app's developer and are subject to a safety check when saved, but they remain third-party instructions. An agent should follow them for the skill's job only, call only the tools the skill lists, and keep its own rules above them.

## Before you begin

It’s important to note the following points before starting to code:

- The site is determined by the call's identity, not by a parameter. Call the API with an identity that is bound to the site: an app instance token of an app installed on the site, or an API key together with the `wix-site-id` header. For details, see [About Identities](https://dev.wix.com/docs/overview/auth-permissions/identities.md).
- A call with no site context returns an empty list from [List App Skills](https://dev.wix.com/docs/api-reference/app-management/app-skills/list-app-skills.md) and `APP_SKILL_NOT_FOUND` from [Get App Skill](https://dev.wix.com/docs/api-reference/app-management/app-skills/get-app-skill.md).
- Skills are only as useful as the tools behind them. Declare the tools first in the App Tools extension, then write skills that use them.
- A skill's guidelines and description are subject to a safety check when the extension is saved. Content that tries to override the agent's rules, reach tools outside the app, or collect data the skill doesn't need is rejected. See [Writing Skill Guidelines](https://dev.wix.com/docs/api-reference/app-management/app-skills/writing-skill-guidelines.md).

## Use cases

- [Track a package with an app skill](https://dev.wix.com/docs/api-reference/app-management/app-skills/sample-flows.md#track-a-package-with-an-app-skill)
- [Quote a price for a customer abroad](https://dev.wix.com/docs/api-reference/app-management/app-skills/sample-flows.md#quote-a-price-for-a-customer-abroad)

## Terminology

- Skill: one job an app teaches agents to do. A skill has a slug, a display name, a description, guidelines, and the names of the app's tools it may use.
  - Guidelines: the instructions an agent follows once the skill is chosen, in Markdown. Returned only by Get App Skill.
  - Tool method names: `methodName` values from the app's App Tools extension. A skill may only reference tools its own app declares.
  - Tags and examples: keywords and sample user requests. Agents use them to decide which skill fits a request.
- Skill ID: derived from the app ID and the slug, so a skill keeps the same ID on every site and across app versions.
- App Skills extension: the part of an app's configuration in the app dashboard where its skills are declared. An app has one.
- App Tools extension: where an app declares the tools agents can run. Skills reference these tools by method name.

## See also

- [Sample Flows](https://dev.wix.com/docs/api-reference/app-management/app-skills/sample-flows.md)
- [App Skills Extension Config](https://dev.wix.com/docs/api-reference/app-management/app-skills/app-skills-extension-config.md)
- [Writing Skill Guidelines](https://dev.wix.com/docs/api-reference/app-management/app-skills/writing-skill-guidelines.md)
- [Tools Host API](https://dev.wix.com/docs/api-reference/app-management/app-tools/tools-host/introduction.md)
- [Use App Skills and App Tools](https://dev.wix.com/docs/api-reference/app-management/app-tools/skills/use-app-skills-and-app-tools.md): an agent recipe for listing skills, reading one, and running its tools
- [About App Tools extensions](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/app-tools/about-app-tools-extensions.md)

@sdk_package_setup