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. 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 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 returns the site's catalog of skills, and Get App Skill returns one skill with its guidelines. For how to declare skills, see App Skills Extension Config.

How agents use skills

An agent works in two steps:

  1. Browse: the agent calls List App Skills 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 to load the skill's guidelines, follows them, and calls the app's tools with Invoke Tool 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.

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 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.
  • A call with no site context returns an empty list from List App Skills and APP_SKILL_NOT_FOUND from Get App Skill.
  • 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.

Use cases

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

Last updated: 6 October 2026

Did this help?