Skills extension API

The skills extension API provides endpoints for publishing, discovering, and managing Agent Skills in the ToolHive Registry. These endpoints are available under the dev.toolhive extension namespace.

Base path

All skills endpoints use the following base path:

/{registryName}/v0.1/x/dev.toolhive/skills

Where {registryName} is the name of the registry as defined in your configuration.

Endpoints

List skills

GET /{registryName}/v0.1/x/dev.toolhive/skills

Returns a paginated list of skills, showing the latest version of each.

Query parameters:

Parameter	Type	Default	Description
search	string	-	Substring match on name, title, or description
status	string	-	Filter by status (e.g., active, deprecated)
limit	int	50	Results per page (1-100)
cursor	string	-	Pagination cursor from a previous response

Response: 200 OK

{
  "skills": [
    {
      "namespace": "io.github.acme",
      "name": "code-review",
      "description": "Structured code review following OWASP guidelines",
      "version": "1.2.0",
      "status": "active",
      "title": "Security Code Review",
      "license": "Apache-2.0",
      "compatibility": "Requires git",
      "repository": { "url": "https://github.com/acme/skills", "type": "git" },
      "packages": [
        {
          "registryType": "git",
          "url": "https://github.com/acme/skills",
          "ref": "v1.2.0",
          "subfolder": "skills/code-review"
        }
      ]
    }
  ],
  "metadata": {
    "count": 1,
    "nextCursor": ""
  }
}

Get latest version

GET /{registryName}/v0.1/x/dev.toolhive/skills/{namespace}/{name}

Returns the latest version of a skill.

Path parameters:

Parameter	Description
namespace	Skill namespace in reverse-DNS format
name	Skill name

Response: 200 OK with a single skill object.

List versions

GET /{registryName}/v0.1/x/dev.toolhive/skills/{namespace}/{name}/versions

Returns all versions of a skill.

Response: 200 OK with a skill list response containing all versions.

Get specific version

GET /{registryName}/v0.1/x/dev.toolhive/skills/{namespace}/{name}/versions/{version}

Returns a specific version of a skill.

Path parameters:

Parameter	Description
namespace	Skill namespace in reverse-DNS format
name	Skill name
version	Version string

Response: 200 OK with a single skill object.

Publish skill

POST /{registryName}/v0.1/x/dev.toolhive/skills

Publishes a new skill version to a managed registry. Requires authentication.

Request body:

{
  "namespace": "io.github.acme",
  "name": "code-review",
  "description": "Structured code review following OWASP guidelines",
  "version": "1.2.0",
  "status": "active",
  "title": "Security Code Review",
  "license": "Apache-2.0",
  "compatibility": "Requires git",
  "allowedTools": ["Bash(git:*)", "Read"],
  "repository": {
    "url": "https://github.com/acme/skills",
    "type": "git"
  },
  "icons": [
    {
      "src": "https://example.com/icon.png",
      "size": "64x64",
      "type": "image/png",
      "label": "logo"
    }
  ],
  "packages": [
    {
      "registryType": "git",
      "url": "https://github.com/acme/skills",
      "ref": "v1.2.0",
      "subfolder": "skills/code-review"
    }
  ],
  "metadata": {
    "author": "acme-security-team"
  },
  "_meta": {}
}

Required fields: namespace, name, description, version

Response: 201 Created with the published skill object.

Delete skill version

DELETE /{registryName}/v0.1/x/dev.toolhive/skills/{namespace}/{name}/versions/{version}

Deletes a specific skill version from a managed registry. Requires authentication.

Response: 204 No Content

Skill object

Field	Type	Required	Description
namespace	string	Yes	Reverse-DNS ownership scope (e.g., io.github.acme)
name	string	Yes	Skill identifier (e.g., code-review)
description	string	Yes	What the skill does and when to use it
version	string	Yes	Version string (e.g., 1.2.0)
status	string	No	active, deprecated, or archived (defaults to active)
title	string	No	Human-friendly display name
license	string	No	SPDX license identifier
compatibility	string	No	Environment requirements
allowedTools	string[]	No	Pre-approved tools (experimental)
repository	object	No	Source repository (url, type)
icons	object[]	No	Display icons (src, size, type, label)
packages	object[]	No	Distribution packages (see below)
metadata	object	No	Custom key-value pairs
_meta	object	No	Extended metadata with reverse-DNS namespacing

Package types

OCI package

Field	Type	Required	Description
registryType	string	Yes	Must be "oci"
identifier	string	Yes	OCI image reference
digest	string	No	Content digest
mediaType	string	No	OCI media type

Git package

Field	Type	Required	Description
registryType	string	Yes	Must be "git"
url	string	Yes	Git repository URL
ref	string	No	Tag or branch reference
commit	string	No	Commit SHA
subfolder	string	No	Path within the repository

Error responses

All error responses return a JSON object with an error field:

{ "error": "description of the error" }

Status	Description
400	Invalid request (missing required fields, bad query parameters)
401	Authentication required
403	Registry is not a managed registry
404	Skill, version, or registry not found
409	Version already exists for this skill
500	Internal server error

See also

• Agent Skills concepts -- what skills are and when to use them
• Skills catalog guide -- publish and discover skills step by step