stacklok

Guide for using ToolHive CLI (thv) to run and manage MCP servers, skills, and AI-client plugins. Use when managing `thv ai-plugin` installs, project sync or upgrades, or plugin publishing for Claude Code or Codex; also use for MCP server and skill lifecycle…

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…

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…

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.

Cut a tagged release of mecatl — dispatch the Create Release PR workflow, review and merge the release PR, then verify the tag and the artifacts it publishes (images + Helm charts to GHCR, plus a GitHub Release with signed archives and a Homebrew formula…

Use when writing or substantively editing user-facing documentation: drafting a new page, rewriting or restructuring an existing one, adding a major section, or turning engineering material (PR descriptions, specs, release notes, rough notes) into docs.…

Review completed non-trivial code across four independent axes: Spec, Standards, Test adequacy, and installed Domain specialists. Use proactively after implementation, modification, refactoring, bug fixes, feature work, or when asked to review/audit/check a…

Profile-driven performance optimization of mecatl using the offline benchmark + scenario harness. Use when optimizing allocations or latency, reducing allocs/op or memory, profiling a Go benchmark, pinpointing a hotspot with pprof, proving a win with…

Configure, write, or tune the mecatl learning: settings policy, including learning.mode, sensitivity, reflection budgets, and validated/evaluated activation. NOT for running /reflect, reviewing proposals or memories, drafting skills, model routing,…

Designs and writes a mecatl model router configuration (the `models:` subtree of ~/.config/mecatl/settings.yaml) tailored to the operator's preferences. Asks about priorities (cost vs capability, open vs proprietary, provider, multimodal) then searches the…

Interpret the mecatl perf MCP server's output to diagnose latency, goroutine leaks, GC pressure, allocation churn, and memory growth in a running mecatl harness. Use when connected to the mecatl perf MCP server (the perf:// resources or the query_metric /…

Refresh the mecak8s image in the local mecatl-dev Kind cluster and build mecatui locally, so the user can manually verify in-flight mecatl changes against a real k8s deployment.

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…

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.

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…

Write clear, focused technical documentation following the Diataxis framework and the project style guide. Use whenever writing or substantively editing a documentation page: drafting a new page, rewriting or restructuring an existing one, adding a major…

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…

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…

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…

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…

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/*`,…

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…

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…

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…

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…

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.

Use when writing or substantively editing user-facing documentation: drafting a new page, rewriting or restructuring an existing one, adding a major section, or turning engineering material (PR descriptions, specs, release notes, rough notes) into docs.…

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…

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…

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,…

A relentless interview to sharpen a plan or design, capturing decisions in this repo's canonical homes as they land. Use when the user wants to stress-test a design and record what comes out of it.

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.

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.

Creates spec.yaml configurations for packaging agent skills as OCI artifacts. Use when adding a new agent skill to Dockyard, creating a skills/*/spec.yaml file, or vendoring a third-party skill repository (e.g. from Anthropic, Datadog, HashiCorp, Hugging…

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…

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 any project in this repository (toolhive, mecatl, ...), including the toolhive, toolhive-studio, toolhive-registry,…

Review RFCs for any project in this repository (toolhive, mecatl, ...). Use when the user wants to review, critique, or provide feedback on an RFC, including ones for the toolhive, toolhive-studio, toolhive-registry, toolhive-registry-server,…

Write RFCs for any project in this repository (toolhive, mecatl, ...). Use when the user wants to create a new RFC, proposal, or design document for a project covered here, including the toolhive, toolhive-studio, toolhive-registry, toolhive-registry-server,…

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…

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…

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…

Operate matlatl, the CLI that maps a repo's markdown into a link graph and reports broken links/anchors, orphans, and unreachable, under-linked, or dead-end docs. Use it to: gate docs in CI / fail a PR on broken links ("check the docs", "are there broken…