KeiSeiKit-1.0/PLUGIN.md

KeiSeiKit — Anthropic Claude Code plugin format

This document describes the plugin-format install path (v0.16+) and how it relates to the classic ./install.sh path. Both paths are supported; use whichever fits.

TL;DR

# One-time
/plugin marketplace add KeiSeiLab/KeiSeiKit-1.0
# Install
/plugin install keisei@keisei-marketplace

The plugin auto-registers: agents, skills, hooks, and the MCP server. No manual ~/.claude/settings.json edits. No install.sh needed for the core (non-primitive) experience.

Layout

The repo follows the Anthropic Claude Code plugin spec:

.claude-plugin/
  plugin.json          # plugin manifest (name, version, author, license, keywords)
  marketplace.json     # marketplace manifest — lets this repo serve as a marketplace source
  mcp-template.json    # template for .mcp.json (copy to repo root; see "MCP prerequisite" below)
agents/                # auto-discovered by Claude Code at plugin-install time
skills/<name>/SKILL.md # auto-discovered
hooks/hooks.json       # PreToolUse / PostToolUse / Stop hooks with ${CLAUDE_PLUGIN_ROOT} paths
.mcp.json              # MCP server registration (see prerequisite note)

Paths inside hooks/hooks.json use ${CLAUDE_PLUGIN_ROOT} (expanded by Claude Code at runtime to the plugin install directory) rather than absolute $HOME/.claude/hooks/... paths. This lets the same hooks ship unchanged whether the plugin is installed from GitHub, npm, or a local path.

Plugin install vs classic install — what differs

Feature	Plugin install	Classic ./install.sh
Agents registered	yes, automatic	yes, copied to ~/.claude/agents/
Skills registered	yes, automatic	yes, copied to ~/.claude/skills/
Hooks wired	yes, via hooks/hooks.json	requires --activate-hooks (jq-merge of settings-snippet.json)
MCP server	yes, via .mcp.json (uses @keisei/mcp-server from keigit.com — requires ~/.npmrc setup, see below)	same
47 Rust primitives	no — plugin ships manifest sources only; no cargo build	yes, --profile=<name> builds the selected set
13 shell primitives	no	yes, copied to ~/.claude/agents/_primitives/
Disk footprint	~2 MB (plugin cache)	~2 MB minimal up to ~200 MB full
Update path	/plugin update keisei	git pull && ./install.sh
Update visibility	Claude Code shows version change	silent

Bottom line: plugin install is the right default for the agent-kit experience (agents + skills + hooks). For the Rust primitives (tomd, kei-ledger, provision-hetzner, kei-migrate, etc.), fall back to the classic installer or run it alongside the plugin — the two don't collide because the plugin namespaces into its own install dir and the classic installer writes to ~/.claude/.

Prerequisites

For plugin install:

• Claude Code 2.1+ (check with claude --version)
• Network access to github.com/KeiSeiLab/KeiSeiKit-1.0 on /plugin marketplace add

For the MCP server subset:

• @keisei/mcp-server available from keigit.com (https://keigit.com/api/packages/keisei/npm/). One-time ~/.npmrc setup:

  @keisei:registry=https://keigit.com/api/packages/keisei/npm/
  //keigit.com/:_authToken=<keigit PAT with read:package>
  

  Without the ~/.npmrc rows, npx cannot resolve the scoped package and the keisei MCP server simply won't appear in your tool list — the agents, skills, and hooks all work without it.
• Node.js 18+ (for npx to fetch the server on demand)

For the Rust primitives (classic install only):

• Rust stable, jq, plus the soft-deps listed in the main README per-profile table.

Known limitations

1. Rust primitives not auto-installed. The plugin format doesn't currently express "also run cargo build at install time". We ship the manifest sources in-repo so that users who want the primitives can run ./install.sh --profile=full alongside the plugin. A future version may add pre-built release binaries for common platforms (macOS arm64/x86_64, Linux x86_64) into bin/ so the plugin can ship primitives without a cargo step.
2. @keisei/mcp-server lives on keigit.com, not npm.org. The .mcp.json entry uses npx -y @keisei/mcp-server which resolves through the ~/.npmrc @keisei:registry line above. Without that line, npx will hit npm.org by default and 404. See _ts_packages/packages/mcp-server/README.md for the publish pipeline.
3. Hooks use ${CLAUDE_PLUGIN_ROOT}. This is the official Claude Code plugin variable. Older Claude Code versions (<2.1) that predate plugin support will not expand this variable — stick with classic install on those versions.
4. No version-pinning yet. /plugin install keisei@keisei-marketplace installs the default branch HEAD. For reproducible team installs, add the --ref=<tag> flag once it lands in Claude Code (currently in the spec per the extension schema ref field).

Feedback & bugs

Open an issue at github.com/KeiSeiLab/KeiSeiKit-1.0/issues. A well-formed problem description is already half the solution.

References

• Anthropic Claude Code plugins docs
• README.md — main install guide (plugin section is the new default)
• settings-snippet.json — retained for classic install; the plugin path does not use it
• install.sh --help — classic installer options, now with a plugin-first banner