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
Make a skill available to attachDraft and Ready states
Add reference files or scriptsManaging skill files
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 are reviewed and marked Ready before any agent 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. Select Create.

Your new skill starts in the Draft state. Before any agent can use it, mark it Ready (see Draft and Ready states).

note

A skill's name and description come from the YAML header at the top of the SKILL.md content — there are no separate name and description fields. To change them later, edit the SKILL.md header.

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.

Draft and Ready States​

Every skill is in one of two states, shown as a chip next to its name:

StateMeaning
DraftThe skill is a work in progress. It cannot be attached to a persona.
ReadyThe skill has been reviewed and is available to attach to personas. Agents can load it.

Making a skill Ready​

  1. Select the skill in the list.
  2. In the detail panel, use the Draft / Ready toggle and select Ready.
  3. Confirm in the dialog (Mark skill as Ready?). The skill can now be attached to personas.

Moving a skill back to Draft​

  1. Select the skill and switch the toggle to Draft.
  2. Confirm in the dialog (Move skill to Draft?).
Skills in use are protected

You can't move a skill back to Draft — or delete it — while it's attached to a persona. Detach it from every persona first, then change the state. This prevents accidentally pulling a skill out from under an agent that depends on it.

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 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 Ready 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.

Attaching Skills to an Agent Persona​

Skills only take effect once you attach them to a persona. Only Ready skills can be attached.

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 Ready 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, the Capabilities step includes a Skills section alongside MCP tools and API endpoints. Expand it and check the Ready skills to attach.

tip

If a skill you want isn't in the list, it's probably still in Draft. Open the Skill Registry, mark it Ready, and it becomes available 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.

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. Mark the skill Ready.
  4. 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.
  • Review before Ready. Treat marking a skill Ready as your approval step — it's the point where agents can start using it.
  • Detach before retiring. To delete or pause a skill, detach it from personas first, then move it to Draft or delete it.
  • Reuse across personas. A well-written skill (a house style, an escalation runbook) is worth attaching to every persona that touches that workflow.
Last updated on