Shared Skill response and package structures.
Skill object
Returned by create, get, and list endpoints (the skill shell).
| Field | Type | Description |
|---|---|---|
id | string | Skill ID with the skill_ prefix |
type | string | Always "skill" |
display_title | string | Display title (at most 255 characters; uniqueness not enforced; immutable after creation). Default: for zip uploads, the zip filename without .zip; for bare file trees, the SKILL.md name |
source | string | Valid values: custom, qoder |
latest_version | string | null | Latest version as an epoch-microsecond string (e.g. "1759178010641129"); null when all versions have been deleted |
metadata | object | Custom metadata object stored with the Skill; defaults to {} |
created_at | string | Creation time (ISO 8601, microsecond precision, e.g. 2026-05-18T15:35:24.248164Z) |
updated_at | string | Last update time (ISO 8601, microsecond precision); refreshed when versions are created or deleted |
description | string | ⚠️ Deprecated: skill description (use the description on version objects instead) |
content | string | ⚠️ Deprecated: base64-encoded content, present only when include_content=true (use GET /skills/{skill_id}/versions/{version}/content instead) |
content_encoding | string | ⚠️ Deprecated: present with content; value is base64 (same replacement as above) |
Skill version object
Returned by Create version, Get version, and List versions. Each version is an immutable, complete content snapshot.
| Field | Type | Description |
|---|---|---|
id | string | Version ID |
type | string | Always "skill_version" |
skill_id | string | Owning Skill ID |
version | string | Version identifier, an epoch-microsecond string taken at creation time (e.g. "1759178010641129") |
name | string | name from this version's SKILL.md frontmatter; must be consistent across versions |
description | string | description from this version's SKILL.md frontmatter |
directory | string | Sandbox install directory name; always equal to name |
created_at | string | Version creation time (ISO 8601, microsecond precision) |
content_size | integer | ⚠️ Deprecated: content size in bytes (no replacement; will be removed) |
content_sha256 | string | ⚠️ Deprecated: SHA-256 digest (no replacement; will be removed) |
status | string | ⚠️ Deprecated: version status (no replacement; will be removed) |
updated_at | string | ⚠️ Deprecated: last update time (versions are immutable; use created_at instead) |
Skill package
Create-skill and create-version requests upload content through the multipart/form-data files field as a .zip archive or a bare file tree.
| Rule | Description |
|---|---|
| Upload forms | A single .zip archive, or a bare file tree (multiple files parts whose filenames carry relative paths) |
| Size limits | Archive at most 50 MB, and uncompressed content at most 50 MB |
| Top-level directory | A single top-level directory is required, and its name must equal the SKILL.md name; otherwise 400 |
| Required manifest | SKILL.md inside the top-level directory, starting with YAML frontmatter |
Frontmatter name | Required, non-empty; at most 64 characters; must match ^[a-z0-9][a-z0-9_-]*$; must be consistent across all versions of a skill |
Frontmatter description | Required, non-empty; at most 5120 characters |
| Frontmatter parsing | Strict YAML first; on failure, a lenient fallback extracts top-level name:/description: line by line and ignores other keys. Quote values containing ': ' |