Skills

A skill is a SKILL.md file — instructions an agent loads when it needs them, rather than guidance you paste into every system prompt. Settings → Skills is where an organization's skills live: the platform catalog you can adopt from, the custom skills you write, and the version history an agent is pinned to. Open it with the Settings control in the top navigation bar, then choose Skills under Capabilities.

Each card carries the skill's validation verdict, its scope, its category and its tags — everything the library is browsed by.

Skills belong to an organization, not to the tenant

Unlike the governance areas, which are tenant-wide, this page is scoped to an organization. The library you are looking at is the library of the organization named in the header switcher, and adopting, authoring and pinning all happen inside it. Switch organizations in the header and the grid, the badge counts and the version banner all re-read for the new one.

That matters when you have more than one organization: the same platform skill can be adopted by several, and removing it from one leaves the others untouched.

The three tabs

Library holds both kinds, and the control on each card says which: a skill this organization wrote is Deleted, an adopted platform skill is Removed from org.

The badge on each tab counts the whole tab, not the filtered view, so the grid under a badge can legitimately show fewer cards than the number claims once you type in the search box or pick a category.

Search matches name, description and tags. The category chips — Documents, Engineering, Operations, Support, Data and Compliance — are the product's closed list; a skill always has exactly one.

The platform catalog

The platform ships six skills into every tenant — five attributed to the RAI platform library, and one, the deliberately unsafe slack-integration, to a Community catalog. All six are scanned by Platform trust & safety, which is the attribution on the safety panel rather than on the card. They are read-only: you can open one and read it, but the name, the body, the category and the tags are all disabled, and there is no version to roll back.

A platform skill opens with View rather than Edit — every field is disabled and the safety rail shows the platform's own scan.

One catalog entry, slack-integration, is deliberately unsafe: its body fetches an external URL, the validator flags it, and adoption is refused. It is there to demonstrate that the safety gate works. Its Add to org button is disabled, and so is the button on any skill that has never been published.

Adopt a platform skill

Adoption publishes nothing and moves no agent. It widens what this organization may attach — you still have to pin the skill to an agent for anything to change.

To reverse it, use Remove from org on the card. That drops the skill from this organization's library and detaches it from every agent in this organization; the platform skill itself is untouched and other organizations keep it.

Write a custom skill

The editor is a two-state document: Structured shows the parsed fields and sections, Raw shows the SKILL.md file itself. Both edit the same content, and the safety rail on the right shows the server's verdict on whichever version is on screen.

The three levels are a progressive-disclosure model: the metadata is always in the agent's prompt, the sections are fetched only when the agent reaches for the skill.

Validate safety runs the same scan without saving, so you can see what a change would do before committing it. The rail says "Unsaved preview — the stored verdict changes when you save" while you are looking at one.

The nine safety checks

Skills are instructions an agent follows, so a skill that reaches outside its own document can change behaviour after it was reviewed. That is the threat the scan is built around. Each check is a pass, a warning or a failure:

Those checks resolve to one of four statuses:

• Validated & safe — every check passed. Only this status can be published.
• Pending review — the three required checks passed, but something warned.
• Safety flagged — a check failed. A flagged platform skill cannot be adopted.
• Draft — never scanned. A scan never resolves to this, so it only ever means a skill nobody has validated yet.

Publishing and versions

Saving and publishing are different acts, and the difference is the whole versioning model.

Saving updates the draft. Publishing snapshots the saved draft as a numbered version — and moves nobody. An agent runs the version it was pinned to until someone deliberately moves it, so publishing a new version never changes what a configured agent does.

Every publish is listed with its author, its change note and the time — and every earlier version stays listed and resolvable.

Publish is offered only when the stored verdict is Validated & safe and there are no unsaved edits, because publishing snapshots the saved draft rather than what is on screen. The Unpublished changes badge in the header says when the draft has moved ahead of the published version.

Roll back

Roll back on an older version re-publishes that version's content as a new version. Nothing is deleted or renumbered — an agent pinned to any earlier number must still be able to resolve it — and agents already pinned do not move. Your unpublished draft is left alone. Roll back is disabled while the editor holds unsaved edits, because a rollback reloads the editor from the server's copy of the draft.

Rolling back is not available on a platform skill: your organization owns the pins but not the skill.

Force update

When agents in this organization are pinned to something older than the published version, the Versions tab shows a banner naming the count and a Force update control. Confirming moves every one of those agents onto the published version from its next beat. Agents in other organizations are not affected.

Re-pinning an agent to a different version is what changes what it runs. A rollback does not: it moves the library's current version, while every agent stays on the version it was pinned to.

Attaching a skill to an agent

Skills are authored here and attached on the project Team pane — open an agent and use its Skills & Tools tab.

Each pin carries the version it was attached at. v2 and v1 here are two different snapshots of two different skills, not a sequence.

The picker offers only skills in this organization's library that have a published version — an unpublished skill cannot be attached. An agent may hold at most 50 pins.

When the library moves ahead of a pin, the row offers a control to move that one agent onto the published version; Force update in the Versions tab does the same thing for every agent at once.

Delete a custom skill

Delete sits in the editor header and on the card in the grid. Before you can confirm, the dialog reads how many agents in this organization are pinned to the skill and says so — that number is the whole question. The skill is then detached from every agent in this organization.

The version history is kept, so an agent that is still pinned goes on resolving the version it was pinned to. It cannot be attached again, though: the attach picker offers only skills that are not deleted, and there is no restore.

A platform skill has no Delete, only Remove from org.

Field reference

Troubleshooting

Related