Update docs for registry server v0.6.3

docs/toolhive/concepts/skills.mdx

@@ -0,0 +1,75 @@
+---
+title: Agent Skills
+description:
+  What Agent Skills are, how they relate to MCP servers, and why you would use
+  them in the ToolHive Registry
+---
+
+Agent Skills are reusable, structured instructions that teach AI agents how to
+perform specific tasks. While MCP servers provide _tools_ (functions an agent
+can call), skills provide _knowledge_ (step-by-step guidance on how to approach
+a problem).
+
+## Skills vs. MCP servers
+
+MCP servers and skills serve complementary purposes in the ToolHive ecosystem:
+
+| Aspect         | MCP servers                         | Skills                                    |
+| -------------- | ----------------------------------- | ----------------------------------------- |
+| **What**       | Executable tools (APIs, functions)  | Structured instructions (Markdown + YAML) |
+| **How agents** | Call tool functions at runtime      | Load instructions into their context      |
+| **Example**    | A server that queries a database    | A guide for writing SQL migration scripts |
+| **Format**     | Running container with MCP protocol | `SKILL.md` file with frontmatter          |
+
+A skill might reference MCP tools it expects to use, and an MCP server might
+ship with skills that explain how to use its tools effectively. The two work
+together: skills tell the agent _what to do_, and MCP tools give it _the means
+to do it_.
+
+## Agent Skills specification
+
+Skills follow the open [Agent Skills specification](https://agentskills.io/),
+which defines a standard format for packaging agent instructions. Each skill is
+a directory containing at minimum a `SKILL.md` file with YAML frontmatter and
+Markdown instructions:
+
+```text
+my-skill/
+└── SKILL.md
+```
+
+The frontmatter includes metadata like the skill name, description, license, and
+optional fields such as compatibility requirements and allowed tools.
+
+## Skills in the registry
+
+The ToolHive Registry server hosts a _skills catalog_ alongside its MCP server
+registry. This lets you:
+
+- **Publish** skills to a managed registry so teams can share reusable agent
+  capabilities
+- **Discover** skills by searching, filtering by status, or browsing by
+  namespace
+- **Version** skills independently, with automatic latest-version tracking
+
+Skills live under a **namespace** (reverse-DNS format like `io.github.myorg`)
+that represents ownership. Combined with the skill name and version, this
+creates a unique identifier for every skill release.
+
+## When to use skills
+
+Consider publishing skills to the registry when you have:
+
+- **Repeatable workflows** that multiple teams or agents need to follow (e.g.,
+  code review checklists, deployment procedures, data analysis patterns)
+- **Domain expertise** that benefits from standardized instructions (e.g.,
+  compliance checks, security auditing steps)
+- **Tool usage guides** that explain how to combine multiple MCP tools to
+  accomplish a complex task
+
+## Next steps
+
+- [Publish and manage skills](../guides-registry/skills.mdx) through the
+  Registry server
+- [View the skills API reference](../reference/registry-skills-api.mdx) for
+  endpoint details

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:
@@ -276,8 +276,8 @@ The fields `file` and `url` are mutually exclusive.
 
 ### Managed registry
 
-API-managed registry for directly publishing and deleting MCP servers via the
-API. Does not sync from external sources.
+API-managed registry for directly publishing and deleting MCP servers and
+[skills](./skills.mdx) via the API. Does not sync from external sources.
 
 ```yaml title="config-managed.yaml"
 registries:
@@ -297,6 +297,8 @@ registries:
 - `DELETE /{registryName}/v0.1/servers/{name}/versions/{version}` - Delete
   versions
 - `GET` operations for listing and retrieving servers
+- Skills extension endpoints for publishing and managing Agent Skills (see
+  [Skills catalog](./skills.mdx))
 
 See the [Registry API reference](../reference/registry-api.mdx) for complete
 endpoint documentation and request/response examples.
@@ -349,7 +351,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-18}
 apiVersion: toolhive.stacklok.dev/v1alpha1
 kind: MCPServer
 metadata:
@@ -360,6 +362,7 @@ metadata:
     toolhive.stacklok.dev/registry-url: 'https://mcp.example.com/servers/my-mcp-server'
     toolhive.stacklok.dev/registry-description: |
       Production MCP server for code analysis
+    toolhive.stacklok.dev/registry-title: 'Code Analysis Server'
     toolhive.stacklok.dev/tool-definitions:
       '[{"name":"analyze_code","description":"Analyze code for potential
       issues","inputSchema":{"type":"object","properties":{"file":{"type":"string","description":"Path
@@ -375,6 +378,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 shown in the registry `title` field                   |
 | `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) |
 

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

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
+  Agent Skills
 ---
 
 The ToolHive Registry server is a standards-compliant implementation of the MCP
@@ -58,6 +59,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 [Agent Skills](./skills.mdx)
+  alongside MCP servers
 - **Container-ready**: Designed for deployment in Kubernetes clusters, but can
   be deployed anywhere
 - **Flexible deployment**: Works standalone or as part of ToolHive
@@ -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
+- [Publish and discover skills](./skills.mdx) through the skills catalog
 - [View the API reference](../reference/registry-api.mdx) for endpoint
   documentation

docs/toolhive/guides-registry/skills.mdx

