Skill

View as Markdown

A Skill is an agentskills.io bundle registered in Unity Catalog. Clients transfer bundle bytes through the Files API. FinalizeSkill reads the uploaded SKILL.md and projects its frontmatter onto the Skill metadata.

Get a skillGET /api/2.1/unity-catalog/{name=skills/*}List skillsGET /api/2.1/unity-catalog/skillsCreate a skillPOST /api/2.1/unity-catalog/skillsUpdate a skillPATCH /api/2.1/unity-catalog/{name=skills/*}Delete a skillDELETE /api/2.1/unity-catalog/{name=skills/*}Finalize a skillPOST /api/2.1/unity-catalog/{name=skills/*}/finalize

Skill object

A Skill is an agentskills.io bundle registered in Unity Catalog. Clients transfer bundle bytes through the Files API. FinalizeSkill reads the uploaded SKILL.md and projects its frontmatter onto the Skill metadata.

namestringBetaIDImmutable

Resource name of the skill. Format: skills/{catalog}.{schema}.{skill}. Each {...} component is capped at 255 characters individually. Server-derived on Create from parent + skill_id; required and immutable on Update/Get/Delete.

bundle_namestringBetaOutput only

Name from the most recently successfully finalized SKILL.md. It may differ from the final component of the Skill resource name. Unset until FinalizeSkill succeeds.

descriptionstringBetaOutput only

Description from the most recently successfully finalized SKILL.md. Unset until FinalizeSkill succeeds.

etagstringBetaOutput only

Optimistic concurrency token returned on every read. To make an Update or Delete conditional, pass the last-read value in that request's etag field. In REST responses, this value is a base64 string; URL-encode it when setting the etag query parameter.

create_timestringBetaOutput only

Time the skill was created.

update_timestringBetaOutput only

Time of the most recent Skill metadata mutation. Uploading bundle files alone does not change this value.

finalize_timestringBetaOutput only

Time of the most recent successful FinalizeSkill. Unset until one succeeds.

created_bystringBetaOutput only

Creator identity.

updated_bystringBetaOutput only

Identity of the last updater.

effective_ownerstringBetaOutput only

Owner of the skill.

metastore_idstringBetaOutput only

Metastore hosting the skill.

commentstringBeta

User-provided comment for the skill. Free-text, user-editable via UpdateSkill (listed in its update_mask). DISTINCT from description, which is the server-parsed, OUTPUT_ONLY SKILL.md frontmatter value: comment is the customer's own annotation and is preserved across bundle re-uploads. When comment is in the update mask, omitting it clears the field, while an explicitly empty string is retained.

View as Markdown

The Skill object

{
  "name": "string",
  "bundle_name": "string",
  "description": "string",
  "etag": "string",
  "create_time": "string",
  "update_time": "string",
  "finalize_time": "string",
  "created_by": "string",
  "updated_by": "string",
  "effective_owner": "string",
  "metastore_id": "string",
  "comment": "string"
}

Get a skill Beta

GET /api/2.1/unity-catalog/{name=skills/*}

Returns the skill identified by its resource name.

You must be the owner of the skill or have READ_VOLUME, READ_METADATA, or MANAGE on it, plus USE_CATALOG on the parent catalog and USE_SCHEMA on the parent schema.

API scopes: unity-catalog

Parameters

namestringRequiredpath

Full resource name of the skill. Format: skills/{catalog}.{schema}.{skill}. Each {...} component is capped at 255 characters individually.

Response

Returns the Skill object.

View as Markdown

Response

{
  "name": "string",
  "bundle_name": "string",
  "description": "string",
  "etag": "string",
  "create_time": "string",
  "update_time": "string",
  "finalize_time": "string",
  "created_by": "string",
  "updated_by": "string",
  "effective_owner": "string",
  "metastore_id": "string",
  "comment": "string"
}

List skills Beta

GET /api/2.1/unity-catalog/skills

Lists skills in a Unity Catalog schema. Provide parent as schemas/{catalog}.{schema}. Results are paginated; pass the returned next_page_token to fetch subsequent pages.

Requires USE_CATALOG on the parent catalog and USE_SCHEMA on the parent schema. Only skills the caller can access as owner or through READ_VOLUME, READ_METADATA, or MANAGE are returned.

API scopes: unity-catalog

Parameters

parentstringRequiredquery

Name of the parent schema. Format: schemas/{catalog}.{schema}. Each {...} component is capped at 255 characters individually.

Required: skill listing is schema-scoped, so parent must be set; an unset or empty parent is rejected with INVALID_PARAMETER_VALUE.

page_sizeint32<= 100query

Maximum number of skills to return. Defaults to 100 when unset or 0; the maximum is 100. Use page_token to retrieve additional pages.

page_tokenstringquery

Opaque pagination token from a previous request.

Response

Returns a list of Skill objects.

View as Markdown

Response

{
  "skills": [
    {
      "name": "string",
      "bundle_name": "string",
      "description": "string",
      "etag": "string",
      "create_time": "string",
      "update_time": "string",
      "finalize_time": "string",
      "created_by": "string",
      "updated_by": "string",
      "effective_owner": "string",
      "metastore_id": "string",
      "comment": "string"
    }
  ],
  "next_page_token": "string"
}

Create a skill Beta

POST /api/2.1/unity-catalog/skills

Creates a skill in a Unity Catalog schema and provisions its managed bundle storage. Specify its name in skill_id. The request contains an optional comment but no bundle bytes. Upload bundle files through the Files API, then call FinalizeSkill.

You must be the owner of the parent schema or have CREATE_VOLUME and USE_SCHEMA on it, plus USE_CATALOG on the parent catalog.

API scopes: unity-catalog

Parameters

parentstringRequiredquery

Name of the parent schema. Format: schemas/{catalog}.{schema}. Each {...} component is capped at 255 characters individually.

skill_idstringRequiredquery

Name for the skill, e.g. "basic-math". The server normalizes this identifier to lowercase. It is independent of the bundle name read from SKILL.md.

Request body

The skill to create. comment is the only accepted client input and may be omitted. Do not set name; the server derives it from parent and skill_id.

namestringIDImmutable

Resource name of the skill. Format: skills/{catalog}.{schema}.{skill}. Each {...} component is capped at 255 characters individually. Server-derived on Create from parent + skill_id; required and immutable on Update/Get/Delete.

commentstring

User-provided comment for the skill. Free-text, user-editable via UpdateSkill (listed in its update_mask). DISTINCT from description, which is the server-parsed, OUTPUT_ONLY SKILL.md frontmatter value: comment is the customer's own annotation and is preserved across bundle re-uploads. When comment is in the update mask, omitting it clears the field, while an explicitly empty string is retained.

Response

Returns the Skill object.

View as Markdown

Request

{
  "name": "string",
  "comment": "string"
}

Response

{
  "name": "string",
  "bundle_name": "string",
  "description": "string",
  "etag": "string",
  "create_time": "string",
  "update_time": "string",
  "finalize_time": "string",
  "created_by": "string",
  "updated_by": "string",
  "effective_owner": "string",
  "metastore_id": "string",
  "comment": "string"
}

Update a skill Beta

PATCH /api/2.1/unity-catalog/{name=skills/*}

Updates a skill. Only fields named in update_mask are changed; currently only comment is supported. The resource name is immutable. Optionally supply an etag to make the update conditional on the skill not having changed since it was read. Bundle files, grants, tags, and ownership are unchanged.

You must be the owner of the skill or have MANAGE on it, plus USE_CATALOG on the parent catalog and USE_SCHEMA on the parent schema.

API scopes: unity-catalog

Parameters

namestringRequiredIDImmutablepath

Resource name of the skill. Format: skills/{catalog}.{schema}.{skill}. Each {...} component is capped at 255 characters individually. Server-derived on Create from parent + skill_id; required and immutable on Update/Get/Delete.

update_maskstringRequiredquery

Fields to update; validated against skill. REQUIRED, matching the sibling Update RPCs. comment is the only mutable field.

etagstringquery

Optimistic concurrency token from the most recent read. When set, the update succeeds only if the resource has not changed. Leave unset for an unconditional update. For REST requests, URL-encode the base64 string returned by the API when setting the etag query parameter.

Request body

The skill with the updated field values. name identifies the resource (skills/{catalog}.{schema}.{skill}); only fields listed in update_mask are applied.

commentstring

User-provided comment for the skill. Free-text, user-editable via UpdateSkill (listed in its update_mask). DISTINCT from description, which is the server-parsed, OUTPUT_ONLY SKILL.md frontmatter value: comment is the customer's own annotation and is preserved across bundle re-uploads. When comment is in the update mask, omitting it clears the field, while an explicitly empty string is retained.

Response

Returns the Skill object.

View as Markdown

Request

{
  "comment": "string"
}

Response

{
  "name": "string",
  "bundle_name": "string",
  "description": "string",
  "etag": "string",
  "create_time": "string",
  "update_time": "string",
  "finalize_time": "string",
  "created_by": "string",
  "updated_by": "string",
  "effective_owner": "string",
  "metastore_id": "string",
  "comment": "string"
}

Delete a skill Beta

DELETE /api/2.1/unity-catalog/{name=skills/*}

Deletes the skill identified by its resource name and makes its managed bundle path unavailable. Managed bundle data is deleted asynchronously. Optionally supply an etag to make the delete conditional on the skill not having changed since it was read.

You must be the owner of the skill or have MANAGE on it, plus USE_CATALOG on the parent catalog and USE_SCHEMA on the parent schema.

API scopes: unity-catalog

Parameters

namestringRequiredpath

Full resource name of the skill. Format: skills/{catalog}.{schema}.{skill}. Each {...} component is capped at 255 characters individually.

etagstringquery

Optimistic concurrency token from the most recent read. When set, the delete succeeds only if the resource has not changed. Leave unset for an unconditional delete. For REST requests, URL-encode the base64 string returned by the API when setting the etag query parameter.

View as Markdown

Response

{}

Finalize a skill Beta

POST /api/2.1/unity-catalog/{name=skills/*}/finalize

Finalizes a skill after its bundle is uploaded. This method reads SKILL.md through the Files API using the caller's authorization. Its YAML frontmatter must contain an agentskills.io-compliant name and a nonblank description within the configured UTF-8 byte limit. On success, it replaces bundle_name and description; refreshes finalize_time, update_time, and updated_by; and returns the updated skill. comment is preserved. Re-finalization uses the latest SKILL.md and is last-write-wins without an etag precondition. Validation failures do not change metadata.

You must be the owner of the skill or have READ_VOLUME on it, plus USE_CATALOG on the parent catalog and USE_SCHEMA on the parent schema.

API scopes: unity-catalog

Parameters

namestringRequiredpath

Full resource name of the skill. Format: skills/{catalog}.{schema}.{skill}. Each {...} component is capped at 255 characters individually.

Response

Returns the Skill object.

View as Markdown

Response

{
  "name": "string",
  "bundle_name": "string",
  "description": "string",
  "etag": "string",
  "create_time": "string",
  "update_time": "string",
  "finalize_time": "string",
  "created_by": "string",
  "updated_by": "string",
  "effective_owner": "string",
  "metastore_id": "string",
  "comment": "string"
}