Skip to main content

Skill Registry

The Skill Registry is where you register Agent Skills — reusable instruction bundles that teach an agent how to do something, written in the open SKILL.md format. A skill packages a set of instructions (and optional reference files and scripts) under a name and description. You attach skills to Agent Personas, and the agents connecting to those personas discover and load them on demand — pulling in the detailed guidance only when a task actually calls for it.

Think of tools as what an agent can do, and skills as how to do it well. A persona might have GitHub and Jira tools; a "release notes" skill tells the agent the exact steps, tone, and format your team expects when it turns merged pull requests into a changelog.

Quick Start: What do you want to do?​

I want to...Jump to
Understand what a skill is and when to use oneWhat is a skill?
Add my first skillCreating a skill
Understand the SKILL.md formatThe SKILL.md format
Add reference files or scriptsManaging skill files
Undo a change to a skillVersions
Start a new skill from an existing oneCloning a skill
Control who can use a skillWho can use a skill
Attach a skill to an agentAttaching skills to a persona
Understand how agents use skillsHow agents use skills

What Is a Skill?​

A skill is a named, reusable piece of know-how you register once and reuse across many agents. Each skill contains:

  • Instructions — the main body of the skill: a step-by-step playbook, a response style, escalation rules, formatting conventions, or any procedural guidance you want agents to follow.
  • References (optional) — supporting documents (for example a style guide or a checklist) the agent can read alongside the instructions.
  • Scripts (optional) — helper scripts the agent may run if its client supports it. The gateway stores and serves scripts but never runs them itself.

