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 |
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 |
