How to Install the Spec Kitty Claude Code Plugin
Who is this for (1)
- Stakeholder Persona: Project Owner — Written for the Project Owner reader.
Spec Kitty ships as a native Claude Code plugin that surfaces all canonical
mission commands (/spec-kitty.specify, /spec-kitty.plan, etc.) and built-in
agent profiles directly inside Claude Code.
Prerequisites
- Claude Code CLI v2.0.12 or later (
claude --versionto check). - One of the following for runtime execution:
- a
spec-kittyon PATH from the same release series as the bundle (fastest), or uvinstalled, so the wrapper can run the pinned version withuvx --from.
- a
If you have neither, install the CLI:
uv tool install --prerelease=allow spec-kitty-cli# orpipx install --pip-args=--pre spec-kitty-cliOption 1: Marketplace install (recommended)
# Add the Spec Kitty plugin from the git-based marketplace:claude plugin marketplace add https://github.com/spec-kitty/spec-kitty
# Verify the plugin is listed:claude plugin listThe marketplace entry points Claude Code at dist/spec-kitty-plugins/claude-code/
inside the repository, which contains the pre-built bundle.
Option 2: Dev install (contributors and local builds)
# From the spec-kitty repository root, build the bundle:spec-kitty plugin build --target claude-code
# Use the bundle for a single session:claude --plugin-dir dist/spec-kitty-plugins/claude-code "<your prompt>"
# Or install persistently:claude plugin install dist/spec-kitty-plugins/claude-codeFor build system details, see CONTRIBUTING.md.
Troubleshooting
Plugin agents not appearing in /agents
- Verify the install:
claude plugin list— the plugin should appear asspec-kitty. - If it does not appear, try reinstalling:
Terminal window claude plugin uninstall spec-kittyclaude plugin install dist/spec-kitty-plugins/claude-code
“No usable spec-kitty found” error
The runtime wrapper could not find a CLI it may run. The message names the release series the bundle was built for. Either install that series:
uv tool install --prerelease=allow spec-kitty-cli# orpipx install --pip-args=--pre spec-kitty-clior install uv so the wrapper can run the pinned version on demand:
curl -LsSf https://astral.sh/uv/install.sh | shA spec-kitty from another series is ignored
Delegation to a PATH CLI is gated on spec-kitty --version naming the bundle’s
release series. A shim, wrapper or alias that installs a spec-kitty but prints
no version on --version is treated as unusable and the pinned version runs
instead, so a broken shim never silently becomes the plugin’s runtime. Run
spec-kitty --version yourself if the plugin seems to ignore your install.
Windows: argument forwarding with quoted strings
The Windows CMD wrapper (bin/spec-kitty-wrapper.cmd) uses %* for argument
forwarding, which may mishandle complex quoted arguments. If you encounter
quoting issues on Windows, invoke spec-kitty directly instead of going through
the wrapper.
How the runtime wrapper works
When Claude Code executes a Spec Kitty skill, it calls
bin/spec-kitty-wrapper (bash) or bin/spec-kitty-wrapper.cmd (Windows).
The wrapper resolves a runtime in this order:
- A
spec-kittyon PATH inside the bundle’s release series. The wrapper readsspec-kitty --versionand delegates only when its<major>.<minor>matches the version the bundle was built from. A CLI from another series is ignored rather than run against commands and skills it does not match; an unreachable or unreadable one falls through the same way. - The pinned version through
uvx.uvx --from "spec-kitty-cli==<version>" spec-kitty …names both the distribution and the executable it ships. (The plain formuvx spec-kitty-cli==<version>cannot work:uvxruns an executable named after the distribution, and this distribution shipsspec-kitty.) - The bundle’s series through
uvx. If the exact version is not published (a bundle built from a pre-release or a local build), the wrapper retries withspec-kitty-cli>=<version>,<<next minor>, so the newest published release of the same series runs. - Exit 1 with a remedy naming
uv tool install/pipx install.
The version string is substituted at build time by spec-kitty plugin build.
uvx resolves and caches the package on first use, so the fallback needs network
access once per version.