Document skills feature and update registry server docs for v0.6.3#601
Document skills feature and update registry server docs for v0.6.3#601
Conversation
Signed-off-by: Radoslav Dimitrov <radoslav@stacklok.com>
Signed-off-by: Radoslav Dimitrov <radoslav@stacklok.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
There was a problem hiding this comment.
Pull request overview
This PR expands the ToolHive documentation to introduce the new skills concept and document how to manage skills via the Registry Server API, while also updating related Registry Server docs and navigation for the v0.6.3 release.
Changes:
- Adds new docs pages for Skills (concept) and Managing skills (Registry Server guide) and wires them into the sidebar.
- Updates Registry Server intro to reference skills and links to the new guide.
- Updates Registry Server docs for
maxMetaSizedefault (64KB → 256KB) and documents the newtoolhive.stacklok.dev/registry-titleannotation.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| sidebars.ts | Adds the new Skills pages to the Registry Server and Concepts sidebars. |
| docs/toolhive/guides-registry/skills.mdx | New guide documenting skills API endpoints (list/get/publish/delete). |
| docs/toolhive/guides-registry/intro.mdx | Mentions skills as a Registry Server feature and links to the new guide. |
| docs/toolhive/guides-registry/database.mdx | Updates documented maxMetaSize default to 262144 bytes. |
| docs/toolhive/guides-registry/configuration.mdx | Updates maxMetaSize default and adds registry-title annotation docs. |
| docs/toolhive/concepts/skills.mdx | New concept page explaining what skills are and how they fit in the ecosystem. |
Signed-off-by: Radoslav Dimitrov <radoslav@stacklok.com>
rdimitrov
force-pushed
the
bump-docs-registry
branch
from
3f7443b to
82dce06
Compare
Signed-off-by: Radoslav Dimitrov <radoslav@stacklok.com>
There was a problem hiding this comment.
The PR successfully introduces the concepts and API mechanics of skills, but both new pages leave users without a clear picture of the end-to-end workflow. The concept page explains what a skill is but not why someone would use the registry (vs. just sharing files). The guide page is effectively an API reference dressed as a how-to, and critically, the consumer side of the story — how someone actually installs and uses a skill once it's in the registry — is completely absent.
Primary issues
1. Missing consumer workflow — "then what?"
The guide covers the publisher side: list, get, publish, delete. But a reader's natural follow-up question is: "OK, I've published my skill to the registry — now how does someone else actually get it and use it?"
The ## Distribution section in the concept page gestures at OCI artifacts and Git repos, but never closes the loop. "The actual skill content is fetched from the package source when a skill is installed" — installed by what? Is there a CLI command? Does a coding agent IDE extension pull from the registry? Is there a ToolHive client command?
Before merging, confirm the consumption workflow and add at minimum one sentence explaining how skills are actually used once published. If the tooling for consumption isn't ready yet, say so explicitly — "skill installation via the CLI is planned for a future release" is better than leaving readers to wonder.
2. Concept page mixes "what" with "how"
The ## Key properties section reads like a field reference: "each skill is identified by a namespace ... and a name ... Skills are versioned using semantic versioning or commit hashes." That's describing the data model, not explaining the conceptual significance. Why reverse-DNS namespaces? Why does versioning matter for skills specifically?
More broadly, the ## Distribution section is a how/reference section — it describes the mechanics of OCI vs. Git packages. That belongs in the guide or a reference page, not a concept page.
Strip the concept page back to "what, why, and where it fits." Move ## Key properties and ## Distribution into the guide (or a reference page), and replace them with a clearer explanation of the role skills play in a developer's workflow — ideally with a concrete scenario: "A team that uses the same database MCP server publishes a query-safely skill once; every developer who joins can discover and use it rather than writing their own instructions from scratch."
3. The "why bother with the registry" motivation is buried or absent
Both pages assume the reader already wants to use a registry for skills. The concept page's intro mentions the "duplicating effort" problem in a single sentence. More importantly: who publishes skills to a shared registry vs. using them locally? Is this for OSS skill authors? For internal team skill sharing? For tool vendors to ship "starter" instructions alongside their MCP servers?
Without this, the concept page can't answer "should I care about this?" — which is the core job of a concept page.
Add 2–3 sentences to the concept page intro establishing the primary audience and use case. Even a single concrete scenario would anchor the rest of the content — e.g., "If you maintain an MCP server, publishing a companion skill lets users know how to use it effectively."
4. Guide reads as API reference, not a task-oriented guide
skills.mdx lists every endpoint in order (list → get → versions → publish → delete) with no narrative thread. A how-to guide should be organized around a user goal, not endpoint ordering. Someone who wants to publish a skill has to read past three read-only sections to get there.
Consider restructuring around tasks, or at minimum add a short intro paragraph explaining the two main use cases: (1) publishing and maintaining your own skills, and (2) discovering skills others have published. Reordering so "Publish a skill" comes before the retrieval operations would also help, since that's likely the primary write-side task.
Secondary issues
| Issue | Location | Recommendation |
|---|---|---|
| "Skills concept" typo in next steps | guides-registry/skills.mdx line 169 |
See inline suggestion |
| Lifecycle section is a stub | concepts/skills.mdx ## Lifecycle |
Either expand (when/why would you deprecate vs. archive?) or fold into the fields table in the guide |
| "fetched from the package source when a skill is installed" | concepts/skills.mdx Distribution section |
Clarify what does the fetching — this is the consumption gap from issue # 1 |
| Guide has no intro scenario | guides-registry/skills.mdx opening |
Add 1–2 sentences on who would use this guide and in what context |
What works well
- The
## Skills and MCP serverssection is clear and genuinely useful — the distinction between "tools an agent can call" vs. "instructions for how to use those tools" is well explained. - The publish example is concrete and realistic.
- The
Packagessub-table is a good addition; the OCI vs. Git distinction is non-obvious and needed documenting. - The note about kebab-case frontmatter vs. camelCase API fields is a real footgun worth calling out.
|
|
||
| ## Next steps | ||
|
|
||
| - [Skills concept](../concepts/skills.mdx) — understand what skills are and how |
There was a problem hiding this comment.
| - [Skills concept](../concepts/skills.mdx) — understand what skills are and how | |
| - [Skills concepts](../concepts/skills.mdx) — understand what skills are and how |
| :::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`). | ||
|
|
||
| ::: |
There was a problem hiding this comment.
This feels more like a "how" than a concept.
Description
Type of change
Related issues/PRs
Screenshots
Submitter checklist
Content and formatting
Navigation
sidebars.ts) updated for added, deleted, reordered, or renamed filesvercel.jsonfor moved, renamed, or deleted pages (i.e., if the URL slug changed)Reviewer checklist
Content