Agent Skills
Agent Skills are reusable, structured instructions that teach AI agents how to perform specific tasks. While MCP servers provide tools (functions an agent can call), skills provide knowledge (step-by-step guidance on how to approach a problem).
Skills vs. MCP servers
MCP servers and skills serve complementary purposes in the ToolHive ecosystem:
| Aspect | MCP servers | Skills |
|---|---|---|
| What | Executable tools (APIs, functions) | Structured instructions (Markdown + YAML) |
| How agents | Call tool functions at runtime | Load instructions into their context |
| Example | A server that queries a database | A guide for writing SQL migration scripts |
| Format | Running container with MCP protocol | SKILL.md file with frontmatter |
A skill might reference MCP tools it expects to use, and an MCP server might ship with skills that explain how to use its tools effectively. The two work together: skills tell the agent what to do, and MCP tools give it the means to do it.
Agent Skills specification
Skills follow the open Agent Skills specification,
which defines a standard format for packaging agent instructions. Each skill is
a directory containing at minimum a SKILL.md file with YAML frontmatter and
Markdown instructions:
my-skill/
└── SKILL.md
The frontmatter includes metadata like the skill name, description, license, and optional fields such as compatibility requirements and allowed tools.
Skills in the registry
The ToolHive Registry server hosts a skills catalog alongside its MCP server registry. This lets you:
- Publish skills to a managed registry so teams can share reusable agent capabilities
- Discover skills by searching, filtering by status, or browsing by namespace
- Version skills independently, with automatic latest-version tracking
Skills live under a namespace (reverse-DNS format like io.github.myorg)
that represents ownership. Combined with the skill name and version, this
creates a unique identifier for every skill release.
When to use skills
Consider publishing skills to the registry when you have:
- Repeatable workflows that multiple teams or agents need to follow (e.g., code review checklists, deployment procedures, data analysis patterns)
- Domain expertise that benefits from standardized instructions (e.g., compliance checks, security auditing steps)
- Tool usage guides that explain how to combine multiple MCP tools to accomplish a complex task
Next steps
- Publish and manage skills through the Registry server
- View the skills API reference for endpoint details