@@ -0,0 +1,184 @@
+---
+title: Skills catalog
+description:
+  How to discover, publish, and manage Agent Skills through the ToolHive
+  Registry Server
+---
+
+The Registry server includes a skills catalog that lets you publish, discover,
+and manage [Agent Skills](../concepts/skills.mdx) alongside MCP servers. Skills
+are exposed through extension endpoints under each registry.
+
+## Prerequisites
+
+- A running Registry server with at least one
+  [managed registry](./configuration.mdx#managed-registry) configured
+- For write operations (publish, delete): authentication configured (see
+  [Authentication configuration](./authentication.mdx))
+
+Skills can only be published to managed registries. Read operations (list, get)
+work on any registry type.
+
+## Discover skills
+
+### List skills
+
+Retrieve a paginated list of skills in a registry, showing the latest version of
+each:
+
+```bash
+curl https://registry.example.com/my-registry/v0.1/x/dev.toolhive/skills
+```
+
+```json title="Response"
+{
+  "skills": [
+    {
+      "namespace": "io.github.acme",
+      "name": "code-review",
+      "description": "Structured code review following OWASP guidelines",
+      "version": "1.2.0",
+      "status": "active",
+      "title": "Security Code Review",
+      "license": "Apache-2.0"
+    }
+  ],
+  "metadata": {
+    "count": 1,
+    "nextCursor": ""
+  }
+}
+```
+
+**Query parameters:**
+
+| Parameter | Type   | Default | Description                                              |
+| --------- | ------ | ------- | -------------------------------------------------------- |
+| `search`  | string | -       | Filter by substring match on name, title, or description |
+| `status`  | string | -       | Filter by status (e.g., `active`, `deprecated`)          |
+| `limit`   | int    | 50      | Results per page (1-100)                                 |
+| `cursor`  | string | -       | Pagination cursor from a previous response               |
+
+### Get a specific skill
+
+Retrieve the latest version of a skill by namespace and name:
+
+```bash
+curl https://registry.example.com/my-registry/v0.1/x/dev.toolhive/skills/io.github.acme/code-review
+```
+
+### List all versions
+
+View the version history for a skill:
+
+```bash
+curl https://registry.example.com/my-registry/v0.1/x/dev.toolhive/skills/io.github.acme/code-review/versions
+```
+
+### Get a specific version
+
+Retrieve a particular version:
+
+```bash
+curl https://registry.example.com/my-registry/v0.1/x/dev.toolhive/skills/io.github.acme/code-review/versions/1.2.0
+```
+
+## Publish a skill
+
+To publish a skill version, send a `POST` request to the skills endpoint with
+the skill metadata:
+
+```bash
+curl -X POST \
+  https://registry.example.com/my-registry/v0.1/x/dev.toolhive/skills \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <TOKEN>" \
+  -d '{
+    "namespace": "io.github.acme",
+    "name": "code-review",
+    "description": "Structured code review following OWASP guidelines and project-specific rules.",
+    "version": "1.2.0",
+    "title": "Security Code Review",
+    "license": "Apache-2.0",
+    "compatibility": "Requires git and access to the internet",
+    "repository": {
+      "url": "https://github.com/acme/agent-skills",
+      "type": "git"
+    },
+    "packages": [
+      {
+        "registryType": "git",
+        "url": "https://github.com/acme/agent-skills",
+        "ref": "v1.2.0",
+        "subfolder": "skills/code-review"
+      }
+    ],
+    "metadata": {
+      "author": "acme-security-team"
+    }
+  }'
+```
+
+**Required fields:**
+
+| Field         | Description                                                 |
+| ------------- | ----------------------------------------------------------- |
+| `namespace`   | Reverse-DNS ownership scope (e.g., `io.github.acme`)        |
+| `name`        | Skill identifier (e.g., `code-review`)                      |
+| `description` | What the skill does and when to use it                      |
+| `version`     | Version string (ideally semantic versioning, e.g., `1.2.0`) |
+
+For the complete list of optional fields and package types, see the
+[skills API reference](../reference/registry-skills-api.mdx#skill-object).
+
+### Version tracking
+
+The registry automatically tracks the latest version of each skill. When you
+publish a new version, the server compares it against the current latest using
+semantic version comparison. The "latest" pointer only updates if the new
+version is semantically newer, so publishing an older patch version won't
+regress the latest pointer.
+
+## Delete a skill version
+
+Remove a specific version from a managed registry:
+
+```bash
+curl -X DELETE \
+  https://registry.example.com/my-registry/v0.1/x/dev.toolhive/skills/io.github.acme/code-review/versions/1.2.0 \
+  -H "Authorization: Bearer <TOKEN>"
+```
+
+A successful deletion returns a `204 No Content` response. Deleting a version
+also removes its associated packages.
+
+## Naming conventions
+
+Skills use a namespace + name addressing scheme:
+
+- **Namespace**: Reverse-DNS format representing ownership (e.g.,
+  `io.github.acme`, `com.example.team`). This prevents naming conflicts between
+  different publishers.
+- **Name**: The skill identifier. Follow the
+  [Agent Skills specification](https://agentskills.io/specification) naming
+  rules: lowercase letters, numbers, and hyphens only; no leading, trailing, or
+  consecutive hyphens; maximum 64 characters.
+
+**Valid examples:**
+
+- `io.github.acme/code-review`
+- `com.example.security/vulnerability-scan`
+
+**Invalid examples:**
+
+- `acme/Code-Review` (uppercase not allowed in name)
+- `io.github.acme/-code-review` (name cannot start with a hyphen)
+
+## Next steps
+
+- Learn about [Agent Skills concepts](../concepts/skills.mdx) and how they
+  relate to MCP servers
+- View the [skills API reference](../reference/registry-skills-api.mdx) for
+  complete endpoint documentation
+- [Configure a managed registry](./configuration.mdx#managed-registry) to enable
+  skill publishing