Reference

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

Referenced skill fields (when 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)

InlineSkillSource object:

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

Available Toolsets

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)

Both functions require the directory to contain a 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`

Overview

Specification

Using Skills

Managing Skills

AgentSkill Object

Inline Skill Fields

Referenced vs Inline

Identifier Resolution

Available Toolsets

Skill File Spec

Python SDK Helpers

API Endpoints

​AgentSkill Object

​Inline Skill Fields

​Referenced vs Inline

​Identifier Resolution

​Available Toolsets

​Skill File Spec

​Python SDK Helpers

​API Endpoints

AgentSkill Object

Inline Skill Fields

Referenced vs Inline

Identifier Resolution

Available Toolsets

Skill File Spec

Python SDK Helpers

API Endpoints