Skip to main content

Skills

AI coding agents use instruction files to learn how to perform specific tasks. These instruction files — called skills — contain metadata and step-by-step guidance that teach an agent what tools to use, what patterns to follow, and how to complete a task correctly.

Without a centralized way to discover and share skills, developers end up duplicating effort: writing the same instructions from scratch, searching scattered sources, or manually copying files between projects.

The ToolHive Registry Server provides a catalog for skills, so you can publish and discover them from a central location.

What is a skill?​

A skill is a SKILL.md file with YAML frontmatter containing metadata and a Markdown body containing instructions for the AI agent. Skills follow the Agent Skills specification.

Here's a simplified example showing the frontmatter:

SKILL.md
---
name: code-review
description: Review pull requests for correctness and style
version: 1.0.0
allowed-tools: Read Grep Glob
license: Apache-2.0
---

Instructions for the AI agent go here...

The frontmatter defines the skill's identity and constraints. The Markdown body below it contains the actual instructions the AI agent follows.

Key properties​

Each skill is identified by a namespace (reverse-DNS format, e.g. io.github.user) and a name. Skills are versioned using semantic versioning or commit hashes and can include metadata like allowedTools, license, and compatibility. For the complete field reference, see Managing skills.

Skills and MCP servers​

Skills and MCP servers are separate concepts that coexist in the same registry infrastructure. An MCP server provides tools that an AI agent can call. A skill provides instructions that tell an agent how to use those tools effectively.

For example, an MCP server might expose a query_database tool, while a skill teaches the agent best practices for writing safe, efficient queries using that tool.

Distribution​

Skills can be distributed as OCI artifacts or from Git repositories. OCI artifacts can be pushed to any OCI-compatible registry (such as GitHub Container Registry) and referenced by tag or digest. Git-based packages reference a repository URL, commit, and optional subfolder.

The ToolHive Registry Server stores skill metadata and makes it searchable through its API. The actual skill content is fetched from the package source when a skill is installed.

Lifecycle​

Skills have three lifecycle states:

  • Active — the skill is available for discovery and installation
  • Deprecated — the skill is still available but discouraged; a newer alternative may exist
  • Archived — the skill is no longer recommended for use

Next steps​