Skip to main content
A skill is a folder of instructions (plus optional helper files) an agent loads when the task calls for it — a playbook it reaches for, without bloating every prompt. Skills are the most common way to grow an agent past its base prompt (the second rung).

​
What a skill is

A folder with a SKILL.md: 
triage/
  SKILL.md
  checklist.md        # optional helper the SKILL.md can reference
SKILL.md is YAML frontmatter followed by instructions: 
---
name: triage
description: Triage an incoming pull request
---
1. Read the diff and the linked issue.
2. Label by area, flag risky changes, run the tests.
3. Summarize in three bullets.
  • name + description are always visible to the agent; the body is loaded only when the agent decides the skill is relevant — progressive disclosure that keeps context lean.
  • Helper files alongside SKILL.md (checklists, scripts, references) are available when the skill runs.

​
How it works

When a session starts, the agent’s skills are materialized into its runtime. The model sees each skill’s name + description and invokes one when the task matches, then follows its instructions (and can read its helper files). Skills don’t run on their own — the agent uses them like tools. Skills are part of the agent’s revision: they’re versioned, rolled back, and activated together with the prompt and model. Changing skills is a deployment.

​
Add skills

Three ways. Each is a deployment that creates a new immutable revision (your new skills + the agent’s current prompt & model) and activates it — so changing skills is versioned and instantly reversible, never a destructive edit.
One folder per skill (a top-level skills/ wrapper is fine — it’s stripped):
triage/
  SKILL.md
pr-review/
  SKILL.md
  checklist.md

# Skills ship as part of a deploy — put them in a skills/ folder:
oc agent deploy ./agent
In the dashboard, the agent’s Skills panel uploads the same .zip. This is a deployment: it creates a new revision (keeping the current prompt + model, replacing the skills) and activates it. The previous skills aren’t lost — roll back anytime by re-activating the earlier revision (one click in the Revisions panel, or oc agent rollback <n>).

​
List & remove

REST API
GET    /v3/agents/agt_123/skills     # enumerated: name, description, files
DELETE /v3/agents/agt_123/skills     # remove all skills (deploys a revision with none)
GET returns each skill with its parsed name/description and file list — handy for showing what an agent currently knows.

​
Authoring tips

  • One skill, one job. A sharp description is what tells the agent when to use it.
  • Keep SKILL.md instructions concrete and ordered; move long reference material into helper files the body points to.
  • Skills are instructions, not code — they shape how the agent works, using the runtime’s own tools.

​
Limits & availability

  • Up to 64 files, 256 KiB total, UTF-8 text, file modes 0644/0755.
  • claude runtime only today; skills on codex agents are coming soon.