From a364cb4211bd0798a09d05ccca9e07e7f02ba548 Mon Sep 17 00:00:00 2001 From: Radoslav Dimitrov Date: Tue, 10 Mar 2026 17:54:12 +0200 Subject: [PATCH 1/3] Update docs for registry server v0.6.3 Signed-off-by: Radoslav Dimitrov --- docs/toolhive/concepts/skills.mdx | 75 ++++++ .../guides-registry/configuration.mdx | 12 +- docs/toolhive/guides-registry/database.mdx | 4 +- docs/toolhive/guides-registry/intro.mdx | 6 +- docs/toolhive/guides-registry/skills.mdx | 184 +++++++++++++ .../reference/registry-skills-api.mdx | 244 ++++++++++++++++++ sidebars.ts | 3 + 7 files changed, 521 insertions(+), 7 deletions(-) create mode 100644 docs/toolhive/concepts/skills.mdx create mode 100644 docs/toolhive/guides-registry/skills.mdx create mode 100644 docs/toolhive/reference/registry-skills-api.mdx diff --git a/docs/toolhive/concepts/skills.mdx b/docs/toolhive/concepts/skills.mdx new file mode 100644 index 00000000..f47f8531 --- /dev/null +++ b/docs/toolhive/concepts/skills.mdx @@ -0,0 +1,75 @@ +--- +title: Agent Skills +description: + What Agent Skills are, how they relate to MCP servers, and why you would use + them in the ToolHive Registry +--- + +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](https://agentskills.io/), +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: + +```text +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](../guides-registry/skills.mdx) through the + Registry server +- [View the skills API reference](../reference/registry-skills-api.mdx) for + endpoint details diff --git a/docs/toolhive/guides-registry/configuration.mdx b/docs/toolhive/guides-registry/configuration.mdx index 083d328c..73435551 100644 --- a/docs/toolhive/guides-registry/configuration.mdx +++ b/docs/toolhive/guides-registry/configuration.mdx @@ -54,7 +54,7 @@ database: maxOpenConns: 25 maxIdleConns: 5 connMaxLifetime: '5m' - maxMetaSize: 65536 + maxMetaSize: 262144 # Optional: dynamic authentication (alternative to pgpass) # dynamicAuth: # awsRdsIam: @@ -276,8 +276,8 @@ The fields `file` and `url` are mutually exclusive. ### Managed registry -API-managed registry for directly publishing and deleting MCP servers via the -API. Does not sync from external sources. +API-managed registry for directly publishing and deleting MCP servers and +[skills](./skills.mdx) via the API. Does not sync from external sources. ```yaml title="config-managed.yaml" registries: @@ -297,6 +297,8 @@ registries: - `DELETE /{registryName}/v0.1/servers/{name}/versions/{version}` - Delete versions - `GET` operations for listing and retrieving servers +- Skills extension endpoints for publishing and managing Agent Skills (see + [Skills catalog](./skills.mdx)) See the [Registry API reference](../reference/registry-api.mdx) for complete endpoint documentation and request/response examples. @@ -349,7 +351,7 @@ of workloads. The types being watched are The Registry server will receive events when a resource among those listed above is annotated with the following annotations: -```yaml {7-16} +```yaml {7-18} apiVersion: toolhive.stacklok.dev/v1alpha1 kind: MCPServer metadata: @@ -360,6 +362,7 @@ metadata: toolhive.stacklok.dev/registry-url: 'https://mcp.example.com/servers/my-mcp-server' toolhive.stacklok.dev/registry-description: | Production MCP server for code analysis + toolhive.stacklok.dev/registry-title: 'Code Analysis Server' toolhive.stacklok.dev/tool-definitions: '[{"name":"analyze_code","description":"Analyze code for potential issues","inputSchema":{"type":"object","properties":{"file":{"type":"string","description":"Path @@ -375,6 +378,7 @@ spec: | `toolhive.stacklok.dev/registry-export` | Yes | Must be `"true"` to include in registry | | `toolhive.stacklok.dev/registry-url` | Yes | The external endpoint URL for this server | | `toolhive.stacklok.dev/registry-description` | Yes | Description text displayed in registry listings | +| `toolhive.stacklok.dev/registry-title` | No | Human-friendly display name shown in the registry `title` field | | `toolhive.stacklok.dev/tools` | No | JSON array of tool name strings (e.g., `["get_weather","get_forecast"]`) | | `toolhive.stacklok.dev/tool-definitions` | No | JSON array of tool definitions with MCP tool metadata (name, description, schema) | diff --git a/docs/toolhive/guides-registry/database.mdx b/docs/toolhive/guides-registry/database.mdx index f9732ad0..24d19b1b 100644 --- a/docs/toolhive/guides-registry/database.mdx +++ b/docs/toolhive/guides-registry/database.mdx @@ -23,7 +23,7 @@ database: maxOpenConns: 25 maxIdleConns: 5 connMaxLifetime: '5m' - maxMetaSize: 65536 + maxMetaSize: 262144 ``` ### Configuration fields @@ -39,7 +39,7 @@ database: | `maxOpenConns` | int | No | `25` | Maximum number of open connections to the database | | `maxIdleConns` | int | No | `5` | Maximum number of idle connections in the pool | | `connMaxLifetime` | string | No | `5m` | Maximum lifetime of a connection (e.g., "1h", "30m") | -| `maxMetaSize` | int | No | `65536` | Maximum allowed size in bytes for publisher-provided metadata extensions | +| `maxMetaSize` | int | No | `262144` | Maximum allowed size in bytes for publisher-provided metadata extensions (256 KB) | | `dynamicAuth` | object | No | - | Dynamic authentication configuration (see [Dynamic authentication](#dynamic-authentication) below) | \* Password configuration is required but has multiple sources (see Password diff --git a/docs/toolhive/guides-registry/intro.mdx b/docs/toolhive/guides-registry/intro.mdx index 431a8a70..eea4ed0e 100644 --- a/docs/toolhive/guides-registry/intro.mdx +++ b/docs/toolhive/guides-registry/intro.mdx @@ -2,7 +2,8 @@ title: Overview sidebar_label: Introduction description: - How to use the ToolHive Registry server to discover and access MCP servers + How to use the ToolHive Registry server to discover and access MCP servers and + Agent Skills --- The ToolHive Registry server is a standards-compliant implementation of the MCP @@ -58,6 +59,8 @@ flowchart LR managed registries, and Kubernetes discovery - **Automatic synchronization**: Background sync with configurable intervals and retry logic for Git, API, and File sources +- **Skills catalog**: Publish and discover reusable [Agent Skills](./skills.mdx) + alongside MCP servers - **Container-ready**: Designed for deployment in Kubernetes clusters, but can be deployed anywhere - **Flexible deployment**: Works standalone or as part of ToolHive @@ -102,5 +105,6 @@ The server supports five registry source types: - [Configure registry sources](./configuration.mdx) to set up your registry - [Deploy the server](./deployment.mdx) in your environment +- [Publish and discover skills](./skills.mdx) through the skills catalog - [View the API reference](../reference/registry-api.mdx) for endpoint documentation diff --git a/docs/toolhive/guides-registry/skills.mdx b/docs/toolhive/guides-registry/skills.mdx new file mode 100644 index 00000000..fc0a1c7a --- /dev/null +++ b/docs/toolhive/guides-registry/skills.mdx @@ -0,0 +1,184 @@ +--- +title: Skills catalog +description: + How to discover, publish, and manage Agent Skills through the ToolHive + Registry Server +--- + +The Registry server includes a skills catalog that lets you publish, discover, +and manage [Agent Skills](../concepts/skills.mdx) alongside MCP servers. Skills +are exposed through extension endpoints under each registry. + +## Prerequisites + +- A running Registry server with at least one + [managed registry](./configuration.mdx#managed-registry) configured +- For write operations (publish, delete): authentication configured (see + [Authentication configuration](./authentication.mdx)) + +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: + +```bash +curl https://registry.example.com/my-registry/v0.1/x/dev.toolhive/skills +``` + +```json title="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:** + +| Parameter | Type | Default | Description | +| --------- | ------ | ------- | -------------------------------------------------------- | +| `search` | string | - | Filter by 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 | + +### Get a specific skill + +Retrieve the latest version of a skill by namespace and name: + +```bash +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: + +```bash +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: + +```bash +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: + +```bash +curl -X POST \ + https://registry.example.com/my-registry/v0.1/x/dev.toolhive/skills \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer " \ + -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:** + +| Field | Description | +| ------------- | ----------------------------------------------------------- | +| `namespace` | Reverse-DNS ownership scope (e.g., `io.github.acme`) | +| `name` | Skill identifier (e.g., `code-review`) | +| `description` | What the skill does and when to use it | +| `version` | Version string (ideally semantic versioning, e.g., `1.2.0`) | + +For the complete list of optional fields and package types, see the +[skills API reference](../reference/registry-skills-api.mdx#skill-object). + +### 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: + +```bash +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 " +``` + +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](https://agentskills.io/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 + +- Learn about [Agent Skills concepts](../concepts/skills.mdx) and how they + relate to MCP servers +- View the [skills API reference](../reference/registry-skills-api.mdx) for + complete endpoint documentation +- [Configure a managed registry](./configuration.mdx#managed-registry) to enable + skill publishing diff --git a/docs/toolhive/reference/registry-skills-api.mdx b/docs/toolhive/reference/registry-skills-api.mdx new file mode 100644 index 00000000..7c022f56 --- /dev/null +++ b/docs/toolhive/reference/registry-skills-api.mdx @@ -0,0 +1,244 @@ +--- +title: Skills extension API +description: + Reference documentation for the ToolHive Registry Server skills extension + endpoints +--- + +The skills extension API provides endpoints for publishing, discovering, and +managing [Agent Skills](../concepts/skills.mdx) in the ToolHive Registry. These +endpoints are available under the `dev.toolhive` extension namespace. + +## Base path + +All skills endpoints use the following base path: + +```text +/{registryName}/v0.1/x/dev.toolhive/skills +``` + +Where `{registryName}` is the name of the registry as defined in your +[configuration](../guides-registry/configuration.mdx). + +## Endpoints + +### List skills + +```text +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` + +```json +{ + "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 + +```text +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 + +```text +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 + +```text +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 + +```text +POST /{registryName}/v0.1/x/dev.toolhive/skills +``` + +Publishes a new skill version to a managed registry. Requires authentication. + +**Request body:** + +```json +{ + "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 + +```text +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: + +```json +{ "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](../concepts/skills.mdx) -- what skills are and when to + use them +- [Skills catalog guide](../guides-registry/skills.mdx) -- publish and discover + skills step by step diff --git a/sidebars.ts b/sidebars.ts index e1f929d0..5ff0727c 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -199,8 +199,10 @@ const sidebars: SidebarsConfig = { 'toolhive/guides-registry/configuration', 'toolhive/guides-registry/authentication', 'toolhive/guides-registry/database', + 'toolhive/guides-registry/skills', 'toolhive/guides-registry/telemetry-metrics', 'toolhive/reference/registry-api', + 'toolhive/reference/registry-skills-api', 'toolhive/reference/registry-schema-upstream', 'toolhive/reference/registry-schema-toolhive', ], @@ -220,6 +222,7 @@ const sidebars: SidebarsConfig = { 'toolhive/concepts/mcp-primer', 'toolhive/concepts/groups', 'toolhive/concepts/tool-optimization', + 'toolhive/concepts/skills', 'toolhive/concepts/registry-criteria', 'toolhive/concepts/observability', 'toolhive/concepts/auth-framework', From 40918c415a597f1b4cfb65bf9e262d7c5725554b Mon Sep 17 00:00:00 2001 From: Radoslav Dimitrov Date: Tue, 10 Mar 2026 18:04:56 +0200 Subject: [PATCH 2/3] Update docs/toolhive/reference/registry-skills-api.mdx Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/toolhive/reference/registry-skills-api.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/toolhive/reference/registry-skills-api.mdx b/docs/toolhive/reference/registry-skills-api.mdx index 7c022f56..821235a4 100644 --- a/docs/toolhive/reference/registry-skills-api.mdx +++ b/docs/toolhive/reference/registry-skills-api.mdx @@ -49,7 +49,7 @@ Returns a paginated list of skills, showing the latest version of each. "name": "code-review", "description": "Structured code review following OWASP guidelines", "version": "1.2.0", - "status": "ACTIVE", + "status": "active", "title": "Security Code Review", "license": "Apache-2.0", "compatibility": "Requires git", From 0e5e2d6562088660c3f316003e833269046d17b1 Mon Sep 17 00:00:00 2001 From: Radoslav Dimitrov Date: Tue, 10 Mar 2026 18:05:03 +0200 Subject: [PATCH 3/3] Update docs/toolhive/guides-registry/skills.mdx Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/toolhive/guides-registry/skills.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/toolhive/guides-registry/skills.mdx b/docs/toolhive/guides-registry/skills.mdx index fc0a1c7a..fe9e8987 100644 --- a/docs/toolhive/guides-registry/skills.mdx +++ b/docs/toolhive/guides-registry/skills.mdx @@ -38,7 +38,7 @@ curl https://registry.example.com/my-registry/v0.1/x/dev.toolhive/skills "name": "code-review", "description": "Structured code review following OWASP guidelines", "version": "1.2.0", - "status": "ACTIVE", + "status": "active", "title": "Security Code Review", "license": "Apache-2.0" }