From bf238e44556af5847e3cafb3b246a591d6b2cd2a Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Thu, 30 Jul 2026 12:21:54 -0400 Subject: [PATCH 1/5] Codify style rules for agent-authored docs Add "Document current behavior" section (docs are not a changelog, prefer positive statements, scoped exception for breaking changes), jargon-translation guidance, and admonition redundancy rules to AGENTS.md and STYLE-GUIDE.md. Add four LLM-pattern rows to the docs-review skill and fix its placeholder guidance to match the example.com convention. Add "write the end state" discipline to the upstream-release-docs skill. Rewrite the auto-generated content instruction with rationale and the complete path list. Refs #1074 Co-Authored-By: Claude Fable 5 --- .claude/skills/docs-review/SKILL.md | 10 +++-- .claude/skills/upstream-release-docs/SKILL.md | 9 +++- AGENTS.md | 21 ++++++++- STYLE-GUIDE.md | 45 +++++++++++++++++++ 4 files changed, 79 insertions(+), 6 deletions(-) diff --git a/.claude/skills/docs-review/SKILL.md b/.claude/skills/docs-review/SKILL.md index e5313e77..9fc44b84 100644 --- a/.claude/skills/docs-review/SKILL.md +++ b/.claude/skills/docs-review/SKILL.md @@ -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 `` 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 `` 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 diff --git a/.claude/skills/upstream-release-docs/SKILL.md b/.claude/skills/upstream-release-docs/SKILL.md index db5d4736..96d53554 100644 --- a/.claude/skills/upstream-release-docs/SKILL.md +++ b/.claude/skills/upstream-release-docs/SKILL.md @@ -49,7 +49,7 @@ When Phase 2 step 4 would normally ask the user for a major feature's "why", ins 1. Fetch the PR body and author with `gh pr view --repo / --json title,body,author`. The PR body usually carries the "why" the author wrote at open time: motivation, intended consumers, design decisions. 2. If the PR body references linked issues ("Closes #N", "Fixes #N", "Refs #N"), fetch the likely-context-bearing ones with `gh issue view --repo /`. -3. Write the "why"/consumer narrative directly into the relevant page using what you learned. This is best-effort; reviewers refine it later. +3. Write the "why"/consumer narrative directly into the relevant page using what you learned, translated into reader-facing language rather than the PR's engineering shorthand. This is best-effort; reviewers refine it later. 4. Defer to `GAPS.md` only when the rationale demonstrably cannot be derived from available sources: the PR points to an internal design doc you cannot access, multiple plausible consumer narratives exist and choosing one would mislead readers, or a release timeline or commitment needs product-team confirmation. ### Artifacts (unattended mode only, written at repo root) @@ -206,7 +206,11 @@ For each PR identified in Phase 1 (skip internal/infra unless user requests): ## Phase 4: Implementation -Apply the approved changes: +Apply the approved changes. + +**Write the end state, not the transition.** Your input is a release delta, but the reader's page is not: docs state how the product works now, not how it changed. When the displacement audit flags a falsified sentence, rewrite it to state the new behavior plainly. Don't preserve the old behavior alongside it ("previously X; as of vX.Y, Y"), and don't add version-stamped change notes or upgrade-ordering warnings to guides; that's release-notes material. + +One exception: a breaking change or major behavioral change (a changed default, behavior that silently differs for existing setups) may get a clearly labeled, versioned admonition (`:::info[Changed in vX.Y]`) when upgraders need an explanation or action they can't infer from an error message. Keep the surrounding prose standalone about current behavior; the admonition carries only the upgrade delta and action. Changes that fail loudly with an obvious cause don't qualify; surface those to the reviewer (in `SUMMARY.md` when unattended, conversationally when interactive) rather than writing them into a page. Large migrations get a dedicated migration guide with short pointers from affected pages, following the `guides-k8s/migrate-to-v1beta1.mdx` pattern. The same discipline applies to vocabulary: PR bodies are written for maintainers, and their shorthand ("consumers", "shapes", "surface area") must be translated into the concrete components, fields, and values the reader sees. 1. **Update existing pages, and prefer extending them over creating new ones.** Edit files using the impact map, preserving the existing writing style and conventions. When a feature _extends_ a capability the docs already cover (a new auth mechanism alongside an existing one, a new flag on a documented command, an additional option on a documented resource), the right move is almost always to add a section to the existing page and reconcile the surrounding prose (see the displacement audit in Phase 3), not to spin up a standalone page. A standalone page for an extension fragments the concept across two locations, duplicates context, and is a common over-documentation failure mode. Reserve new pages for genuinely standalone capabilities (see the next step). @@ -327,6 +331,7 @@ When receiving review comments (from humans or automated reviewers): - **Triple verification**: verify during deep dive (Phase 2), before finalizing (Phase 5), and when handling reviews (Phase 6) - **Document what the release falsifies, not just what it adds**: a new capability usually makes prior "only / default / automatic / planned" statements wrong. Audit the _displaced_ concept's vocabulary across the whole docs set, and treat a purely additive (`+N / -0`) prose edit as a smell. The reviewer cannot catch a sin of omission in a zero-deletion diff; the skill must (Phase 3 displacement audit). +- **Write the end state, not the transition**: docs describe current behavior, not the change history. No "Starting in vX.Y", no "moved from A to B", no upgrade-ordering warnings in guides. The one exception is a clearly labeled, versioned admonition for a breaking or silently-behavioral change upgraders must act on; route other migration guidance to the reviewer (Phase 4). - **Transparency**: log the categorized summary (after Phase 1) and impact map (after Phase 3) for auditability, but do not stop; run all phases to completion - **Respect auto-generated content**: don't manually edit auto-generated files, but always create the surrounding conceptual/guide content that auto-generated reference docs don't provide - **Separate by Diataxis type, at the right granularity**: keep concept and how-to content distinguishable, but prefer extending an existing page over a new one when the feature extends a documented capability. Reserve new pages for standalone capabilities, and split a section out only when it would overload its host (Phase 4). diff --git a/AGENTS.md b/AGENTS.md index 131ea0ac..dfa9a5b2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -24,9 +24,11 @@ This is the user-facing documentation for ToolHive, an open source tool that hel ## Auto-generated content -Do not edit these files directly; they are generated automatically by upstream processes. +NEVER hand-edit or delete these files, even when asked to remove or change the content they contain. They are regenerated from upstream sources on every release sync, so hand edits are silently overwritten by the next release PR. To change or remove their content, the change must land in the upstream repo (for example, marking a CLI command `Hidden: true` in the ToolHive source); it then flows into these files at the next release sync. If content must disappear from the site before an upstream release makes that happen, say so and flag it to a human instead of editing. - `/docs/toolhive/reference/cli/*.md`: auto-generated CLI reference documentation from the ToolHive CLI source code. +- `/docs/toolhive/reference/crds/*.mdx` and `/docs/platform/reference/crds/*.mdx`: CRD reference pages generated by `scripts/upstream-release/extract-crds.mjs`. Hand-written page intros live in `scripts/lib/crd-intros.mjs`, which is the file to edit. +- `/src/components/CRDReference/all-schemas.ts`: consolidated CRD schema barrel generated by `scripts/generate-crd-barrel.mjs`. - `/static/api-specs/*`: auto-generated API, CRD, and JSON schema specifications. ## Commands @@ -174,10 +176,26 @@ The project's official language is US English. - Be friendly and relatable while retaining credibility and professionalism. - Avoid slang and colloquial expressions. - Use clear, straightforward language and avoid overly complex jargon to make content accessible to a wide audience. +- Translate engineering shorthand into concrete, reader-facing terms. Language from PR descriptions and commit messages ("consumers", "shapes", "surface area") rarely belongs in docs; name the actual components, fields, and values instead. - Use active voice instead of passive voice. - Address the reader using the second person ("you", "your"). Avoid the first person ("we", "our") and third person ("the user", "a developer"). - Exception: In `/blog/toolhive-updates` posts, it's acceptable to use the first person ("we", "our") to communicate updates from the ToolHive team. +### Document current behavior + +Docs describe how the product works today; they are not a changelog or upgrade guide. + +- Don't narrate history or transitions. Avoid "Starting in vX.Y", "previously", "changed from X to Y", "new in this release", and version-conditional notes. Release notes and blog posts tell that story; guides and references state only the current behavior. + - Yes: The JSON-RPC error code for rate limiting is `429`. + - No: The JSON-RPC error code moved from `-32029` to `429` in v0.41.0. +- Upgrade sequencing and migration caveats belong in release notes, not inline in how-to guides. +- Prefer positive statements. Say what the product does and what the reader should do; don't restate a positive statement in negative form ("uses X, not Y", "don't point it at..."). If a negation carries a genuinely new fact, fold that fact into the positive statement. + - Yes: The Cloud UI uses the registry policy's `server_api_url` value. + - No: The Cloud UI reads `server_api_url`, not `api_url`. +- Exception: a breaking change or major behavioral change (a changed default, behavior that silently differs for existing setups) may carry a clearly labeled, versioned admonition (e.g. `:::info[Changed in v0.30.1]`) when upgraders need an explanation or action they can't infer from an error message. Keep the surrounding prose standalone about current behavior; the admonition carries only the upgrade delta and action. Remove these notes after a few releases, once the upgrade audience has moved on. Changes that fail loudly at startup with an obvious cause don't qualify. +- Large migrations (API version promotions, multi-field removals) get a dedicated migration guide (see `guides-k8s/migrate-to-v1beta1.mdx`); guide pages link to it with a short pointer rather than carrying the details inline. +- Deprecation notices are current state, not changelog. Documenting that a feature is deprecated, still read but warned about, or scheduled for removal is fine. + ### Capitalization - Capitalize proper nouns like names, companies, and products. Generally, don't capitalize features or generic terms. @@ -270,6 +288,7 @@ This website is built using Docusaurus, which has some specific requirements and - Line highlights are added using comma-separated `{number}` or `{start-end}` ranges in the opening code fence, or `highlight-next-line`, `highlight-start`, and `highlight-end` comments within the code block. - Use admonitions for notes, tips, warnings, and other annotations. This provides a consistent look and feel across the site. - Use the `:::type` syntax to define the admonition type: `note`, `tip`, `info`, `warning`, `danger`, or `enterprise`. Use square brackets to add a custom title, e.g. `:::info[Title]`. Add empty lines around the start and end directives. + - An admonition must add information beyond the surrounding text. Don't use one to restate or negate what the adjacent prose already says, and don't overuse them; too many interrupt the reading flow. - The `:::enterprise` admonition is for Stacklok Enterprise content only - see "Enterprise content constructs" below. - Place images in `static/img` using WebP, PNG, or SVG format. - Use the `ThemedImage` component to provide both light and dark mode screenshots for apps/UIs that support both. Typically used with the `useBaseUrl` hook to construct the image paths. Both require import statements. diff --git a/STYLE-GUIDE.md b/STYLE-GUIDE.md index 697e0f47..c8082bb0 100644 --- a/STYLE-GUIDE.md +++ b/STYLE-GUIDE.md @@ -12,6 +12,7 @@ aim to deliver clear, concise, and valuable information to project users. - [Tone and voice](#tone-and-voice) - [Active voice](#active-voice) - [Speak to the reader](#speak-to-the-reader) + - [Document current behavior](#document-current-behavior) - [Capitalization](#capitalization) - [Punctuation](#punctuation) - [Links](#links) @@ -52,6 +53,10 @@ The project's official language is **US English**. Avoid slang and colloquial expressions. Use clear, straightforward language and avoid overly complex jargon to make content accessible to a wide audience. +Translate engineering shorthand into concrete, reader-facing terms. Language +from PR descriptions and commit messages ("consumers", "shapes", "surface area") +rarely belongs in docs; name the actual components, fields, and values instead. + ### Tone and voice Strive for a casual and conversational tone without becoming overly informal. We @@ -77,6 +82,44 @@ logging.\ Address the reader using the **second person** ("you", "your"). Avoid the first person ("we", "our") and third person ("the user", "a developer"). +### Document current behavior + +Docs describe how the product works today; they are not a changelog or upgrade +guide. + +Don't narrate history or transitions. Avoid "Starting in vX.Y", "previously", +"changed from X to Y", "new in this release", and version-conditional notes. +Release notes and blog posts tell that story; guides and references state only +the current behavior. Upgrade sequencing and migration caveats likewise belong +in release notes, not inline in how-to guides. + +:white_check_mark: Yes: The JSON-RPC error code for rate limiting is `429`.\ +:x: No: The JSON-RPC error code moved from `-32029` to `429` in v0.41.0. + +Prefer positive statements. Say what the product does and what the reader should +do; don't restate a positive statement in negative form. If a negation carries a +genuinely new fact, fold that fact into the positive statement. + +:white_check_mark: Yes: The Cloud UI uses the registry policy's `server_api_url` +value.\ +:x: No: The Cloud UI reads `server_api_url`, not `api_url`. + +**Exception for breaking changes**: a breaking change or major behavioral change +(a changed default, behavior that silently differs for existing setups) may +carry a clearly labeled, versioned admonition (e.g. +`:::info[Changed in v0.30.1]`) when upgraders need an explanation or action they +can't infer from an error message. Keep the surrounding prose standalone about +current behavior; the admonition carries only the upgrade delta and action. +Remove these notes after a few releases, once the upgrade audience has moved on. +Changes that fail loudly at startup with an obvious cause don't qualify. + +Large migrations (API version promotions, multi-field removals) get a dedicated +migration guide; guide pages link to it with a short pointer rather than +carrying the details inline. + +Deprecation notices are current state, not changelog. Documenting that a feature +is deprecated, still read but warned about, or scheduled for removal is fine. + ### Capitalization Capitalize **proper nouns** like names, companies, and products. Generally, @@ -313,6 +356,8 @@ Specific guidelines for Docusaurus: - Don't overuse admonitions; they are best for callouts that add value beyond the main content. Too many admonitions can become visually overwhelming and interrupt the flow of documentation. + - An admonition must add information beyond the surrounding text. Don't use + one to restate or negate what the adjacent prose already says. - Place images in `static/img` using WebP, PNG, or SVG format. - Use the [`ThemedImage` component](https://docusaurus.io/docs/markdown-features/assets#themed-images) From d4cb90b5732d3caebf745ca7f2649e8d420ee191 Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Thu, 30 Jul 2026 12:22:04 -0400 Subject: [PATCH 2/5] Convert mcp-guide-writer agent to a skill The agent format predates skills. Convert to a skill for consistency with the other docs workflows, fix the broken STYLE_GUIDE.md reference, and rescope the framing: guides get the server working with ToolHive, keeping upstream details to a line with a link. Refs #1075 Co-Authored-By: Claude Fable 5 --- .claude/agents/mcp-guide-writer.md | 73 ------------------- .claude/skills/mcp-guide-writer/SKILL.md | 92 ++++++++++++++++++++++++ 2 files changed, 92 insertions(+), 73 deletions(-) delete mode 100644 .claude/agents/mcp-guide-writer.md create mode 100644 .claude/skills/mcp-guide-writer/SKILL.md diff --git a/.claude/agents/mcp-guide-writer.md b/.claude/agents/mcp-guide-writer.md deleted file mode 100644 index c02fa671..00000000 --- a/.claude/agents/mcp-guide-writer.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -name: mcp-guide-writer -description: Use this agent when you need to create comprehensive usage guides for MCP servers in the ToolHive documentation. Examples: Context: The user wants to add documentation for a new MCP server that has been added to the ToolHive registry.\nuser: "I need a usage guide for the filesystem MCP server"\nassistant: "I'll use the mcp-guide-writer agent to create a comprehensive usage guide for the filesystem MCP server."\nSince the user needs an MCP usage guide created, use the mcp-guide-writer agent to generate the MDX documentation file. Context: A new MCP server has been discovered and needs documentation.\nuser: "Can you write documentation for the sqlite MCP server? It's available in the registry."\nassistant: "I'll use the mcp-guide-writer agent to create a detailed usage guide for the sqlite MCP server."\nThe user is requesting MCP server documentation, so use the mcp-guide-writer agent to create the guide. -model: sonnet ---- - -You are an expert technical writer specializing in Model Context Protocol (MCP) server documentation for ToolHive. Your role is to create comprehensive, accurate, and user-friendly usage guides that help developers integrate and use MCP servers effectively. - -When creating a guide, start by gathering comprehensive information about the MCP server, then structure the content to progressively guide users from basic setup to advanced usage scenarios. Focus on practical value and ensure every example is something users can actually implement. - -Your primary responsibilities: - -1. **Research and Information Gathering**: - - Use the `thv registry info --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. - -2. **Create Structured MDX Documentation**: 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 `` 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) - -3. **Ensure 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/*`) - -4. **Follow 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 - -5. **Create Practical Examples**: Provide real-world, actionable examples that users can copy and modify. Include: - - Multiple CLI usage examples from basic to advanced scenarios - - 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 - -6. **Reference Existing Guides**: - - Use `docs/toolhive/guides-mcp/_template.mdx` as references for exact structure, - - Use existing guides as reference for tone and depth of coverage. A good example is `docs/toolhive/guides-mcp/github.mdx` - -7. **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 - -**Key Requirements for Content Structure:** - -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 multiple progressive examples from basic to advanced usage, 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. diff --git a/.claude/skills/mcp-guide-writer/SKILL.md b/.claude/skills/mcp-guide-writer/SKILL.md new file mode 100644 index 00000000..0fbbde6d --- /dev/null +++ b/.claude/skills/mcp-guide-writer/SKILL.md @@ -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: '' +--- + +# 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 --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 `` 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. From bdc676f0ccbe2ce8175cf2044b46b003e6440791 Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Thu, 30 Jul 2026 12:22:12 -0400 Subject: [PATCH 3/5] Align weekly-product-updates with word list Defer to the AGENTS.md word list as the single source of truth for product names instead of maintaining a divergent copy. Drop the unsanctioned "ToolHive Portal" and "ToolHive Gateway" entries and replace "Desktop UI" with ToolHive UI. Refs #1075 Co-Authored-By: Claude Fable 5 --- .claude/skills/weekly-product-updates/SKILL.md | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/.claude/skills/weekly-product-updates/SKILL.md b/.claude/skills/weekly-product-updates/SKILL.md index 3e895250..21375150 100644 --- a/.claude/skills/weekly-product-updates/SKILL.md +++ b/.claude/skills/weekly-product-updates/SKILL.md @@ -27,15 +27,11 @@ Parse the arguments by checking if the first word is `summary` or `blog`. If not ## Terminology -Use correct product names consistently: +Follow the word list in the project's AGENTS.md ("Word list" section); it is the single source of truth for product names and capitalization. Additions and clarifications specific to these updates: - **ToolHive**: Bi-capitalized, one word (not "Toolhive" or "Tool Hive") -- **Virtual MCP Server (vMCP)**: Full name on first use, "vMCP" thereafter. Lowercase "v" (not "VMCP") - **ToolHive Registry Server**: Capitalized as product name. Lowercase "registry server" when generic. -- **ToolHive Gateway**: Capitalized as product name. vMCP is the implementation. -- **ToolHive Portal**: The web-based frontend (Cloud UI). -- **MCP**: Model Context Protocol. Always all-caps abbreviation. -- **open source**: Two words, lowercase (not "open-source") +- **ToolHive UI**: The desktop app. The `toolhive-studio` repo name is internal only; never write "Studio" in user-facing copy. ## ToolHive Repositories @@ -43,8 +39,8 @@ Use correct product names consistently: | --- | --- | | `stacklok/toolhive-registry-server` | Registry Server (discovery, sync, API) | | `stacklok/toolhive` | CLI, Kubernetes Operator, Virtual MCP Server (vMCP) | -| `stacklok/toolhive-studio` | Desktop UI | -| `stacklok/toolhive-cloud-ui` | Cloud UI (ToolHive Portal) | +| `stacklok/toolhive-studio` | ToolHive UI (desktop app) | +| `stacklok/toolhive-cloud-ui` | Cloud UI | Note: The `toolhive` repo contains both Runtimes and vMCP components -- distinguish updates by subdirectories or PR labels. @@ -192,7 +188,7 @@ Use this for Slack, email, Google Docs, or any non-blog context. For detailed release notes, check the project repositories: - [ToolHive Runtimes](https://github.com/stacklok/toolhive/releases) (CLI and Kubernetes Operator) -- [ToolHive Desktop UI](https://github.com/stacklok/toolhive-studio/releases) +- [ToolHive UI](https://github.com/stacklok/toolhive-studio/releases) - [ToolHive Cloud UI](https://github.com/stacklok/toolhive-cloud/releases) - [ToolHive Registry Server](https://github.com/stacklok/toolhive-registry-server/releases) @@ -230,7 +226,7 @@ description: For detailed release notes, check the project repositories: - [ToolHive Runtimes](https://github.com/stacklok/toolhive/releases) (CLI and Kubernetes Operator) -- [ToolHive Desktop UI](https://github.com/stacklok/toolhive-studio/releases) +- [ToolHive UI](https://github.com/stacklok/toolhive-studio/releases) - [ToolHive Cloud UI](https://github.com/stacklok/toolhive-cloud/releases) - [ToolHive Registry Server](https://github.com/stacklok/toolhive-registry-server/releases) From b17983edc6871e8655e79f426093433b8bd7d024 Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Thu, 30 Jul 2026 12:22:20 -0400 Subject: [PATCH 4/5] Add move-page and review-docs-pr skills move-page encodes the five coupled steps of relocating a docs page (file move, sidebars.ts, inbound link sweep, vercel.json redirect, build verification), validated by an end-to-end test run in an isolated worktree. review-docs-pr wraps PR review mechanics (head-ref reads, thread resolution checks, body-level draft for approval) around the docs-review editorial criteria. Refs #1075 Co-Authored-By: Claude Fable 5 --- .claude/skills/move-page/SKILL.md | 68 ++++++++++++++++++++++++++ .claude/skills/review-docs-pr/SKILL.md | 47 ++++++++++++++++++ 2 files changed, 115 insertions(+) create mode 100644 .claude/skills/move-page/SKILL.md create mode 100644 .claude/skills/review-docs-pr/SKILL.md diff --git a/.claude/skills/move-page/SKILL.md b/.claude/skills/move-page/SKILL.md new file mode 100644 index 00000000..19d8d1b9 --- /dev/null +++ b/.claude/skills/move-page/SKILL.md @@ -0,0 +1,68 @@ +--- +name: move-page +description: > + Move or rename a documentation page safely: relocate the file, update sidebars.ts, sweep and fix inbound links, add a vercel.json redirect from the old URL, and verify the build. Use whenever a docs page's file path or URL changes for any reason: moving a page to another section, renaming a file or slug, restructuring or consolidating a section, or retiring a page in favor of another. E.g. "move the vault guide into integrations", "rename quickstart-cli to quickstart", "fold the ngrok tutorial into the integrations guide". +argument-hint: ' ' +--- + +# Move or rename a documentation page + +Relocating a page touches five things: the file, the sidebar, inbound links, the published URL (which external sites and search results already point at), and the build. Missing the redirect is the costly failure: it produces 404s for every existing external link and search result. Follow every step; none are optional. + +## URL model + +Docs are served with `routeBasePath: '/'`, so a page's URL is its file path relative to `docs/`, without the extension: + +- `docs/toolhive/guides-cli/network-isolation.mdx` → `/toolhive/guides-cli/network-isolation` +- `index.mdx` pages resolve to their directory path: `docs/toolhive/guides-registry/index.mdx` → `/toolhive/guides-registry/` +- A doc's sidebar ID is the same path without the extension (e.g. `toolhive/guides-cli/network-isolation`). + +## Before moving + +1. Confirm the old file exists and check `git status` for uncommitted changes to it. +2. Confirm the destination follows the information architecture placement rules (AGENTS.md "Where to place new content"). If the requested destination conflicts with those rules, raise it before proceeding. +3. Never move auto-generated pages (see AGENTS.md "Auto-generated content"). Their location is owned by the generation scripts; moving them requires changes to the upstream config, not a file move. + +## Steps + +1. **Move the file** with `git mv ` so history follows the file. + +2. **Update `sidebars.ts`**: change the doc ID to the new path (relative to `docs/`, no extension). If the page moved between sections, place it appropriately in the destination category and remove it from the source category. + +3. **Sweep inbound links.** Search for both reference forms and update every hit: + - Relative file links from other pages: grep for the old filename (e.g. `network-isolation.mdx`) across `docs/` and `blog/`. Recompute each relative path from the linking file's location. + - Site-absolute URL links: grep for the old URL path (e.g. `/toolhive/guides-cli/network-isolation`) across `docs/`, `blog/`, `src/`, and `docusaurus.config.ts` (navbar/footer links). + - If an auto-generated page links to the old path, don't hand-edit it; the fix belongs in its source (`scripts/lib/crd-intros.mjs` for CRD page intros, or the upstream repo). + - For a rename, also check the page's own front matter (`title`, `description`) and opening prose for the old name while the file is open. + +4. **Add a redirect** in `vercel.json` from the old URL to the new one: + + ```json + { + "source": "/toolhive/guides-cli/old-name", + "destination": "/toolhive/guides-cli/new-name", + "permanent": true + } + ``` + + Use `"permanent": true` for a real move or rename; reserve `"permanent": false` for URLs expected to change again soon. If the old URL already appears as a `destination` in existing redirects, update those entries to point directly at the new URL so readers don't hop through redirect chains. Place the new entry next to related redirects (same section or topic) rather than appending at the end. + +5. **Check anchors.** Redirects preserve `#fragment` anchors, so any inbound link that targets a heading (`old-page#some-heading`) only works if that heading still exists on the destination page. If headings changed during the move, update the linking pages to the new anchors. + +6. **Format and lint the touched files**: `npx prettier --write ` and `npx eslint ` (`.mdx` needs both; see AGENTS.md's linter mapping). Call the binaries directly with file paths; the repo's `npm run prettier:fix` script formats the entire repo and can't be scoped. Note: a longer filename can push wrapped lines past the 80-character limit, causing Prettier to reflow prose and re-pad table rows around the edited links. That churn is expected; mention it in the PR so reviewers don't puzzle over seemingly unrelated line changes. + +7. **Verify**: run `npm run build` after formatting, so the build validates the final content (broken internal links fail the build). Confirm the new page path exists in `build/` output. The build cannot catch external links to the old URL; that's what the redirect is for, so double-check step 4 happened. + +## Moving a whole section + +For a directory move, repeat the sweep per page, move the category entry in `sidebars.ts`, and add one redirect per page (Vercel redirects support `:slug*` path parameters for whole-directory moves; prefer one wildcard rule when every page in the directory moves to the same relative location): + +```json +{ + "source": "/toolhive/tutorials/:slug*", + "destination": "/toolhive/guides-k8s/:slug*", + "permanent": true +} +``` + +Only use a wildcard when the mapping is truly uniform; mixed destinations need per-page rules. diff --git a/.claude/skills/review-docs-pr/SKILL.md b/.claude/skills/review-docs-pr/SKILL.md new file mode 100644 index 00000000..98b12fc6 --- /dev/null +++ b/.claude/skills/review-docs-pr/SKILL.md @@ -0,0 +1,47 @@ +--- +name: review-docs-pr +description: > + Review a docs-website pull request as a subject matter expert and tech writer: read the PR at its head ref, apply the docs-review criteria to the changed pages, verify factual claims against source, and draft a body-level review for approval. Use whenever the user wants a PR evaluated, even informally: "review PR 1069", "take a look at the registry docs PR", "thoughts on this?" with a PR URL, or an initial reaction to a PR they want checked. For reviewing loose files or uncommitted changes (no PR involved), use docs-review directly. +argument-hint: '' +--- + +# Review a documentation PR + +Review the PR's content for accuracy, clarity, and consistency with the project's standards. The output is a draft review shown to the user; never post anything to GitHub without explicit approval. + +## Gather the PR state + +1. Fetch PR metadata: title, body, author, state, `headRefName`, `baseRefName`, and the diff (`gh pr view`, `gh pr diff`, or the GitHub MCP tools if available). +2. **Read the changed files at the PR's head ref**, not from the local working tree: `git fetch origin ` and read files at that ref (`git show :`), or check out the branch. Local files may be on a different branch or stale; reviewing them produces wrong line references and stale feedback. +3. Read the full changed pages, not just the diff hunks. A diff-only read misses duplication with adjacent sections, contradictions with unchanged prose, and admonitions that restate the text right above them. + +## Check existing review state + +Before drafting, look at reviews and threads already on the PR: + +- Don't re-raise a point another reviewer already made; agreeing briefly is fine, duplicating is noise. +- A thread that was resolved without the suggested change being applied is an intentional dismissal; don't re-raise it as a new finding. +- For bot-generated release PRs (Renovate/github-actions authors), check whether a human has already pushed fix-up commits; review the current state, not the bot's original. + +## Review the content + +Apply the docs-review skill's criteria (information architecture, LLM-pattern table, accuracy, style guide compliance). Invoke `/docs-review` for the full criteria if not already loaded. In addition: + +- **Verify factual claims at the source.** For content documenting product behavior, the code is the primary source and the docs are what's being verified: check flags, fields, defaults, and API routes against the upstream repo at the relevant tag, not against other docs or memory. +- **Check the PR's own claims.** If the PR body says "build passes" or "links verified", spot-check rather than trusting it. +- **Scope findings to the PR.** Pre-existing issues in surrounding content can be noted as out-of-scope observations or follow-up issue candidates, not blocking findings. + +## Draft the review + +Structure the draft as: + +1. A one-or-two-sentence overall verdict (approve / needs changes, and why). +2. Primary issues (must address before merge), each with the file and a concrete fix. +3. Secondary issues (worth fixing, not blocking). +4. Out-of-scope observations, if any, framed as follow-up candidates. + +Keep it a **body-level review only**: no inline (per-line) review comments. Diff line anchors are unreliable and pending inline comments can conflict with reviews a human has in progress. + +## Get approval before posting + +Show the draft to the user and stop. Post to GitHub only after explicit go-ahead, using the review action the user chooses (`gh pr review --comment`, `--approve`, or `--request-changes`). The user may also take the draft and post it themselves; that's a normal outcome, not a failure. From cb2a19907e5c31ccf125af7bb9ffdac82ff03102 Mon Sep 17 00:00:00 2001 From: Dan Barr Date: Thu, 30 Jul 2026 12:38:10 -0400 Subject: [PATCH 5/5] Fix Cloud UI repo URL Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- .claude/skills/weekly-product-updates/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.claude/skills/weekly-product-updates/SKILL.md b/.claude/skills/weekly-product-updates/SKILL.md index 21375150..57a6a2c2 100644 --- a/.claude/skills/weekly-product-updates/SKILL.md +++ b/.claude/skills/weekly-product-updates/SKILL.md @@ -189,7 +189,7 @@ For detailed release notes, check the project repositories: - [ToolHive Runtimes](https://github.com/stacklok/toolhive/releases) (CLI and Kubernetes Operator) - [ToolHive UI](https://github.com/stacklok/toolhive-studio/releases) -- [ToolHive Cloud UI](https://github.com/stacklok/toolhive-cloud/releases) +- [ToolHive Cloud UI](https://github.com/stacklok/toolhive-cloud-ui/releases) - [ToolHive Registry Server](https://github.com/stacklok/toolhive-registry-server/releases) You can find all ToolHive documentation on the [Stacklok documentation site](https://docs.stacklok.com/toolhive).