AgentSkill Object
The AgentSkill object supports two modes: referenced (server-stored) and inline (sent per-request).
Common fields:
| Field | Type | Default | Description |
|---|
type | string | "skill_reference" | "skill_reference" for server-stored skills, "inline" for inline bundles |
type = "skill_reference"):
| Field | Type | Default | Description |
|---|
skill_name | string | null | Human-readable skill name for lookup |
skill_id | string | null | Unique identifier (UUID or name string) |
skill_version | string | "latest" | Skill version to use |
At least one of skill_name or skill_id must be provided. If both are given, skill_id takes precedence for resolution.
Inline Skill Fields
When type = "inline", the following fields are used instead of skill_name/skill_id:
| Field | Type | Default | Description |
|---|
name | string | null | Human-readable name for the inline skill |
description | string | null | Short description of what the skill does |
source | object | null | Source payload containing the base64-encoded zip bundle (see below) |
| Field | Type | Default | Description |
|---|
type | string | "base64" | Encoding type (currently only "base64") |
media_type | string | "application/zip" | MIME type of the bundle |
data | string | required | Base64-encoded zip containing SKILL.md and optional files |
For inline skills, source (with data) is required, and skill_id/skill_name must not be set.
Referenced vs Inline
| Referenced Skills | Inline Skills |
|---|
| How to use | skill_id or skill_name | source with base64 zip |
| Persistence | Stored on the server | Sent per-request, not persisted |
| Version pinning | Supported (version field) | N/A (bundle is the version) |
| Best for | Production, shared skills | Prototyping, ephemeral use, CI/CD |
type field | "skill_reference" | "inline" |
Identifier Resolution
The platform resolves skill references in this order:
- If
skill_id is provided, use it directly
- If
skill_name is provided, look up by name
- If
skill_version is "latest" (default), resolve to the most recent revision
- If
skill_version is a specific string (e.g., "20260219-abc123"), resolve to that exact version
Toolsets define what capabilities are available to the agent when executing a skill:
| Toolset | Description |
|---|
core | Basic operations (file I/O, text processing) |
document | Document extraction and layout understanding |
image | Image analysis and understanding |
image-gen | Image generation and editing |
video | Video analysis and understanding |
viz | Visualization and annotation |
web | Web search and retrieval |
world-gen | World generation and editing |
Skill File Spec
| File | Required | Format | Purpose |
|---|
SKILL.md | Yes | YAML frontmatter + Markdown | Metadata and instructions |
vlmrun.yaml | Yes | YAML | Execution configuration |
schema.json | Recommended | JSON Schema draft-07 | Output validation |
resources/ | No | Any | Supporting files |
Python SDK Helpers
The Python SDK provides two convenience functions for working with local skill directories:
| Function | Import | Returns | Description |
|---|
create_from_directory | client.skills.create_from_directory(...) | AgentSkill (type="skill_reference") | Zips a local directory, uploads via the Files API, and creates a server-side skill in one call |
AgentSkill.from_directory | from vlmrun.client.types import AgentSkill | AgentSkill (type="inline") | Classmethod that zips and base64-encodes a local directory into an inline skill bundle (no server upload) |
SKILL.md file. Skill name and description are read from the YAML frontmatter automatically.
from pathlib import Path
from vlmrun.client import VLMRun
from vlmrun.client.types import AgentSkill
client = VLMRun(api_key="<VLMRUN_API_KEY>")
# Server-side: upload and create a reusable skill
skill_ref = client.skills.create_from_directory(Path("./my-skill"))
# Inline: build a self-contained skill bundle (no upload)
skill_inline = AgentSkill.from_directory(Path("./my-skill"))
API Endpoints
| Operation | Method | Endpoint |
|---|
| List skills | GET | /v1/skills |
| Get skill by ID | GET | /v1/skills/{skill_id} |
| Create skill | POST | /v1/skills/create |
| Update skill | POST | /v1/skills/{skill_id}/update |
| Lookup skill | POST | /v1/skills/lookup |
| Download skill | GET | /v1/skills/{skill_id}/download |
