stacklok

Guide for using ToolHive CLI (thv) to run and manage MCP servers and skills. Use when running, listing, stopping, building, or configuring MCP servers locally. Covers server lifecycle, registry browsing, secrets management, client registration, groups, container builds, exports, permissions, network isolation, authentication, and skill management (install, uninstall, list, info, build, push, validate). NOT for Kubernetes operator usage or ToolHive development/contributing.

Validates operator chart contribution practices (helm template, ct lint, docs generation) before committing changes.

Creates ToolHive release PRs by analyzing commits since the last release, categorizing changes, recommending semantic version bump type (major/minor/patch), and triggering the release workflow. Use when cutting a release, preparing a new version, checking what changed since last release, or when the user mentions "release", "version bump", or "cut a release".

Implements a GitHub user story from planning through PR creation, with research, codebase analysis, and structured commits.

Generates polished GitHub release notes for a ToolHive release by analyzing every merged PR, cross-referencing linked issues, dispatching expert agents to assess breaking changes, and producing a formatted release body. Use when the user provides a GitHub release URL, tag name, or says "release notes".

Finds flaky tests on the main branch by analyzing GitHub Actions failures, ranks them by frequency, and enters parallel plan mode to design deflake strategies. Use when you want to find and fix the flakiest tests.

Augments human code review by summarizing changes, surfacing key review questions, assessing test coverage, and identifying low-risk sections. Use when reviewing a diff, PR, or code snippet as a senior review partner.

Reviews vMCP code changes for known anti-patterns that make the codebase harder to understand or more brittle. Use when reviewing PRs, planning features, or refactoring vMCP code.

