Skip to main content
Skills are modular, reusable capabilities that extend VLM Run Orion agents with domain-specific expertise. Each skill packages instructions, metadata, and optional resources (scripts, templates, schemas) that the agent uses automatically when relevant.

​
Why use Skills?

Skills let you decouple what you want the agent to do from how it’s configured:
  • Reusable: Create a skill once, reference it in chat completions or agent executions
  • Versionable: Pin a specific skill version for reproducible results, or use "latest" for the newest revision
  • Composable: Pass multiple skills in a single request
  • Auto-generated: Create skills from a prompt, a chat session, or a pre-built skill zip
Skills work across both the Agent API (agent.vlm.run) and the main VLM Run API (api.vlm.run). See the Skills capability page for usage with generation endpoints (image, document, video, audio).

​
Skill Identifiers

Each skill can be referenced in two ways:
FieldDescriptionExample
skill_nameHuman-readable name for lookup"invoice-extraction"
skill_idUnique identifier (UUID or name string)"abc-123-def"
You must provide at least one of skill_name or skill_id. When using skill_name, you can also specify a version (defaults to "latest").

​
Using Skills in Chat Completions

Pass skills in the skills parameter when creating chat completions: 
from vlmrun.client import VLMRun

client = VLMRun(base_url="https://agent.vlm.run/v1", api_key="<VLMRUN_API_KEY>")

response = client.agent.completions.create(
    model="vlmrun-orion-1:auto",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Extract data from this document."},
                {"type": "file_url", "file_url": {"url": "https://example.com/invoice.pdf"}}
            ]
        }
    ],
    skills=[{"skill_name": "invoice-extraction"}],
)

​
Using Skills in Agent Execution

Pass skills in the config.skills parameter when executing agents: 
from vlmrun.client import VLMRun
from vlmrun.client.types import AgentExecutionConfig, AgentSkill
from vlmrun.types import MessageContent, FileUrl

client = VLMRun(base_url="https://agent.vlm.run/v1", api_key="<VLMRUN_API_KEY>")

response = client.agent.execute(
    inputs={"file": MessageContent(type="file_url", file_url=FileUrl(url="<file-url>"))},
    config=AgentExecutionConfig(
        skills=[AgentSkill(skill_name="patient-referral", version="20260219-abc123")]
    ),
    batch=True,
)

​
Managing Skills

Skills are managed through dedicated API endpoints. You can create, list, lookup, update, and download skills programmatically.

​
Creating a Skill

Skills can be created in three ways:
ModeSourceDescription
Promptprompt (+ optional json_schema)Auto-generate SKILL.md and schema.json from a text prompt
Sessionsession_idAuto-generate SKILL.md from a chat session’s history
Filefile_idUpload a pre-built skill zip containing SKILL.md
from vlmrun.client import VLMRun

client = VLMRun(base_url="https://agent.vlm.run/v1", api_key="<VLMRUN_API_KEY>")

skill = client.skills.create(
    prompt="Extract invoice_id, date, and total_amount from invoices.",
    json_schema={
        "type": "object",
        "properties": {
            "invoice_id": {"type": "string"},
            "invoice_date": {"type": "string", "format": "date"},
            "total_amount": {"type": "number"}
        },
        "required": ["invoice_id", "invoice_date", "total_amount"]
    }
)
print(f"Created skill: {skill.id} ({skill.name})")

​
Listing and Looking Up Skills

from vlmrun.client import VLMRun

client = VLMRun(base_url="https://agent.vlm.run/v1", api_key="<VLMRUN_API_KEY>")

# List all skills
skills = client.skills.list()

# Lookup by name
skill = client.skills.get(name="invoice-extraction")

# Lookup by name + version
skill = client.skills.get(name="invoice-extraction", version="20260219-abc123")

# Lookup by ID
skill = client.skills.get(id="<skill-id>")

​
Updating a Skill

Updating a skill creates a new version with a new unique ID but the same name: 
from vlmrun.client import VLMRun
from pathlib import Path

client = VLMRun(base_url="https://agent.vlm.run/v1", api_key="<VLMRUN_API_KEY>")

# Upload new skill zip
file = client.files.upload(file=Path("updated-skill.zip"))

# Update creates a new version
updated = client.skills.update(
    skill_id="<skill-id>",
    file_id=file.id,
    description="Improved invoice extraction"
)
print(f"New version: {updated.version}")

​
Version Pinning

By default, version is "latest", which resolves to the most recent revision. Pin a specific version for reproducibility: 
from vlmrun.client.types import AgentSkill

# Always use latest
skill = AgentSkill(skill_name="invoice-extraction")

# Pin a specific version
skill = AgentSkill(skill_name="invoice-extraction", version="20260219-abc123")

​
AgentSkill Reference

The AgentSkill object accepts the following fields:
FieldTypeDefaultDescription
skill_namestringnullHuman-readable skill name for lookup
skill_idstringnullUnique identifier (UUID or name string)
versionstring"latest"Skill version to use
typestring"vlm-run"Skill type
At least one of skill_name or skill_id must be provided. If both are given, skill_id takes precedence.

Skills API Reference

View the complete API reference for skill endpoints

Skills in Generation Endpoints

Use skills with image, document, video, and audio generation