stacklok
diff --git a/‎.claude/agents/mcp-guide-writer.md‎
Lines changed: 0 additions & 73 deletions b/‎.claude/agents/mcp-guide-writer.md‎
Lines changed: 0 additions & 73 deletions
diff --git a/‎.claude/skills/docs-review/SKILL.md‎
Lines changed: 7 additions & 3 deletions b/‎.claude/skills/docs-review/SKILL.md‎
Lines changed: 7 additions & 3 deletions
diff --git a/‎.claude/skills/mcp-guide-writer/SKILL.md‎
Lines changed: 92 additions & 0 deletions b/‎.claude/skills/mcp-guide-writer/SKILL.md‎
Lines changed: 92 additions & 0 deletions
@@ -1,7 +1,7 @@
 ---
 name: docs-review
 description: >
-  Perform comprehensive editorial reviews of documentation with a tech writer / copyeditor lens. Use when asked to review docs, documentation PRs, or documentation changes - especially net-new documentation or LLM-generated content. Reviews can be for single documents or multiple related documents. Focuses on information architecture, clarity, conciseness, structure, readability, and style. Identifies common LLM writing patterns that harm documentation quality and catches multi-document issues like content duplication or misplaced content.
+  Perform comprehensive editorial reviews of documentation with a tech writer / copyeditor lens. Use when asked to review docs, documentation changes, or a set of changed files - especially net-new documentation or LLM-generated content. Reviews can be for single documents or multiple related documents. Focuses on information architecture, clarity, conciseness, structure, readability, and style. Identifies common LLM writing patterns that harm documentation quality and catches multi-document issues like content duplication or misplaced content. For reviewing a pull request end-to-end (fetching the PR branch, checking review threads, drafting a review to post), use the review-docs-pr skill, which applies these criteria as one of its steps.
 ---
 
 # Documentation Review
@@ -68,8 +68,12 @@ Watch for these telltale signs of AI-generated docs that need human intervention
 | Hedging language | "may," "might," "could potentially" | Be direct or remove |
 | Em/en dashes | `—` or `–` used as inline separators | Rephrase naturally: use commas, split sentences, or restructure. Use spaced hyphens (`-`) only in list-style contexts |
 | Hedged lists | "such as," "including," "clients include" when listing supported items | Be definitive: state the full list, or link to a canonical reference |
-| Placeholder examples | `my-skill`, `example-org`, `my-app` instead of real values | Use real, working examples from the actual product |
+| Placeholder examples | `my-skill`, `example-org`, `my-app` where a real product value exists | Use real values for fixed things (commands, flags, image names); use `<ALL_CAPS>` placeholders for values the reader supplies; use reserved domains (`example.com`) in URLs, never real domains |
 | Features without context | Introduces a flag/option without explaining why a reader would use it | Explain the user benefit and how it connects to concepts the reader already knows |
+| Changelog framing | "Starting in vX.Y," "previously," "moved from X to Y" - narrating the transition instead of the current behavior | State current behavior only; transitions belong in release notes. Common in release-driven PRs where the diff (the delta) leaks into the prose. Exception: a clearly labeled, versioned admonition for a breaking or silently-behavioral change that upgraders must act on is valid (see the style guide); flag those only when stale (several releases old) or duplicating adjacent prose |
+| Negative restatement | "X, not Y" or a "Don't do Z" sentence that inverts the positive statement just made | Cut it, or fold any genuinely new fact into the positive statement |
+| Redundant admonitions | A note or warning that restates adjacent body text, often with added negation | Cut it; an admonition must add information beyond the surrounding prose |
+| PR jargon leak | Engineering shorthand from PR descriptions ("consumers," "shapes," "surface area," "wire up") | Name the concrete components, fields, and values |
 
 ### Section Structure and Navigation
 
