Skills and templates

What is a skill?

A skill is a folder of instructions that teaches the agent how to do one specific job, such as “draft release notes from a changelog” or “produce our standard weekly sales report”. It contains a SKILL.md file and, optionally, scripts, templates, or reference files the instructions refer to. Skills keep your agent’s base instructions short. Instead of putting every procedure in the agent’s instructions, you install skills in its sandbox. The agent sees each skill’s name and description, and loads the full instructions only when a task calls for that skill.

release-notes/
  SKILL.md          <- required: front matter + instructions
  template.md       <- optional files the instructions mention
  scripts/check.py

SKILL.md starts with YAML front matter giving a name and a description. The name uses only letters, digits, _ and -, since it names the folder the skill is staged in; an upload with any other name is refused. Write the description so the model can tell when to use the skill:

---
name: release-notes
description: Draft release notes from a changelog. Use when asked for release notes or a changelog summary.
---
Read CHANGELOG.md. Group changes into Features, Fixes, and Breaking changes.
Use template.md for the layout. Check every date against the git tags.

Skills need a managed sandbox; they are installed as files inside it.

Versions

Every upload of a skill is a numbered version. The skill also has a default version. Uploading a new version does not change the default unless you ask it to, so you can test a new version before switching everyone to it.

Action	Call
Create a skill (version 1, default)	`client.skills.create(files=[...])`
Upload a new version	`client.skills.versions.create(skill_id, files=[...], default=False)`
Make a version the default	`client.skills.update(skill_id, default_version=...)`

When you reference a skill, you can pin a specific version. Pinning makes runs reproducible: a session always gets exactly the instructions you tested.

Example: upload, version, and use in a template

Examples on this page assume client is an OpenAI client configured as in the quickstart. The upload is a zip file containing the skill folder. The zip can be at most 32 MiB, with at most 2,048 entries, each at most 32 MiB, and at most 128 MiB once unpacked.

import io
import zipfile


def bundle(skill_md: str) -> bytes:
    """Zip a skill folder that contains a single SKILL.md."""
    out = io.BytesIO()
    with zipfile.ZipFile(out, "w") as archive:
        archive.writestr("release-notes/SKILL.md", skill_md)
    return out.getvalue()


skill_md = """---
name: release-notes
description: Draft release notes from a changelog
---
Summarize changes.
"""

# 1. Create the skill. Version 1 becomes the default.
skill = client.skills.create(files=[("release-notes.zip", bundle(skill_md))])

# 2. Upload version 2 without changing the default yet.
version = client.skills.versions.create(
    skill.id,
    files=[("release-notes.zip", bundle(skill_md + "Check the dates.\n"))],
    default=False,
)

# 3. Promote it once you have tested it.
client.skills.update(skill.id, default_version=version.version)

# 4. Pin that exact version in a reusable template.
template = client.beta.agents.environments.templates.create(
    name="release-workspace",
    skills=[
        {"type": "skill_reference", "skill_id": skill.id, "version": version.version},
    ],
)

Install a skill in a session

Add it to the session’s environment, or to a template the session uses:

session = client.beta.agents.sessions.create(
    agent_id=agent.id,
    environment={
        "type": "openai_hosted",
        "skills": [
            {"type": "skill_reference", "skill_id": skill.id, "version": version.version},
        ],
    },
)

Environment templates

An environment template is a saved sandbox setup that many sessions can share: staged files, skills, packages, setup commands, environment variables, and network policy. Create it once, then pass its ID:

session = client.beta.agents.sessions.create(agent_id=agent.id, environment={
    "type": "openai_hosted",
    "environment_template_id": template.id,
})

Settings on the session override the template’s, except that a session cannot loosen the template’s network policy. Do not delete a template or skill while sessions that depend on it are still being created.

Keep it safe

Review skills like code. A skill’s instructions direct what the agent does, and its scripts run in the sandbox. Read third-party skills before installing them.
No secrets in skills or templates. Anything in them is readable by the agent. Use vault credentials for tokens.
Self-hosted environments cannot install skills. Put the files the agent needs in the workspace folder instead.

Start here

Build with Orca

Plans and billing

Operate your application

Skills and templates

What is a skill?

Versions

Example: upload, version, and use in a template

Install a skill in a session

Environment templates

Keep it safe

​What is a skill?

​Versions

​Example: upload, version, and use in a template

​Install a skill in a session

​Environment templates

​Keep it safe

What is a skill?

Versions

Example: upload, version, and use in a template

Install a skill in a session

Environment templates

Keep it safe