Document skills feature and update registry server docs for v0.6.3 #601
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,94 @@ | ||
| --- | ||
| title: Skills | ||
| description: | ||
| Understanding skills as reusable instruction sets for AI coding agents, | ||
| discoverable through the ToolHive Registry. | ||
| --- | ||
|
|
||
| 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](https://agentskills.io/specification). | ||
|
|
||
| Here's a simplified example showing the frontmatter: | ||
|
|
||
| ```markdown title="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. | ||
|
|
||
| :::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`). | ||
|
|
||
| ::: | ||
|
Comment on lines
+43
to
+49
Collaborator
There was a problem hiding this comment. This feels more like a "how" than a concept. |
||
|
|
||
| ## 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](../guides-registry/skills.mdx#skill-fields). | ||
|
|
||
| ## 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 | ||
|
|
||
| - [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 | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,174 @@ | ||||||
| --- | ||||||
| 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 | ||||||
| `/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] | ||||||
|
|
||||||
| 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. | ||||||
|
|
||||||
| ```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 | 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 | | ||||||
| | `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 | ||||||
|
Collaborator
There was a problem hiding this comment.
Suggested change
|
||||||
| 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 | ||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.