@@ -100,7 +104,7 @@ The docs follow a product-area-based information architecture under `docs/toolhi
 Docs that readers can't trust are worse than no docs. Actively verify:
 
 - **Cross-check against reference material**: Does the prose contradict the auto-generated CLI reference, the API spec, or the upstream project's docs? Flag contradictions. Note: docs are often drafted before a release, so auto-generated references may not yet include new features - absence from the reference is not the same as a contradiction. But if an existing reference explicitly describes different behavior (e.g., "by name or OCI reference" when the prose also claims Git support), that's a real conflict to flag
-- **Code examples must work**: Could a reader copy-paste this and get the described result? Check for correct syntax, realistic flag combinations, and valid argument values. Placeholder examples (`my-skill`, `example.com`) should be replaced with real, working values wherever possible
+- **Code examples must work**: Could a reader copy-paste this and get the described result? Check for correct syntax, realistic flag combinations, and valid argument values. Generic placeholders (`my-skill`, `foo`) should be replaced with real product values where the value is fixed, or `<ALL_CAPS>` placeholders where the reader supplies it. Domains in example URLs are the exception: use reserved domains (`example.com`), not real ones
 - **Feature coverage completeness**: When documenting a new feature, check that the full surface area is covered. Are all subcommands/endpoints mentioned? Are common error states addressed? A how-to that covers the happy path but ignores the most likely failure mode will generate support questions
 - **Consistency across the doc set**: Do the same terms, flag names, and behaviors described here match how they're described in related pages? Cross-document inconsistencies (e.g., one page says "space-delimited," another uses comma-separated) erode trust
 
 
@@ -0,0 +1,92 @@
+---
+name: mcp-guide-writer
+description: >
+  Create usage guides for MCP servers in the ToolHive documentation (docs/toolhive/guides-mcp/). Use when asked to write, create, or update a usage guide for an MCP server, e.g. "write a usage guide for the filesystem MCP server" or "document the sqlite MCP server from the registry".
+argument-hint: '<server-name>'
+---
+
+# MCP server usage guide writer
+
+Create accurate, user-friendly usage guides that help developers run an MCP server with ToolHive.
+
+**Guide scope**: the guide's job is to get the server working with ToolHive: install, configure, connect a client, and try it out. It is not a tutorial for the upstream server itself. Keep upstream-server caveats and behavior details to a sentence with a link to the server's own documentation.
+
+## Research and information gathering
+
+- Use the `thv registry info <server-name> --format json` command to gather detailed information about the MCP server, including configuration options, capabilities, and requirements.
+- Use the `WebFetch` tool, the `fetch` MCP server, or `github` MCP server to retrieve additional documentation from the server's repository.
+
+## Structure
+
+Write guides as MDX files in `docs/toolhive/guides-mcp/` following the `_template.mdx` structure exactly. Each guide must include ONLY these sections:
+
+- Front matter with title, description, last_update author and today's date (`YYYY-MM-DD` format)
+- Overview section explaining what the MCP server does
+- Metadata section with `<MCPMetadata name='server-name' />` component
+- Usage section with tabbed UI/CLI/Kubernetes instructions
+- Sample prompts section with practical examples
+- Recommended practices section with security and best practices
+
+DO NOT include:
+
+- Available tools/capabilities section (handled by MCPMetadata component)
+- Configuration options section (handled by MCPMetadata component)
+
+## Technical accuracy
+
+All configuration examples must be valid and tested. Reference the existing ToolHive documentation in the `docs/toolhive/` directory as the source of truth for:
+
+- Available `thv` CLI commands and their syntax (reference: `docs/toolhive/reference/cli/*.md` or run `thv --help`)
+- Kubernetes CRD specifications and fields (reference: `static/api-specs/toolhive-crds/*.schema.json`)
+- UI configuration options and workflows (reference: `docs/toolhive/guides-ui/*`)
+
+## Documentation standards
+
+Adhere to the project's writing style guide (`STYLE-GUIDE.md`) including:
+
+- Use US English with casual, conversational tone
+- Address readers in second person ("you", "your")
+- Use sentence case for headings
+- Apply proper Markdown formatting (ATX headings, fenced code blocks with language tags)
+- Include descriptive alt text for images
+- Use admonitions (`:::note`, `:::tip`, `:::warning`) for important information, using `:::tip[Title]` format for custom titles
+
+## Practical examples
+
+Provide real-world, actionable examples that users can copy and modify. Include:
+
+- CLI usage examples covering the common configurations for this server, including security configurations
+- Complete Kubernetes manifests with proper YAML formatting
+- UI configuration guidance focusing on unique features
+- Sample prompts that demonstrate real use cases for the MCP server
+- Security-focused examples using network isolation and permission profiles
+
+## Reference existing guides
+
+- Use `docs/toolhive/guides-mcp/_template.mdx` as the reference for exact structure.
+- Use existing guides as reference for tone and depth of coverage. A good example is `docs/toolhive/guides-mcp/github.mdx`.
+
+## Quality assurance
+
+Before finalizing, verify that:
+
+- All code examples are syntactically correct
+- Configuration parameters match the actual MCP server requirements
+- Links to external resources are valid and current
+- The guide follows the established template structure
+- Examples work with current ToolHive versions
+
+## Content structure requirements
+
+1. **Overview section**: Provide a clear, concise explanation of the MCP server's purpose and key features. Include links to official documentation and highlight what makes this server unique.
+
+2. **Usage section tabs**:
+
+   Using the MCP server's documentation as reference, use its unique features and use cases to create detailed instructions for each tab:
+   - **UI tab**: Focus on unique configuration options and features, not basic registry selection. The ToolHive UI includes a configuration interface that allows users to set the secrets and environment variables defined in the server metadata, customize command-line arguments, and add volume mounts. Provide step-by-step instructions for these configurations if needed for the MCP server.
+   - **CLI tab**: Provide examples covering the common configurations, including security configurations.
+   - **Kubernetes tab**: Include complete, working YAML manifests with proper formatting and comments.
+
+3. **Sample prompts**: Create 3-6 realistic prompts that demonstrate the server's capabilities. Make them specific and actionable, not generic.
+
+4. **Recommended practices**: Focus on security, performance, and reliability best practices specific to the MCP server.