diff --git a/docs/toolhive/concepts/skills.mdx b/docs/toolhive/concepts/skills.mdx new file mode 100644 index 00000000..2149c2bd --- /dev/null +++ b/docs/toolhive/concepts/skills.mdx @@ -0,0 +1,113 @@ +--- +title: Understanding skills +description: + Learn what skills are in ToolHive, why they exist, and how they relate to MCP + servers. +--- + +A **skill** is a reusable, versioned bundle of instructions, prompts, and +configuration that teaches an AI agent how to perform a specific task. If MCP +servers provide **tools** (the raw capabilities an agent can call), skills +provide the **knowledge** of when, why, and how to use those tools effectively. + +## When you would use skills + +Consider these scenarios: + +- **You maintain a shared MCP registry** and want teams to publish reusable + prompt bundles alongside the MCP servers they connect to, so that other + engineers can discover both the tooling and the expertise in one place. +- **You build internal developer tools** and want to package a "code review" + workflow that combines multiple MCP server calls with domain-specific + instructions, then distribute it through a central catalog. +- **You run a platform team** and want to curate a set of approved skills that + your organization's AI agents can use, with clear versioning and status + tracking. + +## How skills relate to MCP servers + +MCP servers expose tools; skills consume them. A skill might reference one or +more tools from one or more MCP servers, wrapping them in a higher-level +workflow with context-specific instructions. + +```mermaid +flowchart LR + Skill["Skill\n(workflow + prompts)"] -->|references| MCP["MCP Server(s)\n(raw tools)"] +``` + +Skills are stored in the same Registry server instance as MCP servers, but under +a separate extensions API path (`/{registryName}/v0.1/x/dev.toolhive/skills`, +where `{registryName}` is the name of your registry). They are not intermixed +with MCP server entries. + +## Skill structure + +Each skill has the following core fields: + +| Field | Required | Description | +| ------------- | -------- | ------------------------------------------------------------------- | +| `namespace` | Yes | Reverse-DNS identifier (e.g., `io.github.acme`) | +| `name` | Yes | Skill identifier in kebab-case (e.g., `code-review`) | +| `description` | Yes | Human-readable summary of what the skill does | +| `version` | Yes | Semantic version or commit hash (e.g., `1.0.0`) | +| `status` | No | One of `ACTIVE`, `DEPRECATED`, or `ARCHIVED` (defaults to `ACTIVE`) | +| `title` | No | Human-friendly display name | +| `license` | No | SPDX license identifier (e.g., `Apache-2.0`) | + +Skills also support optional fields for packages (OCI or Git references), icons, +repository metadata, allowed tools, compatibility requirements, and arbitrary +metadata. + +### Naming conventions + +- **Namespace**: Use reverse-DNS notation. For example, `io.github.your-org` or + `com.example.team`. This prevents naming collisions across organizations. +- **Name**: Use kebab-case identifiers. For example, `code-review`, + `deploy-checker`, `security-scan`. +- **Version**: Use semantic versioning (e.g., `1.0.0`, `2.1.3`) or a commit + hash. The registry tracks a "latest" pointer per namespace/name pair. + +**Valid examples:** + +- `io.github.acme/code-review` version `1.0.0` +- `com.example.platform/deploy-checker` version `0.3.1` + +**Invalid examples:** + +- `acme/Code Review` (namespace must be reverse-DNS, name must be kebab-case) +- Empty namespace or name (both are required) + +### Package types + +Skills can reference distribution packages in two formats: + +- **OCI**: Container registry references with an identifier, digest, and media + type +- **Git**: Repository references with a URL, ref, commit, and optional subfolder + +## Versioning + +The registry stores multiple versions of each skill and maintains a "latest" +pointer. When you publish a new version, the registry automatically updates the +latest pointer if the new version is newer than the current latest. Publishing +an older version does not change the latest pointer. + +You can retrieve a specific version or request `latest` to get the most recent +one. + +## Current status and what's next + +The skills API is available as an extension endpoint on the Registry server +(`/{registryName}/v0.1/x/dev.toolhive/skills`). You can publish, list, search, +retrieve, and delete skills through this API. + +Skill installation via agent clients (such as the ToolHive CLI or IDE +extensions) is planned for a future release. For now, the registry serves as a +discovery and distribution layer where you can browse available skills and +retrieve their package references. + +## Next steps + +- [Manage skills](../guides-registry/skills.mdx) through the Registry server API +- [Registry server introduction](../guides-registry/intro.mdx) for an overview + of the Registry server diff --git a/docs/toolhive/guides-registry/configuration.mdx b/docs/toolhive/guides-registry/configuration.mdx index 083d328c..ebd9bae1 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: @@ -297,6 +297,7 @@ registries: - `DELETE /{registryName}/v0.1/servers/{name}/versions/{version}` - Delete versions - `GET` operations for listing and retrieving servers +- [Skills management](./skills.mdx) via the extensions API See the [Registry API reference](../reference/registry-api.mdx) for complete endpoint documentation and request/response examples. @@ -357,6 +358,7 @@ metadata: namespace: toolhive-system annotations: toolhive.stacklok.dev/registry-export: 'true' + toolhive.stacklok.dev/registry-title: 'Code Analysis Server' toolhive.stacklok.dev/registry-url: 'https://mcp.example.com/servers/my-mcp-server' toolhive.stacklok.dev/registry-description: | Production MCP server for code analysis @@ -375,6 +377,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 for the registry entry (overrides the generated name) | | `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/index.mdx b/docs/toolhive/guides-registry/index.mdx index 15ce6288..cd771ac8 100644 --- a/docs/toolhive/guides-registry/index.mdx +++ b/docs/toolhive/guides-registry/index.mdx @@ -2,7 +2,7 @@ title: ToolHive Registry Server description: How-to guides for using the ToolHive Registry Server to discover and access - MCP servers. + MCP servers and skills. --- import DocCardList from '@theme/DocCardList'; diff --git a/docs/toolhive/guides-registry/intro.mdx b/docs/toolhive/guides-registry/intro.mdx index 431a8a70..b096652a 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 + skills --- The ToolHive Registry server is a standards-compliant implementation of the MCP @@ -66,6 +67,8 @@ flowchart LR status persistence - **Kubernetes-aware**: Automatic discovery of MCP servers deployed via ToolHive Operator +- **Skills registry**: Publish and discover reusable + [skills](../concepts/skills.mdx) through the extensions API ## Registry sources @@ -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 +- [Manage skills](./skills.mdx) to publish and discover reusable skills - [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..850c2e72 --- /dev/null +++ b/docs/toolhive/guides-registry/skills.mdx @@ -0,0 +1,202 @@ +--- +title: Manage skills +description: + How to publish, list, retrieve, and delete skills using the ToolHive Registry + server extensions API. +--- + +The Registry server provides an extensions API for managing +[skills](../concepts/skills.mdx). This guide covers the full lifecycle: +publishing, listing, retrieving, and deleting skills. + +## Prerequisites + +- A running Registry server with at least one **managed** registry configured + (skills can only be published to managed registries) +- `curl` or another HTTP client +- If authentication is enabled, a valid bearer token (see + [Authentication](./authentication.mdx)) + +## API base path + +All skills endpoints use the following base path: + +```text +/{registryName}/v0.1/x/dev.toolhive/skills +``` + +Replace `{registryName}` with the `name` of the registry as defined in your +[configuration file](./configuration.mdx) (for example, `my-registry` if your +config has `registries: [{name: my-registry, ...}]`). + +## Publish a skill + +To publish a new skill version, send a `POST` request with the skill metadata: + +```bash title="Publish a skill" +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": "Performs structured code reviews using best practices", + "version": "1.0.0", + "status": "active", + "title": "Code Review Assistant", + "license": "Apache-2.0", + "packages": [ + { + "registryType": "git", + "url": "https://github.com/acme/skills", + "ref": "v1.0.0", + "subfolder": "code-review" + } + ], + "repository": { + "url": "https://github.com/acme/skills", + "type": "git" + } + }' +``` + +**Required fields:** `namespace`, `name`, `description`, `version` + +A successful response returns `201 Created` with the published skill. If the +version already exists, the server returns `409 Conflict`. + +The `status` field accepts `active`, `deprecated`, or `archived` (case +insensitive). The server normalizes status values to uppercase internally. + +### Versioning behavior + +When you publish a new version, the registry compares it against the current +latest version. If the new version is newer, the latest pointer updates +automatically. Publishing an older version (for example, backfilling `0.9.0` +after `1.0.0` exists) does not change the latest pointer. + +## List skills + +To list skills in a registry: + +```bash title="List all skills" +curl https://registry.example.com/my-registry/v0.1/x/dev.toolhive/skills +``` + +### Query parameters + +| Parameter | Type | Default | Description | +| --------- | ------ | ------- | -------------------------------------------------- | +| `search` | string | - | Filter by name or description substring | +| `status` | string | - | Filter by status (comma-separated, e.g., `active`) | +| `limit` | int | 50 | Maximum results per page (1-100) | +| `cursor` | string | - | Pagination cursor from a previous response | + +### Search example + +```bash title="Search for skills by keyword" +curl "https://registry.example.com/my-registry/v0.1/x/dev.toolhive/skills?search=review&limit=10" +``` + +### Response format + +```json +{ + "skills": [ + { + "namespace": "io.github.acme", + "name": "code-review", + "description": "Performs structured code reviews using best practices", + "version": "1.0.0", + "status": "ACTIVE", + "title": "Code Review Assistant", + "license": "Apache-2.0", + "packages": [ + { + "registryType": "git", + "url": "https://github.com/acme/skills", + "ref": "v1.0.0", + "subfolder": "code-review" + } + ], + "repository": { + "url": "https://github.com/acme/skills", + "type": "git" + } + } + ], + "metadata": { + "count": 1, + "nextCursor": "" + } +} +``` + +Use the `nextCursor` value to fetch the next page of results. An empty +`nextCursor` indicates there are no more pages. + +## Retrieve a skill + +### Get the latest version + +```bash title="Get the latest version of a skill" +curl https://registry.example.com/my-registry/v0.1/x/dev.toolhive/skills/io.github.acme/code-review +``` + +### Get a specific version + +```bash title="Get a specific version" +curl https://registry.example.com/my-registry/v0.1/x/dev.toolhive/skills/io.github.acme/code-review/versions/1.0.0 +``` + +### List all versions + +```bash title="List all versions of a skill" +curl https://registry.example.com/my-registry/v0.1/x/dev.toolhive/skills/io.github.acme/code-review/versions +``` + +## Delete a skill version + +To delete a specific version: + +```bash title="Delete a skill version" +curl -X DELETE \ + https://registry.example.com/my-registry/v0.1/x/dev.toolhive/skills/io.github.acme/code-review/versions/1.0.0 \ + -H "Authorization: Bearer " +``` + +A successful delete returns `204 No Content`. Deleting a non-existent version +returns `404 Not Found`. + +:::warning + +Deleting a skill version is permanent. If the deleted version was the latest, +the latest pointer is not automatically reassigned to a previous version. + +::: + +## Error responses + +The API returns standard HTTP status codes: + +| Code | Meaning | +| ---- | ------------------------------------------------------------- | +| 400 | Invalid request (missing required fields, invalid parameters) | +| 401 | Authentication required | +| 403 | Registry is not a managed registry (read-only registries) | +| 404 | Registry, skill, or version not found | +| 409 | Version already exists | +| 500 | Internal server error | + +## What's next + +Skill installation via agent clients (such as the ToolHive CLI or IDE +extensions) is planned for a future release. For now, the registry serves as a +discovery and distribution layer. + +- [Understanding skills](../concepts/skills.mdx) for background on the skills + model +- [Registry server introduction](./intro.mdx) for an overview of the Registry + server +- [Authentication](./authentication.mdx) for configuring API access diff --git a/sidebars.ts b/sidebars.ts index f10a18bf..fbc9dc83 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -187,7 +187,7 @@ const sidebars: SidebarsConfig = { type: 'category', label: 'Registry Server', description: - 'How to deploy and use the ToolHive Registry server to discover and access MCP servers', + 'How to deploy and use the ToolHive Registry server to discover and access MCP servers and skills', link: { type: 'doc', id: 'toolhive/guides-registry/index', @@ -200,6 +200,7 @@ 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-schema-upstream', @@ -227,6 +228,7 @@ const sidebars: SidebarsConfig = { 'toolhive/concepts/cedar-policies', 'toolhive/concepts/backend-auth', 'toolhive/concepts/vmcp', + 'toolhive/concepts/skills', ], },