Deep links in ToolHive Studio. Use when implementing, debugging, or asking about deep link features (toolhive-gui:// protocol), adding new deep link intents, understanding the deep link architecture, IPC model, or platform/packaging support.

Spin up and interact with ToolHive Studio's containerized dev environment (Xvfb + noVNC + DinD). Use when running, testing, or debugging the app in isolation — locally, in a git worktree, or in GitHub Codespaces; when touching `.devcontainer/*`, `scripts/devcontainer-*.sh`, or the `devContainer:dev` npm script; or when debugging "blank white window", "Docker daemon failed to start", or "Missing X server" errors in the devcontainer. The container is fully isolated: no host pnpm install, no host Docker socket, no host X11/GPU — experiment freely without contaminating the host.

Remediate security vulnerabilities found by Grype or pnpm audit. Use when a security scan fails, a CVE needs fixing, or you need to analyze, upgrade, override, or ignore a vulnerable dependency.

Reproduce and fix bugs using TDD. Use when analyzing a bug report, writing a regression test, or applying a minimal fix. Covers test placement, mock patterns, and the red-green-refactor workflow for automated bug fixing.

Start here for all API mocking in tests. Covers auto-generation, fixtures, and when to use other skills. Required reading before creating, refactoring, or modifying any test involving API calls.

Test that components send correct query parameters or request arguments. Use when testing filtering, sorting, pagination, or any read operation where request parameters matter. Use for test-scoped mock customization.

REQUIRED for editing any skill file. Ensures changes sync to Claude, Codex, and Cursor. Never edit .claude/skills/ files directly - always use this skill.

Verify API requests in tests. Use when testing that correct API calls are made for create, update, or delete operations. Use when testing mutations, form submissions, or actions with backend side effects.

Add new MCP server entries to the ToolHive registry. Creates server.json and icon.svg files with correct schema, _meta extensions, and validation. Use when adding a server, creating a registry entry, onboarding an MCP server, or writing server.json. NOT for reviewing existing entries (use mcp-review).

Review MCP server specifications and updates for compliance, security, and quality. Use when evaluating server.json files, PRs adding/updating servers, or assessing MCP server changes. NOT for creating new entries (use add-mcp-server instead).

Audit existing ToolHive catalog server entries for drift: whether the pinned image still exists, the upstream repo is still alive and active, and the declared env vars and network-permission profile still match what the server actually needs. Use whenever asked to audit, health-check, sweep, or spot-check catalog entries / server.json files for staleness, broken images, dead repos, abandoned projects, or wrong env-vars/permissions - for the community tier, the official tier, the whole registry, or a named subset. Report-only; it never edits entries. NOT for reviewing a new submission (use mcp-review) or creating one (use add-mcp-server).

Review skill submissions and updates for compliance, security, and quality. Use when evaluating skill.json files, SKILL.md content, PRs adding/updating skills, or assessing skill changes in the ToolHive registry. NOT for reviewing MCP server entries (use mcp-review) or creating new skills (use add-mcp-server).

Audit and harden GitHub Actions workflows against prompt injection, pull_request_target exploits (Pwn Requests), expression injection, cache poisoning, credential theft, and supply chain attacks. Based on Clinejection and hackerbot-claw campaigns. Use when reviewing CI/CD security, securing AI agent workflows, hardening publishing pipelines, or checking for GitHub Actions misconfigurations. Also covers slash command authorization, CLAUDE.md protection, and network egress. NOT for general CI/CD optimization or non-security workflow issues.

Reviews pull requests by analyzing code changes, checking for common issues, and providing structured feedback with suggestions.

Guide for creating effective skills. Use when users want to create a new skill, update an existing skill, build a slash command, or extend agent capabilities with specialized knowledge, workflows, tool integrations, or custom commands.

Generate weekly product updates by analyzing GitHub activity across ToolHive repositories and transforming technical changes into marketing-ready content. Use when you need to create product announcements, blog posts, or customer communications summarizing what shipped.

Analyze an upstream project's new release, verify changes against source code, and update documentation. Covers discovery, deep-dive into PRs/issues, docs audit, source-verified implementation, and review feedback handling.

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.

Fast CRD schema validation for ToolHive documentation. Extracts all YAML blocks from K8s and vMCP docs, runs kubectl apply --dry-run=server to catch field name errors, type mismatches, and schema drift. No cluster resources are created. Use for: "dry-run the docs", "validate the YAML", "check for schema issues", "run a quick doc check", or after any CRD/API change to catch doc rot. Requires a Kubernetes cluster with ToolHive CRDs installed.

Test ToolHive documentation by executing the steps in tutorials and guides against a real environment, verifying that examples are correct and ToolHive has not regressed. Use when the user asks to test, validate, or verify documentation such as: "test the vault integration tutorial", "verify the K8s quickstart", "check the CLI install docs", "test toolhive vault integration in kubernetes", or any request to run through a doc's instructions to confirm they work. Supports both Kubernetes-based docs (tutorials, K8s guides) and CLI-based docs.

Updates vMCP YAML examples in documentation, verifies against toolhive source, and creates e2e tests

Start the Registry Server via docker compose and run a suite of curl-based smoke tests covering system, read-only MCP API, admin API, entry lifecycle, and OAuth/auth enforcement scenarios.

Deploy the ToolHive Registry Server to a Kind cluster with CloudNativePG (CNPG) PostgreSQL database. Use when you need a production-like PostgreSQL setup with the CNPG operator.

Deploy the OpenTelemetry observability stack (Prometheus, Grafana, OTEL Collector) to a Kind cluster for testing registry server telemetry. Use when you need to set up monitoring, metrics collection, or observability infrastructure.

Deploy the ToolHive Registry Server to a Kind cluster with telemetry enabled. Use when you need to deploy the registry server for testing with OTEL metrics and tracing.

Build or update a domain model by conversation. Use when the user wants to add or change an entity, relationship, attribute, action, invariant, or scenario in a *.modelith.yaml file, or describes product concepts they want captured in the model. Drafts the YAML, asks clarifying questions where a definition is fuzzy, runs the linter, and regenerates the committed Markdown. For a read-only check that explains findings without editing, use domain-model-lint instead.

Load a domain model into the working context before a coding task. Use at the start of a session that will touch product concepts, when the user says "use the domain model" or "load the model," or before implementing a feature in a repo that has a *.modelith.yaml. Makes the agent reason in the team's vocabulary — entity names, relationships, and invariants.

Run modelith lint on a domain model and explain the findings — a read-only review pass. Use when the user asks to check, validate, or review a *.modelith.yaml file, or wants to know what is missing or inconsistent. Turns the linter output into a prioritized, actionable summary. To actually change the model (add or edit entities, fix the gaps), use domain-model-author.

Creates spec.yaml configurations for packaging MCP servers as containers. Use when adding a new MCP server to Dockyard, creating a spec.yaml file, or packaging npm/PyPI/Go MCP servers.

Reviews pull requests for MCP server updates in the Dockyard repository. Use when reviewing PRs that update MCP server versions (spec.yaml changes), add new MCP servers, or modify security allowlists. Evaluates against ToolHive registry criteria including security, provenance, and quality.

Scans MCP servers in the Dockyard repository for security issues using Cisco AI Defense mcp-scanner. Evaluates findings, identifies false positives, and updates security allowlists in spec.yaml files.

Help respond to review comments on an RFC pull request. Use when the user wants to address, reply to, or resolve feedback on an open RFC PR for toolhive, toolhive-studio, toolhive-registry, toolhive-registry-server, toolhive-cloud-ui, or dockyard projects.

Review RFCs for the ToolHive ecosystem. Use when the user wants to review, critique, or provide feedback on an RFC for toolhive, toolhive-studio, toolhive-registry, toolhive-registry-server, toolhive-cloud-ui, or dockyard projects.

Write RFCs for the ToolHive ecosystem. Use when the user wants to create a new RFC, proposal, or design document for toolhive, toolhive-studio, toolhive-registry, toolhive-registry-server, toolhive-cloud-ui, or dockyard projects.

Transform an OpenAPI 3.x spec and workflow descriptions into a validated mcp-scope.yaml that ultimately gets used to generate an MCP server. Guides the AI through spec analysis, semantic grouping, tool naming, description writing, and auth detection with interactive user gates. Use when a user wants to scope an API for MCP server generation.

Validate a generated MCP server project against the mcp-scope.yaml and OpenAPI spec that drove its generation, then suggest hint-driven improvements. Part of the mcp-builder pipeline that transforms an OpenAPI 3.x spec into a ToolHive-ready MCP server across four phases — AI Scoping, Human Review, Deterministic Code Generation, and AI Validation & Polish (this skill). Use when a user has a generated MCP server project (Phase 3 output) and wants to validate it before deployment.

Place generated MCP server deployment manifests into a cluster repo, fill in placeholders by inferring values from existing cluster configuration, and explain remaining manual steps. Use when you have a generated MCP server project and a cluster repo where you want to deploy it.