Add agent skills management documentation

docs/toolhive/concepts/skills.mdx

@@ -10,6 +10,10 @@ configuration that teaches an AI agent how to perform a specific task. If MCP
 servers provide **tools** (the raw capabilities an agent can call), skills
 provide the **knowledge** of when, why, and how to use those tools effectively.
 
+Skills follow the [Agent Skills](https://agentskills.io/) specification, an open
+standard supported by a growing number of AI coding agents including Claude
+Code, GitHub Copilot, Cursor, OpenCode, and many others.
+
 ## When you would use skills
 
 Consider these scenarios:
@@ -35,47 +39,71 @@ flowchart LR
   Skill["Skill\n(workflow + prompts)"] -->|references| MCP["MCP Server(s)\n(raw tools)"]
 ```
 
-Skills are stored in the same Registry server instance as MCP servers, but under
-a separate extensions API path (`/{registryName}/v0.1/x/dev.toolhive/skills`,
-where `{registryName}` is the name of your registry). They are not intermixed
-with MCP server entries.
+When you publish skills to the ToolHive Registry for team-wide discovery, they
+are stored under a separate extensions API path
+(`/{registryName}/v0.1/x/dev.toolhive/skills`, where `{registryName}` is the
+name of your registry). They are not intermixed with MCP server entries.
 
 ## Skill structure
 
-Each skill has the following core fields:
+A skill is a directory containing a `SKILL.md` file (required) plus optional
+supporting files:
 
-| Field         | Required | Description                                                         |
-| ------------- | -------- | ------------------------------------------------------------------- |
-| `namespace`   | Yes      | Reverse-DNS identifier (e.g., `io.github.acme`)                     |
-| `name`        | Yes      | Skill identifier in kebab-case (e.g., `code-review`)                |
-| `description` | Yes      | Human-readable summary of what the skill does                       |
-| `version`     | Yes      | Semantic version or commit hash (e.g., `1.0.0`)                     |
-| `status`      | No       | One of `ACTIVE`, `DEPRECATED`, or `ARCHIVED` (defaults to `ACTIVE`) |
-| `title`       | No       | Human-friendly display name                                         |
-| `license`     | No       | SPDX license identifier (e.g., `Apache-2.0`)                        |
+```text
+my-skill/
+├── SKILL.md          # Required: metadata + instructions
+├── scripts/          # Optional: executable code
+├── references/       # Optional: documentation
+└── assets/           # Optional: templates, resources
+```
 
-Skills also support optional fields for packages (OCI or Git references), icons,
-repository metadata, allowed tools, compatibility requirements, and arbitrary
-metadata.
+The `SKILL.md` file contains YAML frontmatter with metadata followed by Markdown
+instructions that the AI agent reads when the skill is activated.
 
-### Naming conventions
+### SKILL.md frontmatter
 
-- **Namespace**: Use reverse-DNS notation. For example, `io.github.your-org` or
-  `com.example.team`. This prevents naming collisions across organizations.
-- **Name**: Use kebab-case identifiers. For example, `code-review`,
-  `deploy-checker`, `security-scan`.
-- **Version**: Use semantic versioning (e.g., `1.0.0`, `2.1.3`) or a commit
-  hash. The registry tracks a "latest" pointer per namespace/name pair.
+| Field           | Required | Description                                           |
+| --------------- | -------- | ----------------------------------------------------- |
+| `name`          | Yes      | Lowercase letters, numbers, and hyphens (2-64 chars). |
+|                 |          | Must match the directory name.                        |
+| `description`   | Yes      | What the skill does and when to use it (max 1024      |
+|                 |          | chars).                                               |
+| `license`       | No       | SPDX license identifier (e.g., `Apache-2.0`).         |
+| `compatibility` | No       | Environment requirements (max 500 chars).             |
+| `metadata`      | No       | Arbitrary key-value pairs.                            |
+| `allowed-tools` | No       | List of pre-approved tools.                           |
+| `version`       | No       | Semantic version (e.g., `1.0.0`). ToolHive extension; |
+|                 |          | the base spec uses `metadata` for versioning.         |
+
+Example:
+
+```yaml title="SKILL.md"
+---
+name: code-review
+description: >-
+  Performs structured code reviews using best practices. Use when reviewing pull
+  requests or code changes.
+version: 1.0.0
+license: Apache-2.0
+---
+```
+
+For the complete format specification, see
+[agentskills.io/specification](https://agentskills.io/specification).
 
-**Valid examples:**
+### Naming conventions
 
-- `io.github.acme/code-review` version `1.0.0`
-- `com.example.platform/deploy-checker` version `0.3.1`
+- **Name**: Use kebab-case identifiers. For example, `code-review`,
+  `deploy-checker`, `security-scan`. The name must match the parent directory
+  name.
+- **Version**: Use semantic versioning (e.g., `1.0.0`, `2.1.3`).
 
-**Invalid examples:**
+When publishing skills to a ToolHive Registry Server, additional fields apply:
 
-- `acme/Code Review` (namespace must be reverse-DNS, name must be kebab-case)
-- Empty namespace or name (both are required)
+- **Namespace**: Use reverse-DNS notation (e.g., `io.github.your-org`). This
+  prevents naming collisions across organizations.
+- **Version**: Required when publishing to the registry.
+- **Status**: One of `active`, `deprecated`, or `archived` (case insensitive).
 
 ### Package types
 
@@ -95,19 +123,36 @@ an older version does not change the latest pointer.
 You can retrieve a specific version or request `latest` to get the most recent
 one.
 
-## Current status and what's next
+## How skills are discovered
+
+AI agents discover skills by reading from their skills directories. When you
+install a skill with the ToolHive CLI, the `SKILL.md` file is written to the
+appropriate directory for your AI client. The agent loads the skill's `name` and
+`description` at startup, and activates the full instructions when a task
+matches.
+
+Skills support two installation scopes:
+
+- **User scope**: Available across all your projects (installed to your home
+  directory)
+- **Project scope**: Available only in a specific project (installed to the
+  project directory)
+
+## Distribution
 
-The skills API is available as an extension endpoint on the Registry server
-(`/{registryName}/v0.1/x/dev.toolhive/skills`). You can publish, list, search,
-retrieve, and delete skills through this API.
+Skills can be distributed as:
 
-Skill installation via agent clients (such as the ToolHive CLI or IDE
-extensions) is planned for a future release. For now, the registry serves as a
-discovery and distribution layer where you can browse available skills and
-retrieve their package references.
+- **OCI artifacts**: Packaged as container registry artifacts for versioned
+  distribution through registries like GitHub Container Registry
+- **Git repositories**: Referenced by URL with optional branch/tag and subfolder
+- **Registry entries**: Published to a ToolHive Registry Server for centralized
+  discovery and installation by name
 
 ## Next steps
 
-- [Manage skills](../guides-registry/skills.mdx) through the Registry server API
-- [Registry server introduction](../guides-registry/intro.mdx) for an overview
-  of the Registry server
+- [Manage agent skills](../guides-cli/skills-management.mdx) with the ToolHive
+  CLI
+- [Manage skills in the registry](../guides-registry/skills.mdx) through the
+  Registry Server API
+- [Agent Skills specification](https://agentskills.io/specification) for the
+  complete format reference

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

@@ -150,6 +150,8 @@ ToolHive provides.
 
 ## Next steps
 
+- [Manage agent skills](./skills-management.mdx) to install reusable skills for
+  your AI clients
 - [Set up custom permissions](./custom-permissions.mdx) to control filesystem
   and network access for your servers
 - [Secure your servers](./auth.mdx) with OIDC authentication and Cedar policies

docs/toolhive/guides-cli/index.mdx

@@ -32,6 +32,8 @@ both installed.
   `thv` and run your first MCP server in minutes.
 - **Already installed?** Jump to [Run MCP servers](./run-mcp-servers.mdx) to
   start managing servers from the command line.
+- **Managing agent skills?** See [Manage agent skills](./skills-management.mdx)
+  to install and publish reusable skills.
 - **Building or automating?** See advanced workflows for [auth](./auth.mdx),
   [CI/CD](./advanced-cicd.mdx), [container builds](./build-containers.mdx), and
   more.