toolhive-cli-user

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 commands. Covers server lifecycle, registries, secrets, client registration, builds, permissions, skills, and AI plugins. NOT for Kubernetes operator usage, ToolHive development/contributing, or general AI-client configuration unrelated to ToolHive.

Quality

90%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Quality

Content

86%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A well-structured CLI reference skill: fully executable commands, real one-level-deep bundle references with working anchors, strong guardrails and an error-recovery table. The main weaknesses are command duplication across sections and reference-style presentation of inherently sequential workflows (skill publishing, plugin sync) without explicit ordering or validation checkpoints.

Suggestions

Remove duplicated commands between Quick Start and Managing Servers (keep Quick Start to 4-5 commands and point to the Managing Servers section for the rest) to tighten token efficiency.

Convert the Skills publishing and AI plugin install/sync flows into short numbered workflows with explicit validation steps (e.g., 1. `thv skill validate ./dir` 2. fix reported errors and re-validate 3. only then `thv skill build` and `push`).

In the AI Plugin section, state upfront the required sequence (start `thv serve` → install → `list`/`info` to verify → client-side activation for Codex) rather than distributing the steps across prose paragraphs and the error table.

Dimension	Reasoning	Score
Conciseness	The body is dense and efficient — command blocks with terse one-line comments, no explanations of what MCP, Docker, or registries are, assuming Claude's competence. It falls short of the 5 anchor because of duplication: `thv list`/`status`/`stop`/`rm` appear in both Quick Start and Managing Servers, and `--from-config` appears in both Running and Building sections, so not every token earns its place.	4 / 5
Actionability	Nearly every section is copy-paste-ready shell commands with real flags and concrete values (e.g., `thv run github --secret GITHUB_TOKEN,target=GITHUB_PERSONAL_ACCESS_TOKEN`, `thv build --dry-run --output Dockerfile.mcp uvx://mcp-server-git`), covering the common cases for each command group, with an error table mapping symptoms to specific recovery commands.	5 / 5
Workflow Clarity	Sequences are present and prerequisites are called out ("Setup is required before use: `thv secret setup`", "start `thv serve` first", validate→build→push ordering in Skills), and destructive operations have an explicit confirmation checkpoint plus a symptom→recovery error table. It stops short of the 5 anchor because multi-step flows (skill publishing, plugin install/sync/upgrade, secret setup→use) are presented as parallel command listings rather than explicit ordered workflows with validation checkpoints between steps.	4 / 5
Progressive Disclosure	The body is a clear quick-reference overview that defers detail via well-signaled, one-level-deep references — [COMMANDS.md](references/COMMANDS.md) and [EXAMPLES.md](references/EXAMPLES.md), each linked with section anchors (e.g., `#thv-run`, `#ai-plugin-commands`, `#invoke-a-tool`) that all resolve to real headings in the actual bundle files — and a closing See Also section. No nested references, no inlined bulk reference material.	5 / 5
	Total	18 / 20 Passed

Description

92%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong description: concrete, third-person, comprehensive over the tool's surface, with an explicit 'Use when' clause and explicit out-of-scope boundaries. The only room for improvement is folding a few more natural trigger phrases (registry, secrets, runtime) into the 'Use when' clause rather than just the coverage list.

Dimension	Reasoning	Score
Specificity	The description lists multiple concrete action domains with specific verbs — "run and manage MCP servers, skills, and AI-client plugins", "plugin publishing for Claude Code or Codex" — and its coverage clause ("server lifecycle, registries, secrets, client registration, builds, permissions, skills, and AI plugins") spans the tool's full surface with no evident gaps.	5 / 5
Completeness	It explicitly answers both questions: 'what' ("Guide for using ToolHive CLI (thv) to run and manage MCP servers, skills, and AI-client plugins") and 'when' ("Use when managing `thv ai-plugin` installs, project sync or upgrades, or plugin publishing... also use for MCP server and skill lifecycle commands") with concrete trigger phrases, plus explicit negative scope ("NOT for Kubernetes operator usage...").	5 / 5
Trigger Term Quality	Strong natural-term coverage including the name/command synonym pair "ToolHive CLI (thv)", "MCP servers", "skills", "plugins", "Claude Code", "Codex", "sync or upgrades", and "publishing". A few natural trigger phrasings users might say (e.g., searching/configuring a registry, setting up secrets, container/runtime concerns) appear only as covered topics, not in the explicit 'Use when' clause, so this sits just below the comprehensive synonym coverage of the 5 anchor.	4 / 5
Distinctiveness Conflict Risk	It occupies a clear niche (the thv CLI specifically, named with both product and command) and actively reduces conflict risk with the explicit exclusion "NOT for Kubernetes operator usage, ToolHive development/contributing, or general AI-client configuration unrelated to ToolHive".	5 / 5
	Total	19 / 20 Passed

Validation

93%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: stacklok/toolhive
Path: skills/toolhive-cli-user/SKILL.md
Commit: 4c866b5

Reviewed: 8 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.