Skip to main content

Skills catalog

The Registry Server includes a skills catalog that lets you discover, publish, and manage Agent Skills in a centralized location. Instead of searching scattered sources for skills compatible with your AI coding tools, you can browse a single registry that your team or organization maintains.

What are Agent Skills?​

Agent Skills are reusable, versioned definitions that describe tool configurations for AI coding assistants like Claude Code. A skill bundles together metadata about what tools are needed, how to obtain them (via OCI images or Git repositories), and compatibility requirements — so that an AI agent can find and use the right tools for a task.

Skills follow the Agent Skills Specification and are stored alongside MCP server entries in the registry.

Each skill includes:

  • Identity — a reverse-DNS namespace (e.g., io.github.user) and a name (e.g., code-review), forming a unique identifier
  • Version — any non-empty string, ideally a semantic version or commit hash
  • Description — what the skill does
  • Packages — distribution artifacts (OCI images or Git repositories) that contain the skill's implementation
  • Optional metadata — title, license, compatibility requirements, allowed tools, icons, and source repository

Why use a skills catalog?​

Without a centralized catalog, finding the right skill for a task means searching across GitHub repositories, documentation sites, and team wikis. The skills catalog solves this by providing:

  • Centralized discovery — browse and search all available skills from a single API
  • Version management — publish multiple versions of a skill and retrieve specific versions or the latest
  • Organization-wide curation — administrators can publish approved skills to a managed registry, ensuring consistency across teams
  • Status tracking — mark skills as active, deprecated, or archived to manage their lifecycle

Prerequisites​

The skills API is an extension endpoint available on managed registries. To use it, you need a Registry Server instance with at least one managed registry configured.

API endpoints​

The skills API is mounted at:

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

For complete endpoint documentation, including request/response schemas and query parameters, see the Registry API reference.

info

The skills API is a ToolHive extension to the MCP Registry specification. It lives under the x/ (extension) namespace and may evolve in future releases.

Skill lifecycle​

A typical workflow for managing skills:

  1. Publish a skill version to a managed registry using POST /{registryName}/v0.1/x/dev.toolhive/skills with the skill metadata and package references
  2. Discover available skills by listing or searching the catalog
  3. Retrieve a specific skill to get its package references and metadata
  4. Deprecate outdated versions by publishing an update with "status": "deprecated"
  5. Delete versions that are no longer needed

Publishing and deleting require authentication. Read operations (list, search, get) follow the registry's configured authentication mode.

Next steps​