From 8938aa5dc4c0725b5ef7b10af4c879612c6fd3e2 Mon Sep 17 00:00:00 2001 From: Radoslav Dimitrov Date: Tue, 10 Mar 2026 14:24:14 +0200 Subject: [PATCH 1/4] Update the registry server documentation Signed-off-by: Radoslav Dimitrov --- docs/toolhive/concepts/skills.mdx | 100 +++++++++++ .../guides-registry/configuration.mdx | 6 +- docs/toolhive/guides-registry/database.mdx | 4 +- docs/toolhive/guides-registry/intro.mdx | 2 + docs/toolhive/guides-registry/skills.mdx | 166 ++++++++++++++++++ sidebars.ts | 2 + 6 files changed, 276 insertions(+), 4 deletions(-) create mode 100644 docs/toolhive/concepts/skills.mdx create mode 100644 docs/toolhive/guides-registry/skills.mdx diff --git a/docs/toolhive/concepts/skills.mdx b/docs/toolhive/concepts/skills.mdx new file mode 100644 index 00000000..94d88e9c --- /dev/null +++ b/docs/toolhive/concepts/skills.mdx @@ -0,0 +1,100 @@ +--- +title: Skills +description: + Understanding skills as reusable instruction sets for AI coding agents, + discoverable through the ToolHive Registry. +--- + +AI coding agents like Claude Code 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, +discover, and install 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](https://agentskills.io/specification). + +Here's a simplified example: + +```markdown title="SKILL.md" +--- +name: lint-fix +description: Find and fix linting errors in a project +version: 1.0.0 +allowed-tools: Read Edit Bash Grep +license: Apache-2.0 +--- + +# Lint fix + +When asked to fix linting errors, follow these steps: + +1. Run the project's linter to identify issues +2. Read each file with errors +3. Fix the errors while preserving the original intent +4. Re-run the linter to verify all issues are resolved +``` + +The frontmatter defines the skill's identity and constraints. The body contains +the actual instructions the AI agent follows. + +## Key properties + +Each skill has the following properties: + +| Property | Description | +| --------------- | ------------------------------------------------------------------ | +| `name` | Identifier in lowercase alphanumeric and hyphens (e.g. `my-skill`) | +| `namespace` | Reverse-DNS owner identifier (e.g. `io.github.user`) | +| `version` | Semantic version or commit hash | +| `description` | Human-readable summary of what the skill does | +| `allowedTools` | List of tools the skill needs (e.g. `Read`, `Edit`, `Bash`) | +| `status` | Lifecycle state: `active`, `deprecated`, or `archived` | +| `license` | SPDX license identifier (e.g. `Apache-2.0`) | +| `compatibility` | Environment requirements or constraints | +| `packages` | Distribution references (OCI artifacts or Git repositories) | + +## 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 are packaged as OCI artifacts for distribution. This means you can push +skills to any OCI-compatible registry (such as GitHub Container Registry) and +reference them by tag or digest, just like container images. + +The ToolHive Registry Server stores skill metadata and makes it searchable +through its API. The actual skill content is fetched from the OCI registry 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 + +- [Manage skills in the Registry Server](../guides-registry/skills.mdx) — + publish, list, and manage skills through the Registry API +- [Registry API reference](../reference/registry-api.mdx) — full endpoint + documentation including skills endpoints diff --git a/docs/toolhive/guides-registry/configuration.mdx b/docs/toolhive/guides-registry/configuration.mdx index 083d328c..ef1eaa26 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: @@ -349,7 +349,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-17} apiVersion: toolhive.stacklok.dev/v1alpha1 kind: MCPServer metadata: @@ -358,6 +358,7 @@ metadata: annotations: toolhive.stacklok.dev/registry-export: 'true' toolhive.stacklok.dev/registry-url: 'https://mcp.example.com/servers/my-mcp-server' + toolhive.stacklok.dev/registry-title: 'Code Analyzer' toolhive.stacklok.dev/registry-description: | Production MCP server for code analysis toolhive.stacklok.dev/tool-definitions: @@ -375,6 +376,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 | Custom display name for the server in registry listings | | `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..01c8c813 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 | | `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..ac830524 100644 --- a/docs/toolhive/guides-registry/intro.mdx +++ b/docs/toolhive/guides-registry/intro.mdx @@ -58,6 +58,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 + [skills](../concepts/skills.mdx) — instruction sets for AI coding agents - **Container-ready**: Designed for deployment in Kubernetes clusters, but can be deployed anywhere - **Flexible deployment**: Works standalone or as part of ToolHive diff --git a/docs/toolhive/guides-registry/skills.mdx b/docs/toolhive/guides-registry/skills.mdx new file mode 100644 index 00000000..f1ef32af --- /dev/null +++ b/docs/toolhive/guides-registry/skills.mdx @@ -0,0 +1,166 @@ +--- +title: Managing skills +description: + How to publish, discover, and manage skills in the ToolHive Registry Server +--- + +The Registry Server provides API endpoints for managing +[skills](../concepts/skills.mdx) — reusable instruction sets for AI coding +agents. You can publish skills to your registry, search for existing skills, and +manage their lifecycle. + +Skills endpoints are available under the extension path +`/{registryName}/v0.1/x/dev.toolhive/skills`. All endpoints require +authentication unless the registry is configured in anonymous mode. + +## List skills + +Retrieve all skills from a registry, with optional filtering and pagination. + +```bash +curl -s "https://REGISTRY_URL/registry/REGISTRY_NAME/v0.1/x/dev.toolhive/skills" \ + -H "Authorization: Bearer TOKEN" | jq +``` + +### Query parameters + +| Parameter | Type | Default | Description | +| --------- | ------- | ------- | ------------------------------------------------------------ | +| `search` | string | - | Filter by name or description substring | +| `status` | string | - | Filter by status (comma-separated, e.g. `active,deprecated`) | +| `limit` | integer | `50` | Maximum results per page (max 100) | +| `cursor` | string | - | Pagination cursor from a previous response | + +The response includes a `metadata` object with `count` (total matching skills) +and `nextCursor` (for pagination). + +### Example: search for skills + +```bash +curl -s "https://REGISTRY_URL/registry/REGISTRY_NAME/v0.1/x/dev.toolhive/skills?search=lint&status=active" \ + -H "Authorization: Bearer TOKEN" | jq +``` + +## Get a skill + +Retrieve the latest version of a specific skill by namespace and name. + +```bash +curl -s "https://REGISTRY_URL/registry/REGISTRY_NAME/v0.1/x/dev.toolhive/skills/NAMESPACE/SKILL_NAME" \ + -H "Authorization: Bearer TOKEN" | jq +``` + +For example, to get the latest version of a skill named `lint-fix` in the +`io.github.user` namespace: + +```bash +curl -s "https://REGISTRY_URL/registry/my-registry/v0.1/x/dev.toolhive/skills/io.github.user/lint-fix" \ + -H "Authorization: Bearer TOKEN" | jq +``` + +## List skill versions + +Retrieve all published versions of a skill. + +```bash +curl -s "https://REGISTRY_URL/registry/REGISTRY_NAME/v0.1/x/dev.toolhive/skills/NAMESPACE/SKILL_NAME/versions" \ + -H "Authorization: Bearer TOKEN" | jq +``` + +## Get a specific version + +Retrieve a specific version of a skill. + +```bash +curl -s "https://REGISTRY_URL/registry/REGISTRY_NAME/v0.1/x/dev.toolhive/skills/NAMESPACE/SKILL_NAME/versions/VERSION" \ + -H "Authorization: Bearer TOKEN" | jq +``` + +## Publish a skill + +Publish a new skill version to a managed registry. The request body is a JSON +object containing the skill metadata. + +```bash +curl -X POST "https://REGISTRY_URL/registry/REGISTRY_NAME/v0.1/x/dev.toolhive/skills" \ + -H "Authorization: Bearer TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "namespace": "io.github.user", + "name": "lint-fix", + "title": "Lint Fixer", + "description": "Find and fix linting errors in a project", + "version": "1.0.0", + "status": "active", + "license": "Apache-2.0", + "allowedTools": ["Read", "Edit", "Bash", "Grep"], + "packages": [ + { + "registryType": "oci", + "identifier": "ghcr.io/user/skills/lint-fix", + "ref": "1.0.0", + "digest": "sha256:abc123..." + } + ], + "repository": { + "type": "git", + "url": "https://github.com/user/my-skills" + } + }' +``` + +A successful publish returns a `201 Created` response. + +### Skill fields + +| Field | Type | Required | Description | +| --------------- | -------- | -------- | --------------------------------------------------------- | +| `namespace` | string | Yes | Reverse-DNS owner identifier (e.g. `io.github.user`) | +| `name` | string | Yes | Skill identifier (lowercase alphanumeric and hyphens) | +| `version` | string | Yes | Semantic version or commit hash | +| `title` | string | No | Human-readable display name | +| `description` | string | No | Summary of what the skill does | +| `status` | string | No | `active` (default), `deprecated`, or `archived` | +| `license` | string | No | SPDX license identifier | +| `compatibility` | string | No | Environment requirements | +| `allowedTools` | string[] | No | Tools the skill needs (experimental) | +| `packages` | array | No | Distribution references (see [Packages](#packages) below) | +| `repository` | object | No | Source repository (`type` and `url`) | +| `icons` | array | No | Icon references (`src`, `type`, `size`, `label`) | +| `metadata` | object | No | Skill metadata from the SKILL.md frontmatter | +| `_meta` | object | No | Opaque extended metadata | + +### Packages + +Each package entry describes where the skill artifact is distributed. + +| Field | Type | Description | +| -------------- | ------ | ------------------------------------------------ | +| `registryType` | string | Distribution type: `oci` or `git` | +| `identifier` | string | OCI identifier (e.g. `ghcr.io/user/skills/name`) | +| `ref` | string | Tag or branch reference | +| `url` | string | Direct URL to the package | +| `commit` | string | Git commit SHA | +| `subfolder` | string | Subfolder within the repository | +| `digest` | string | Content digest for integrity verification | +| `mediaType` | string | Media type of the package | + +## Delete a skill version + +Delete a specific version of a skill from a managed registry. + +```bash +curl -X DELETE "https://REGISTRY_URL/registry/REGISTRY_NAME/v0.1/x/dev.toolhive/skills/NAMESPACE/SKILL_NAME/versions/VERSION" \ + -H "Authorization: Bearer TOKEN" +``` + +A successful delete returns a `204 No Content` response. + +## Next steps + +- [Skills concept](../concepts/skills.mdx) — understand what skills are and how + they fit into the ToolHive ecosystem +- [Registry API reference](../reference/registry-api.mdx) — full OpenAPI + documentation for all registry endpoints +- [Authentication configuration](./authentication.mdx) — configure access + control for your registry diff --git a/sidebars.ts b/sidebars.ts index e1f929d0..ab4c8921 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -200,6 +200,7 @@ const sidebars: SidebarsConfig = { 'toolhive/guides-registry/authentication', 'toolhive/guides-registry/database', 'toolhive/guides-registry/telemetry-metrics', + 'toolhive/guides-registry/skills', 'toolhive/reference/registry-api', 'toolhive/reference/registry-schema-upstream', 'toolhive/reference/registry-schema-toolhive', @@ -220,6 +221,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 ed9aa9258642f984f097a18ab9f86460f0c557dc Mon Sep 17 00:00:00 2001 From: Radoslav Dimitrov Date: Tue, 10 Mar 2026 14:28:40 +0200 Subject: [PATCH 2/4] Apply docs-review feedback Signed-off-by: Radoslav Dimitrov --- docs/toolhive/concepts/skills.mdx | 51 +++++++------------ .../guides-registry/configuration.mdx | 2 +- docs/toolhive/guides-registry/intro.mdx | 4 +- docs/toolhive/guides-registry/skills.mdx | 8 +++ 4 files changed, 30 insertions(+), 35 deletions(-) diff --git a/docs/toolhive/concepts/skills.mdx b/docs/toolhive/concepts/skills.mdx index 94d88e9c..e65e38f7 100644 --- a/docs/toolhive/concepts/skills.mdx +++ b/docs/toolhive/concepts/skills.mdx @@ -5,17 +5,17 @@ description: discoverable through the ToolHive Registry. --- -AI coding agents like Claude Code 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. +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, -discover, and install them from a central location. +The ToolHive Registry Server provides a catalog for skills, so you can publish +and discover them from a central location. ## What is a skill? @@ -23,45 +23,30 @@ 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](https://agentskills.io/specification). -Here's a simplified example: +Here's a simplified example showing the frontmatter: ```markdown title="SKILL.md" --- -name: lint-fix -description: Find and fix linting errors in a project +name: code-review +description: Review pull requests for correctness and style version: 1.0.0 -allowed-tools: Read Edit Bash Grep +allowed-tools: Read Grep Glob license: Apache-2.0 --- -# Lint fix - -When asked to fix linting errors, follow these steps: - -1. Run the project's linter to identify issues -2. Read each file with errors -3. Fix the errors while preserving the original intent -4. Re-run the linter to verify all issues are resolved +Instructions for the AI agent go here... ``` -The frontmatter defines the skill's identity and constraints. The body contains -the actual instructions the AI agent follows. +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 has the following properties: - -| Property | Description | -| --------------- | ------------------------------------------------------------------ | -| `name` | Identifier in lowercase alphanumeric and hyphens (e.g. `my-skill`) | -| `namespace` | Reverse-DNS owner identifier (e.g. `io.github.user`) | -| `version` | Semantic version or commit hash | -| `description` | Human-readable summary of what the skill does | -| `allowedTools` | List of tools the skill needs (e.g. `Read`, `Edit`, `Bash`) | -| `status` | Lifecycle state: `active`, `deprecated`, or `archived` | -| `license` | SPDX license identifier (e.g. `Apache-2.0`) | -| `compatibility` | Environment requirements or constraints | -| `packages` | Distribution references (OCI artifacts or Git repositories) | +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](../guides-registry/skills.mdx#skill-fields). ## Skills and MCP servers diff --git a/docs/toolhive/guides-registry/configuration.mdx b/docs/toolhive/guides-registry/configuration.mdx index ef1eaa26..2839004a 100644 --- a/docs/toolhive/guides-registry/configuration.mdx +++ b/docs/toolhive/guides-registry/configuration.mdx @@ -375,8 +375,8 @@ 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 | Custom display name for the server in registry listings | +| `toolhive.stacklok.dev/registry-description` | Yes | Description text displayed in registry listings | | `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/intro.mdx b/docs/toolhive/guides-registry/intro.mdx index ac830524..bb4b78af 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 @@ -104,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) in your registry - [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 index f1ef32af..a12a9f81 100644 --- a/docs/toolhive/guides-registry/skills.mdx +++ b/docs/toolhive/guides-registry/skills.mdx @@ -13,6 +13,14 @@ Skills endpoints are available under the extension path `/{registryName}/v0.1/x/dev.toolhive/skills`. All endpoints require authentication unless the registry is configured in anonymous mode. +:::info[Managed registry required for write operations] + +Publishing and deleting skills requires a +[managed registry](./configuration.mdx#managed-registry). Read operations (list, +get) work with all registry types. + +::: + ## List skills Retrieve all skills from a registry, with optional filtering and pagination. From 82dce067408dcc2d05942ace5856b8bec78db51d Mon Sep 17 00:00:00 2001 From: Radoslav Dimitrov Date: Tue, 10 Mar 2026 14:35:59 +0200 Subject: [PATCH 3/4] Fix skills distribution docs Signed-off-by: Radoslav Dimitrov --- docs/toolhive/concepts/skills.mdx | 11 ++++++----- docs/toolhive/guides-registry/skills.mdx | 2 +- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/toolhive/concepts/skills.mdx b/docs/toolhive/concepts/skills.mdx index e65e38f7..b2798107 100644 --- a/docs/toolhive/concepts/skills.mdx +++ b/docs/toolhive/concepts/skills.mdx @@ -60,13 +60,14 @@ tool. ## Distribution -Skills are packaged as OCI artifacts for distribution. This means you can push -skills to any OCI-compatible registry (such as GitHub Container Registry) and -reference them by tag or digest, just like container images. +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 OCI registry when -a skill is installed. +through its API. The actual skill content is fetched from the package source +when a skill is installed. ## Lifecycle diff --git a/docs/toolhive/guides-registry/skills.mdx b/docs/toolhive/guides-registry/skills.mdx index a12a9f81..9da4cd41 100644 --- a/docs/toolhive/guides-registry/skills.mdx +++ b/docs/toolhive/guides-registry/skills.mdx @@ -127,7 +127,7 @@ A successful publish returns a `201 Created` response. | `name` | string | Yes | Skill identifier (lowercase alphanumeric and hyphens) | | `version` | string | Yes | Semantic version or commit hash | | `title` | string | No | Human-readable display name | -| `description` | string | No | Summary of what the skill does | +| `description` | string | Yes | Summary of what the skill does | | `status` | string | No | `active` (default), `deprecated`, or `archived` | | `license` | string | No | SPDX license identifier | | `compatibility` | string | No | Environment requirements | From 091c7b15915fc662e2de92e4216adc89a0ce57e0 Mon Sep 17 00:00:00 2001 From: Radoslav Dimitrov Date: Tue, 10 Mar 2026 14:57:50 +0200 Subject: [PATCH 4/4] Address copilot feedback Signed-off-by: Radoslav Dimitrov --- docs/toolhive/concepts/skills.mdx | 8 ++++++++ docs/toolhive/guides-registry/skills.mdx | 2 +- 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/toolhive/concepts/skills.mdx b/docs/toolhive/concepts/skills.mdx index b2798107..b3027da9 100644 --- a/docs/toolhive/concepts/skills.mdx +++ b/docs/toolhive/concepts/skills.mdx @@ -40,6 +40,14 @@ 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. +:::note + +The SKILL.md frontmatter uses kebab-case keys (e.g. `allowed-tools`) per the +[Agent Skills specification](https://agentskills.io/specification), while the +Registry API uses camelCase (e.g. `allowedTools`). + +::: + ## Key properties Each skill is identified by a `namespace` (reverse-DNS format, e.g. diff --git a/docs/toolhive/guides-registry/skills.mdx b/docs/toolhive/guides-registry/skills.mdx index 9da4cd41..17fcd96c 100644 --- a/docs/toolhive/guides-registry/skills.mdx +++ b/docs/toolhive/guides-registry/skills.mdx @@ -10,7 +10,7 @@ agents. You can publish skills to your registry, search for existing skills, and manage their lifecycle. Skills endpoints are available under the extension path -`/{registryName}/v0.1/x/dev.toolhive/skills`. All endpoints require +`/registry/{registryName}/v0.1/x/dev.toolhive/skills`. All endpoints require authentication unless the registry is configured in anonymous mode. :::info[Managed registry required for write operations]