Skills

The Skills module is the catalog of the Skills your organization approves for use by its agents. Each Skill has a stable identity — the name an agent installs it by — and a set of versions, each with its own content package and its own state in the lifecycle.

The split between the two is the heart of the module: the Skill is what the agent asks for, and the version is what it gets. Only the versions you publish are available for consumption; the rest exist here alone, for the people who catalog and review them.

NOTE

A newly catalogued Skill starts at version 1.0.0 in Draft and is not available to any agent. It becomes available once a version reaches Published — see Lifecycle.

Quick links

Learn how to:

• Filter and list the Skills
• Catalog a Skill
• View a Skill
• Edit a Skill
• Work with versions
• Understand the lifecycle
• Review the security findings
• Delete a Skill
• Check the form fields
• Consume the Skills from an agent
• Check the permissions

Listing

The Skills page lists the catalogued Skills with pagination. You can filter by:

• Keywords (optional): searches by name or description.
• Lifecycle status (optional): the version's lifecycle state. All statuses removes the filter.
• Owner (optional): who answers for the Skill. Accepts more than one value.
• Tags (optional): the tags assigned to the Skill. Accepts more than one value.

Use Search to apply the filters and Clear to reset them.

Columns in the table:

• Name: the Skill's name — the same directory the agent installs it into.
• Owner: the user or group responsible for it.
• Tags: the tags assigned. When there are none, the column shows No tags.
• Latest: the highest version available for consumption. When no version is available, it shows Not published.
• Actions: the View and Delete Skill icons on each row, each shown according to the user's permission — see Permissions.

Catalog a Skill

THE PACKAGE AND THE NAME MUST AGREE

The package needs YAML frontmatter with name and description, and the name declared there must match the Skill's name. In a .zip archive, that frontmatter is read from the SKILL.md at the root.

View a Skill

Click the View icon on the Skill's row. The Skill overview screen has two tabs:

• General info: the Skill's stable identity — what does not change from one version to the next.
• Versions: every version, the content of each one and the lifecycle — see Versions.

The General info tab shows:

Edit a Skill

On the General info tab, click Edit, change the fields and click Save.

THE NAME DOES NOT CHANGE

The name is the Skill's identity: it is the directory the Skill installs into on the consumer's machine, and the API has no field to change it. Description, owner and tags can be edited at any time; the name cannot.

Versions

The Versions tab lists every version of the Skill, under the Version, Lifecycle and Updated columns. Select a version to see its content.

For the selected version, the screen shows:

• What changed: the description given by whoever opened the version.
• Skill files: the files inside the package, with Path, Media type and Size. Click Preview to read a text file without downloading it — files that are not text show a notice and have to be downloaded.
• Download package: downloads the version's complete package.
• Security findings: the findings from the package check — see Security findings.
• Technical details: Version ID, the package Digest (Not built yet while no content has been uploaded), Derived from (when the version came from another one) and the dates.
• Transition history: the record of status changes, with From, To, Actor, At and Reason.

Open a new version

Click Open new version. The form starts from the highest existing version and computes the new number from the increment you pick:

What changed is required: the reviewer reads it before approving and the consumer before upgrading. An increment that would land on a number that already exists is refused — pick another one.

The new version starts in Draft, with no content; upload the package from the same tab.

Resume a retired version

A version in Retired never reopens. To carry on from it, select it and click Resume from here: a new version is created in Draft pointing back at the retired one under Derived from. The number is still computed from the Skill's highest version, not from the retired one.

Lifecycle

Every version runs through a state machine of its own. The Change status button offers only the destinations the service accepts from the current state; View workflow opens the full diagram, highlighting the current status and the paths available from it.

When you pick a destination, the screen states the consequence before you confirm — including the effect on the Skill's Latest, which may move to another version or cease to exist.

Reason is optional on most transitions and required when rejecting a version under review.

DEPRECATED IS STILL CONSUMABLE

Deprecated does not take the version out of circulation: it is still delivered to anyone who asks for it, carrying the migration warning. To stop delivering it, use Unpublished or Retired.

Security findings

Each version shows the findings of the check applied to its package, under Security findings, graded Critical, High, Medium and Low. Use the Severity selector to filter — All shows every one.

A finding may belong to a specific file or to the package as a whole, in which case it is marked Package-level check. When the package passes every check, the section shows No findings.

Findings are informative: they do not block a transition. Deciding whether to approve or publish a version that has findings belongs to whoever holds the permission to do it.

Delete a Skill

Click the Delete Skill icon on the Skill's row and confirm. Deleting removes the Skill and every version under it, and cannot be undone.

A SKILL IN USE IS NOT DELETED

While a version is available for consumption — Published or Deprecated — deletion is blocked, and the screen names the version standing in the way. Move that version to Unpublished or Retired before deleting the Skill.

Form fields

Consume the Skills from an agent

Publishing a version makes it available, but it is the agent that fetches it: nothing is pushed to any machine. The agent discovers the catalog, installs what it needs and, at the start of each session, checks what changed.

The recommended path is to expose the catalog as an MCP Server on the AI Gateway itself — the agent then talks to it through the protocol's tools, with no hand-written integration. The step-by-step is in MCP Servers.

Permissions

Access to each action of the Skills journey depends on its own permission. Without the matching permission, the screen element does not appear — the interface never shows an unavailable action as disabled.

Permissions are granted in Access Control, on the Roles screen, under the AI Gateway product. The table below lists each one exactly as Access Control displays it.

In the lifecycle, each transition requires the permission of its own group. The destination you pick is what decides the permission:

A control without its permission is not rendered; a Skill reached directly by URL without the matching permission lands on the AI Gateway's own access-denied screen, not Access Control's.

THE SEGREGATION IS DELIBERATE

Keeping Submit, Approve and Publish apart lets the person who writes a Skill not be the one who approves it, and the person who approves it not be the one who puts it into circulation. Holding all three in a single profile is possible, but it undoes the review by another person that the lifecycle exists to sustain.