Skip to main content

Skills catalog

The Registry server includes a skills catalog that lets you publish, discover, and manage Agent Skills alongside MCP servers. Skills are exposed through extension endpoints under each registry.

Prerequisites​

Skills can only be published to managed registries. Read operations (list, get) work on any registry type.

Discover skills​

List skills​

Retrieve a paginated list of skills in a registry, showing the latest version of each:

curl https://registry.example.com/my-registry/v0.1/x/dev.toolhive/skills
Response
{
  "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"
    }
  ],
  "metadata": {
    "count": 1,
    "nextCursor": ""
  }
}

Query parameters:

ParameterTypeDefaultDescription
searchstring-Filter by substring match on name, title, or description
statusstring-Filter by status (e.g., active, deprecated)
limitint50Results per page (1-100)
cursorstring-Pagination cursor from a previous response

Get a specific skill​

Retrieve the latest version of a skill by namespace and name:

curl https://registry.example.com/my-registry/v0.1/x/dev.toolhive/skills/io.github.acme/code-review

List all versions​

View the version history for a skill:

curl https://registry.example.com/my-registry/v0.1/x/dev.toolhive/skills/io.github.acme/code-review/versions

Get a specific version​

Retrieve a particular version:

curl https://registry.example.com/my-registry/v0.1/x/dev.toolhive/skills/io.github.acme/code-review/versions/1.2.0

Publish a skill​

To publish a skill version, send a POST request to the skills endpoint with the skill metadata:

curl -X POST \
  https://registry.example.com/my-registry/v0.1/x/dev.toolhive/skills \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{
    "namespace": "io.github.acme",
    "name": "code-review",
    "description": "Structured code review following OWASP guidelines and project-specific rules.",
    "version": "1.2.0",
    "title": "Security Code Review",
    "license": "Apache-2.0",
    "compatibility": "Requires git and access to the internet",
    "repository": {
      "url": "https://github.com/acme/agent-skills",
      "type": "git"
    },
    "packages": [
      {
        "registryType": "git",
        "url": "https://github.com/acme/agent-skills",
        "ref": "v1.2.0",
        "subfolder": "skills/code-review"
      }
    ],
    "metadata": {
      "author": "acme-security-team"
    }
  }'

Required fields:

FieldDescription
namespaceReverse-DNS ownership scope (e.g., io.github.acme)
nameSkill identifier (e.g., code-review)
descriptionWhat the skill does and when to use it
versionVersion string (ideally semantic versioning, e.g., 1.2.0)

For the complete list of optional fields and package types, see the skills API reference.

Version tracking​

The registry automatically tracks the latest version of each skill. When you publish a new version, the server compares it against the current latest using semantic version comparison. The "latest" pointer only updates if the new version is semantically newer, so publishing an older patch version won't regress the latest pointer.

Delete a skill version​

Remove a specific version from a managed registry:

curl -X DELETE \
  https://registry.example.com/my-registry/v0.1/x/dev.toolhive/skills/io.github.acme/code-review/versions/1.2.0 \
  -H "Authorization: Bearer <TOKEN>"

A successful deletion returns a 204 No Content response. Deleting a version also removes its associated packages.

Naming conventions​

Skills use a namespace + name addressing scheme:

  • Namespace: Reverse-DNS format representing ownership (e.g., io.github.acme, com.example.team). This prevents naming conflicts between different publishers.
  • Name: The skill identifier. Follow the Agent Skills specification naming rules: lowercase letters, numbers, and hyphens only; no leading, trailing, or consecutive hyphens; maximum 64 characters.

Valid examples:

  • io.github.acme/code-review
  • com.example.security/vulnerability-scan

Invalid examples:

  • acme/Code-Review (uppercase not allowed in name)
  • io.github.acme/-code-review (name cannot start with a hyphen)

Next steps​