Skip to content

Commit d55a2f9

Browse files
JAORMXclaudeaponcedeleonch
authored
Add agent skills management documentation (#656)
* Add agent skills management documentation Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Address review feedback on skills documentation Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Address PR feedback on skills docs Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Co-authored-by: Alejandro Ponce <aponcedeleonch@stacklok.com>
1 parent ba07b88 commit d55a2f9

9 files changed

Lines changed: 517 additions & 77 deletions

File tree

‎docs/toolhive/concepts/skills.mdx‎

Lines changed: 86 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,10 @@ configuration that teaches an AI agent how to perform a specific task. If MCP
1010
servers provide **tools** (the raw capabilities an agent can call), skills
1111
provide the **knowledge** of when, why, and how to use those tools effectively.
1212

13+
Skills follow the [Agent Skills](https://agentskills.io/) specification, an open
14+
standard supported by a growing number of AI coding agents including Claude
15+
Code, GitHub Copilot, Cursor, OpenCode, and many others.
16+
1317
## When you would use skills
1418

1519
Consider these scenarios:
@@ -35,47 +39,71 @@ flowchart LR
3539
Skill["Skill\n(workflow + prompts)"] -->|references| MCP["MCP Server(s)\n(raw tools)"]
3640
```
3741

38-
Skills are stored in the same Registry server instance as MCP servers, but under
39-
a separate extensions API path (`/{registryName}/v0.1/x/dev.toolhive/skills`,
40-
where `{registryName}` is the name of your registry). They are not intermixed
41-
with MCP server entries.
42+
When you publish skills to the ToolHive Registry for team-wide discovery, they
43+
are stored under a separate extensions API path
44+
(`/{registryName}/v0.1/x/dev.toolhive/skills`, where `{registryName}` is the
45+
name of your registry). They are not intermixed with MCP server entries.
4246

4347
## Skill structure
4448

45-
Each skill has the following core fields:
49+
A skill is a directory containing a `SKILL.md` file (required) plus optional
50+
supporting files:
4651

47-
| Field | Required | Description |
48-
| ------------- | -------- | ------------------------------------------------------------------- |
49-
| `namespace` | Yes | Reverse-DNS identifier (e.g., `io.github.acme`) |
50-
| `name` | Yes | Skill identifier in kebab-case (e.g., `code-review`) |
51-
| `description` | Yes | Human-readable summary of what the skill does |
52-
| `version` | Yes | Semantic version or commit hash (e.g., `1.0.0`) |
53-
| `status` | No | One of `ACTIVE`, `DEPRECATED`, or `ARCHIVED` (defaults to `ACTIVE`) |
54-
| `title` | No | Human-friendly display name |
55-
| `license` | No | SPDX license identifier (e.g., `Apache-2.0`) |
52+
```text
53+
my-skill/
54+
├── SKILL.md # Required: metadata + instructions
55+
├── scripts/ # Optional: executable code
56+
├── references/ # Optional: documentation
57+
└── assets/ # Optional: templates, resources
58+
```
5659

57-
Skills also support optional fields for packages (OCI or Git references), icons,
58-
repository metadata, allowed tools, compatibility requirements, and arbitrary
59-
metadata.
60+
The `SKILL.md` file contains YAML frontmatter with metadata followed by Markdown
61+
instructions that the AI agent reads when the skill is activated.
6062

61-
### Naming conventions
63+
### SKILL.md frontmatter
6264

63-
- **Namespace**: Use reverse-DNS notation. For example, `io.github.your-org` or
64-
`com.example.team`. This prevents naming collisions across organizations.
65-
- **Name**: Use kebab-case identifiers. For example, `code-review`,
66-
`deploy-checker`, `security-scan`.
67-
- **Version**: Use semantic versioning (e.g., `1.0.0`, `2.1.3`) or a commit
68-
hash. The registry tracks a "latest" pointer per namespace/name pair.
65+
| Field | Required | Description |
66+
| --------------- | -------- | ----------------------------------------------------- |
67+
| `name` | Yes | Lowercase letters, numbers, and hyphens (2-64 chars). |
68+
| | | Must match the directory name. |
69+
| `description` | Yes | What the skill does and when to use it (max 1024 |
70+
| | | chars). |
71+
| `license` | No | SPDX license identifier (e.g., `Apache-2.0`). |
72+
| `compatibility` | No | Environment requirements (max 500 chars). |
73+
| `metadata` | No | Arbitrary key-value pairs. |
74+
| `allowed-tools` | No | List of pre-approved tools. |
75+
| `version` | No | Semantic version (e.g., `1.0.0`). ToolHive extension; |
76+
| | | the base spec uses `metadata` for versioning. |
77+
78+
Example:
79+
80+
```yaml title="SKILL.md"
81+
---
82+
name: code-review
83+
description: >-
84+
Performs structured code reviews using best practices. Use when reviewing pull
85+
requests or code changes.
86+
version: 1.0.0
87+
license: Apache-2.0
88+
---
89+
```
90+
91+
For the complete format specification, see
92+
[agentskills.io/specification](https://agentskills.io/specification).
6993

70-
**Valid examples:**
94+
### Naming conventions
7195

72-
- `io.github.acme/code-review` version `1.0.0`
73-
- `com.example.platform/deploy-checker` version `0.3.1`
96+
- **Name**: Use kebab-case identifiers. For example, `code-review`,
97+
`deploy-checker`, `security-scan`. The name must match the parent directory
98+
name.
99+
- **Version**: Use semantic versioning (e.g., `1.0.0`, `2.1.3`).
74100

75-
**Invalid examples:**
101+
When publishing skills to a ToolHive Registry Server, additional fields apply:
76102

77-
- `acme/Code Review` (namespace must be reverse-DNS, name must be kebab-case)
78-
- Empty namespace or name (both are required)
103+
- **Namespace**: Use reverse-DNS notation (e.g., `io.github.your-org`). This
104+
prevents naming collisions across organizations.
105+
- **Version**: Required when publishing to the registry.
106+
- **Status**: One of `active`, `deprecated`, or `archived` (case insensitive).
79107

80108
### Package types
81109

@@ -95,19 +123,36 @@ an older version does not change the latest pointer.
95123
You can retrieve a specific version or request `latest` to get the most recent
96124
one.
97125

98-
## Current status and what's next
126+
## How skills are discovered
127+
128+
AI agents discover skills by reading from their skills directories. When you
129+
install a skill with the ToolHive CLI, the `SKILL.md` file is written to the
130+
appropriate directory for your AI client. The agent loads the skill's `name` and
131+
`description` at startup, and activates the full instructions when a task
132+
matches.
133+
134+
Skills support two installation scopes:
135+
136+
- **User scope**: Available across all your projects (installed to your home
137+
directory)
138+
- **Project scope**: Available only in a specific project (installed to the
139+
project directory)
140+
141+
## Distribution
99142

100-
The skills API is available as an extension endpoint on the Registry server
101-
(`/{registryName}/v0.1/x/dev.toolhive/skills`). You can publish, list, search,
102-
retrieve, and delete skills through this API.
143+
Skills can be distributed as:
103144

104-
Skill installation via agent clients (such as the ToolHive CLI or IDE
105-
extensions) is planned for a future release. For now, the registry serves as a
106-
discovery and distribution layer where you can browse available skills and
107-
retrieve their package references.
145+
- **OCI artifacts**: Packaged as container registry artifacts for versioned
146+
distribution through registries like GitHub Container Registry
147+
- **Git repositories**: Referenced by URL with optional branch/tag and subfolder
148+
- **Registry entries**: Published to a ToolHive Registry Server for centralized
149+
discovery and installation by name
108150

109151
## Next steps
110152

111-
- [Manage skills](../guides-registry/skills.mdx) through the Registry server API
112-
- [Registry server introduction](../guides-registry/intro.mdx) for an overview
113-
of the Registry server
153+
- [Manage agent skills](../guides-cli/skills-management.mdx) with the ToolHive
154+
CLI
155+
- [Manage skills in the registry](../guides-registry/skills.mdx) through the
156+
Registry Server API
157+
- [Agent Skills specification](https://agentskills.io/specification) for the
158+
complete format reference

‎docs/toolhive/guides-cli/client-configuration.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -150,6 +150,8 @@ ToolHive provides.
150150

151151
## Next steps
152152

153+
- [Manage agent skills](./skills-management.mdx) to install reusable skills for
154+
your AI clients
153155
- [Set up custom permissions](./custom-permissions.mdx) to control filesystem
154156
and network access for your servers
155157
- [Secure your servers](./auth.mdx) with OIDC authentication and Cedar policies

‎docs/toolhive/guides-cli/index.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,8 @@ both installed.
3232
`thv` and run your first MCP server in minutes.
3333
- **Already installed?** Jump to [Run MCP servers](./run-mcp-servers.mdx) to
3434
start managing servers from the command line.
35+
- **Managing agent skills?** See [Manage agent skills](./skills-management.mdx)
36+
to install and publish reusable skills.
3537
- **Building or automating?** See advanced workflows for [auth](./auth.mdx),
3638
[CI/CD](./advanced-cicd.mdx), [container builds](./build-containers.mdx), and
3739
more.

0 commit comments

Comments
 (0)