Skills follow the SKILL.md standard: a Markdown file with a short YAML header (the skill's name and description) followed by the instructions.

Why use skills instead of putting everything in the persona description?

  • Reuse. Write a runbook once and attach it to every persona that needs it.
  • Consistency. Every agent using the skill follows the same steps, tone, and rules.
  • Load on demand. Agents only pull in a skill's full instructions when a task matches — so a persona can offer many skills without overwhelming the agent up front.
  • Governance. Skills live in one reviewed catalog, and only the personas you attach them to can use them.

Use Cases​

A repeatable runbook​

Capture a multi-step process so any agent performs it the same way every time.

Example: "Incident Triage"

  • Instructions: how to classify severity, which channels to post to, when to page on-call, and what a status update should contain.
  • Attach it to an SRE persona that has PagerDuty, Slack, and Jira tools.

A house style or output format​

Enforce a consistent voice and structure for anything an agent writes.

Example: "Release Notes Style"

  • Instructions: the sections, tone, and Markdown format your changelog uses.
  • Reference: an example release-notes page.
  • Attach it to a persona with GitHub and Confluence tools.

A domain playbook​

Give a general-purpose agent expert guidance for a specific domain.

Example: "SQL Investigation"

  • Instructions: how to explore a schema, safe query practices, and how to summarize findings.
  • Script: a helper query the agent can run in a supported client.
  • Attach it to a data-analytics persona.

Creating a Skill​

  1. Select Skill Registry in the sidebar.
  2. Select Add Skill.

The Add Skill dialog opens. You can create a skill in three ways:

OptionHow it works
Paste SKILL.mdType or paste your SKILL.md content directly into the editor. This is the quickest way to start.
Upload SKILL.mdSelect a single .md file from your computer.
Upload folderSelect a folder laid out in the standard structure below. Any references/ and scripts/ files are bundled into the skill automatically.

The expected folder layout is:

my-skill/
SKILL.md — required (name, description, and instructions)
references/ — optional supporting documents
scripts/ — optional helper scripts
  1. Add Labels (optional) — comma-separated keywords such as engineering, security, data that make the skill easier to find later.
  2. Under Visibility, choose who the skill reaches — see Who can use a skill. If you don't manage the skill catalog, this choice isn't offered and your skill is private to you.
  3. Select Create.
note

A skill's name and description come from the YAML header at the top of the SKILL.md content. To change them later, select Edit details on the skill's card — or edit the SKILL.md header directly.


The SKILL.md Format​

A SKILL.md file has two parts: a short YAML header and the instructions body.

---
name: release-notes-style
description: How to turn merged pull requests into a changelog entry.
---

# Release notes

When asked to draft release notes:

1. Group changes into Features, Fixes, and Breaking changes.
2. Write each entry as a single sentence in past tense.
3. Link the pull request number at the end of each line.
4. Keep the tone factual — no marketing language.
  • name and description (in the header) are what appear in the registry and in the list an agent sees. Write the description so an agent can tell when to use the skill.
  • Everything below the header becomes the instructions the agent loads when it activates the skill.

Skills in use are protected

You can't delete a skill while it's attached to a persona. Detach it from every persona first. This prevents accidentally pulling a skill out from under an agent that depends on it.


Who Can Use a Skill​

Not every skill belongs in front of the whole company. A private scratch playbook, a finance runbook, a support escalation guide meant for everyone — each has a different audience, and you choose it on the skill itself.

Every skill has one of three audiences:

AudienceWho can see and use it
PrivateOnly you and administrators.
Shared with specific teamsOnly members of the teams you choose.
Shared with everyoneAnyone in your organization.

The registry groups skills under Private and Shared headings, each with a count, so you can see at a glance who each one reaches. Opening a skill spells it out in a sentence under Access — Only you can use this skill, Everyone can use this skill, or the teams by name, as in team-IJ and test1memberTeam can use this skill — with a line underneath saying what that means in practice (Members of these teams have access. No one else does.).

Choosing the audience when you create a skill​

In the Add Skill dialog, Visibility offers two cards:

  • Private — Only you and admins can see and use this skill.
  • Shared — People in your organization can see and use it.

Choose Shared and a second question appears, Who can use this skill?:

  • Everyone in your organization
  • Specific teams — pick the teams from the Select teams list. You must choose at least one team; leaving it empty means the whole organization, which is a different answer.

Changing the audience later​

  1. Select the skill in the registry to open its detail panel.

  2. Next to Access, select Give access (on a private skill) or Change access (on one that's already shared).

  3. In Who can use this skill?, choose one of three:

    ChoiceWhat it does
    Only youTakes the skill back to private.
    Specific teamsPick from All teams; the ones it already reaches are listed under Assigned.
    Everyone in your organizationOpens it to the whole organization.
  4. Confirm. The button names what you chose — Limit to you, Give these teams access, or Give everyone access.

The dialog warns you before anything narrows or widens: choosing Only you on a skill two teams share says 2 teams will lose access. Only you will be able to use this skill.

Giving everyone access replaces team access

If a skill is shared with specific teams and you switch it to everyone, the dialog warns that all teams with access today will be replaced by organization-wide access. The teams aren't kept alongside — the skill simply becomes available to the whole organization.

Who can share a skill​

Sharing is an administrator decision. If you manage the skill catalog, you choose any audience, for your own skills and everyone else's. If you don't, you can still write and edit your own skills, but they stay private — the Add Skill dialog tells you This skill is private — only you and your administrators can see it. An administrator can share it later.

You can always edit a skill you created, private or shared. Skills you can't see don't appear in the registry at all.

Finding the skills that are yours​

The registry's toggle above the list splits skills two ways:

  • Available to me — skills you can connect an AI agent to.
  • Managed by me — administrators see every skill in the organization and decide who can connect; everyone else sees the skills they created and can edit.

Each shows a count, and a creator filter narrows the list further when several people have been writing skills. Agent Personas has the same pair of views.


Managing Skill Files​

Selecting a skill opens its detail panel with a file browser containing the SKILL.md file and the optional references/ and scripts/ folders.

Editing the name and description​

Select Edit details on the skill's card, change the Name or Description, and select Apply. A name is required. Personas that already use the skill pick up the change automatically.

Editing the instructions​

  • Open SKILL.md and select Edit SKILL.md to change the header (name/description) or the instructions body.
  • Toggle between Rendered and Raw to preview the Markdown or see the source.

Adding references and scripts​

Use the Add file menu in the file browser:

  • Add reference — a supporting document (for example guide.md). Give it a file name and content.
  • Add script — a helper script. Provide a file name, its language (for example python), and the content.

You can edit, replace, download, or delete any file from the browser.

Scripts are never run by the gateway

Scripts are stored and delivered to agents as text. The AI Gateway does not execute them. Whether a script runs is entirely up to the agent's client — and only if that client supports skill-script execution. If yours doesn't, agents rely on the instructions and references instead.

Editing a skill that's already attached​

You can edit a skill's instructions, references, and scripts even while it's attached to personas. Your changes are picked up automatically — the agents using it get the updated content the next time they load the skill, with no need to re-attach.

Cloning a skill​

Select Clone to start a new skill from an existing one. Name the clone — it's suggested as billing-runbook (clone) — and the gateway copies the instructions, references, scripts, description, and labels into it, then opens it ready to edit.

A clone is always private to whoever made it, even if the skill it came from is shared with the whole organization, and even if you're an administrator. A clone is a working copy; share it later if it earns it.

A clone is a separate skill, not a link: later edits to either one leave the other alone. It starts its own version history and is attached to no personas. Cloning needs only the access to read the skill you're cloning, so you can start from one someone else shared with you.


Versions​

Every change to a skill's content — the instructions, a reference, or a script — keeps the previous content as an earlier version. The registry holds the version a skill serves today and the two before it, so a bad edit is one step away from being undone.

Select Versions on a skill to open it. The panel lists each version with who saved it and when, and shows what that save changed — the version you select held against the version before it, file by file: SKILL.md, each reference, and each script. Removed lines are marked in red against the earlier version, added lines in green against the later one, and a line above the comparison names which version each colour belongs to. It opens on the version in use, so the first thing you see is what the most recent save did.

Selecting an earlier version offers a second view, Against current: that version held against what the skill serves today — in other words, exactly what restoring it would change. Anyone who can see a skill can read its versions.

What a version covers​

A version is a skill's content: the SKILL.md instructions and every reference and script. Changing any of those keeps a version. Changing a skill's name or description does not — those are edited freely and don't fill up your three slots.

Name and description still travel with each version, though. Every version records the name and description the skill had while that version was in use, so restoring brings back the wording that went with the content, not just the body. The Versions panel tells you when a restore would rename the skill, before you commit to it.

Restoring an earlier version​

Select Restore version on the one you want. That version becomes the one the skill serves, along with the name and description it carried. Nothing is created and nothing is dropped — the version you restored from stays in the list, so switching back is one more restore.

Restoring changes what every agent using the skill is told to do, so the gateway names the affected personas and asks you to confirm first. With no personas attached, the restore goes straight through. Restoring is available to a skill's author and to administrators — the same people who can edit it.

Only three versions are kept

Saving a fourth version drops one of the three, and dropped versions cannot be recovered. The version in use is never the one dropped — so if you restore an older version and then edit it, the version you restored stays, and the next-oldest goes instead. Once a skill is holding three, the editor names the version your next save will drop before you save it, and the Versions panel marks that version Drops next. Kept versions are a safety net for recent edits, not a permanent archive — keep anything you need long term in your own source control.

Save stays unavailable until something actually changes, so reopening an editor and closing it again can never spend a version. Editing only a skill's name, description, labels, visibility, or status still saves, but keeps no version — those are not content. While a content change is pending, the editor says that saving will keep a new version, and names the version it drops if the skill is already holding three.


Attaching Skills to an Agent Persona​

Skills only take effect once you attach them to a persona.

A skill must reach everyone the persona reaches​

A persona has an audience of its own — private, scoped to teams, or open to the whole organization. Attaching a skill to a persona hands that skill to everyone who can use the persona, so the skill's audience has to cover the persona's:

The skill is...You can attach it to...
Shared with everyoneAny persona.
Shared with specific teamsA persona scoped to those same teams, or a subset of them.
PrivateOnly your own private persona.

This is why a skill shared with Engineering can't go on a company-wide persona: the persona would hand an Engineering-only playbook to everyone. Either share the skill more widely, or narrow the persona.

In the skill picker, skills the persona's audience doesn't cover simply aren't listed, and a note at the bottom tells you how many were left out — 3 skills are not listed: they are not shared with everyone this persona reaches. If nothing qualifies, you'll see No skill is shared widely enough to attach to this persona. Share a skill with this persona's audience, or narrow the persona.

Widening a persona can strand a skill

If you later open a persona up — say from two teams to the whole organization — a skill attached to it may no longer reach far enough, and saving the persona is refused with a message naming the skill. Share that skill more widely first, or detach it. An already-attached skill that no longer qualifies stays listed with a Private skill or Not shared with this persona's teams badge so you can uncheck it.

From an existing persona​

  1. Open the persona from the Agent Personas list.
  2. On the Overview tab, find the Skills card and select Attach skills.
  3. In the dialog, search for and check the skills you want, then select Save.

To remove a skill, select the detach (×) icon on the attached skill row.

While creating a persona​

In the Create agent persona wizard, Skills is its own dedicated step — separate from the Tools & APIs step where you select MCP tools and API endpoints. On the Skills step, check the skills to attach.


How Agents Use Skills​

Skills are delivered to agents using progressive disclosure — the agent is made aware of what's available, but only loads the detail it needs, when it needs it. When an agent connects to a persona that has skills attached:

  1. Awareness. On connect, the agent receives a short note listing the available skills by name and description.
  2. Discovery. The agent can pull up the catalog of attached skills (name and description only) to decide which one fits the task at hand.
  3. Load on demand. When a task matches a skill, the agent loads that skill's full instructions — plus any references and scripts — and follows them.

This keeps the agent focused: a persona can offer many skills without flooding the agent with instructions it doesn't need for the current request. Skills work alongside the persona's tools and APIs — the loaded instructions often tell the agent which of its tools to use and in what order.

Because access is scoped to the persona, an agent can only load the skills that persona was granted — it can't discover or load skills from other personas or tenants.

A skill's audience follows it to the agent. On the agent endpoint, where people reach skills by name rather than through a single persona, someone only ever sees the skills shared with them — private skills to their owner, team skills to that team's members, and organization-wide skills to everyone. A skill that isn't shared with you answers exactly as an unknown skill name does, so its existence stays private.


Real-World Example​

"I want every support agent to escalate the same way."

  1. In the Skill Registry, select Add Skill and paste a SKILL.md:
    • name: support-escalation
    • description: When and how to escalate a support ticket.
    • Instructions covering severity levels, who to notify, and the message format.
  2. Add a label like support, then select Create.
  3. Open your Support Triage persona → Overview → Skills → Attach skills, check support-escalation, and select Save.

Now every agent connecting to the Support Triage persona follows the same escalation playbook — and when you refine the wording later, the update reaches all of them automatically.


Tips​

  • Write the description for the agent. The description is how an agent decides when to use a skill — make it a clear "use this when…" sentence.
  • Keep instructions focused. One skill, one job. Several small, well-scoped skills beat one giant catch-all.
  • Use references for examples. Put long examples or checklists in a reference file rather than bloating the instructions.
  • Detach before retiring. To delete a skill, detach it from personas first.
  • Reuse across personas. A well-written skill (a house style, an escalation runbook) is worth attaching to every persona that touches that workflow.
  • Start private, share when it's good. Draft a skill as private, get it right, then share it with the teams that need it — sharing later takes two clicks and nothing has to be rebuilt.
  • Match the audience to the persona you have in mind. If a skill is destined for a company-wide persona, share it with everyone from the start; scoping it to teams first just means changing it again later.