Skip to Content
ReferenceCLIコマンドplugin

plugin コマンド

pluginコマンドは、Kova を npm パッケージで拡張するためのコマンドです。プラグインは create 関数（PluginFactory）をエクスポートする npm パッケージで、インストール時にスキルリンクの登録などを通じて Kova のコマンド／スキル空間を拡張します。

構文

kova plugin <subcommand> [options]

サブコマンド一覧

サブコマンド説明
install <package>npm パッケージをインストールしてプラグインとして登録
uninstall <package>プラグインの登録を解除し npm パッケージをアンインストール
listインストール済みプラグイン一覧

すべて owner-only 操作（OperationKind 分類）。agent モードでは INTERACTIVE_INPUT_REQUIRED でブロックされます。

plugin install

npm パッケージをインストールし、create 関数を読み込んでプラグインを登録します。プラグインの依存先プラグインがあれば先に解決します。

構文

kova plugin install <package>

動作

  1. pnpm / yarn / npm を順に検出して使用可能な package manager を選定（detectPackageManager）
  2. <package> を npm install 相当でインストール
  3. import('<package>') で create 関数（PluginFactory）を読み込み
  4. 依存プラグイン（plugin.dependencies）が未インストールなら先にインストール
  5. Kova config にプラグイン名を登録し、プラグインが提供するスキルをリンク

create 関数をエクスポートしないパッケージは「Kova プラグインではない」として INVALID_PARAMS で失敗します。

使用例

⚠ 現時点で公開済みの kova プラグインはありません。下記の @example/... は 動作するパッケージではない説明用プレースホルダ です。実在パッケージ @komlock_lab/jpyc-ec は GitHub Packages のみで配布されているため、利用には別途設定が必要です（GitHub Packages 経由のインストール を参照）。

kova plugin install @example/my-plugin

出力例:

{
  "ok": true,
  "data": {
    "plugin": "@example/my-plugin",
    "installed": true,
    "skills": ["my-skill"]
  }
}

依存プラグインを伴うインストール:

{
  "ok": true,
  "data": {
    "plugin": "@example/derived-plugin",
    "installed": true,
    "skills": ["derived-skill"],
    "dependencies": ["@example/base-plugin"]
  }
}

GitHub Packages 経由のインストール

@komlock_lab/jpyc-ec のように GitHub Packages のみで配布されているプラグインをインストールする場合は、事前に registry と認証情報を設定する必要があります。

# 1. @komlock_lab スコープを GitHub Packages に向ける
npm config set @komlock_lab:registry https://npm.pkg.github.com
 
# 2. read:packages スコープ付きの GitHub Personal Access Token (PAT) を登録
#    PAT は https://github.com/settings/tokens で発行
npm config set //npm.pkg.github.com/:_authToken <YOUR_PAT>
 
# 3. インストール
kova plugin install @komlock_lab/jpyc-ec

PAT は最低でも read:packages 権限を持つ classic token、または Packages: Read 権限の fine-grained token が必要です。

plugin uninstall

プラグインのスキルリンクを解除し、npm uninstall 相当でパッケージを削除します。他のプラグインに依存されている場合は失敗します（依存元を先に削除する必要あり）。

構文

kova plugin uninstall <package>

使用例

kova plugin uninstall @example/my-plugin

出力例:

{
  "ok": true,
  "data": {
    "plugin": "@example/my-plugin",
    "uninstalled": true,
    "skills": ["my-skill"]
  }
}

依存元が残っている場合:

{
  "ok": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Cannot uninstall \"@example/base-plugin\": the following plugins depend on it: @example/derived-plugin. Uninstall them first."
  }
}

plugin list

インストール済みプラグインのパッケージ名一覧を表示します。

構文

kova plugin list

使用例

kova plugin list

出力例:

{
  "ok": true,
  "data": {
    "plugins": [
      "@example/my-plugin"
    ]
  }
}

未インストールの場合:

{
  "ok": true,
  "data": {
    "plugins": []
  }
}

プラグインの作り方

Kova プラグインは、create 関数（型: PluginFactory）を default または named export する npm パッケージです。

// package: my-kova-plugin
// entry point: index.js
//
// 注: 本体（@komlock_lab/kova）は minify バンドルのため型定義を同梱していない。
// プラグイン作者向けに `@komlock_lab/kova/plugin-api` サブパスから型のみ
// import できるようにしてある（実装は含まれない、型解決のみ）。
import type { PluginFactory } from '@komlock_lab/kova/plugin-api';
 
export const create: PluginFactory = (ctx) => {
  return {
    name: 'my-plugin',
    skills: ['my-skill'],
    dependencies: [], // 他プラグインへの依存があれば package 名で列挙
    // ... PluginContext を使った初期化
  };
};

PluginContext（ctx）には config / wallet / signer などへのアクセスが含まれます。プラグイン開発ガイドは今後追加予定です。

よくあるエラーと対処法

INVALID_PARAMS（既にインストール済み）

{
  "ok": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Plugin \"@example/my-plugin\" is already installed"
  }
}

対処法: kova plugin list で確認し、再インストールしたい場合は一度 uninstall してから install。

INVALID_PARAMS（create 関数なし）

{
  "ok": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Package \"foo-package\" is not a valid kova plugin (no create export)"
  }
}

対処法: パッケージが create 関数（PluginFactory）をエクスポートしているか確認。任意の npm パッケージを Kova プラグインとして使うことはできません。

INVALID_PARAMS（未インストール）

{
  "ok": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Plugin \"foo-package\" is not installed"
  }
}

対処法: kova plugin list で実際のインストール状況を確認。

UNKNOWN_ERROR（PluginContext 未初期化）

{
  "ok": false,
  "error": {
    "code": "UNKNOWN_ERROR",
    "message": "Plugin context not initialized"
  }
}

対処法: Kova 内部の初期化エラーです。kova のバージョンを確認し、再インストールしてください。

注意点

1. owner-only 操作

install / uninstall は owner-only です。Claude Code 内（agent モード）で勝手にプラグインを書き換えられないよう、TTY + passphrase 経路でのみ実行可能です。

2. package manager の自動検出

pnpm → yarn → npm の順で検出され、最初に見つかった manager を使います。プロジェクトの package manager と異なる場合は明示的に PATH を整えてください。

3. スキルとの違い

skillsplugins
配布形態git リポジトリ + SKILL.mdnpm パッケージ + create 関数
拡張範囲プロンプト + メタデータコード（Kova の機能を拡張）
安全性プロンプトの解釈は AI 任せ任意の Node.js コードが実行される（信頼必須）

プラグインは任意のコードを実行できるため、信頼できる発行元のパッケージのみインストールしてください。

4. アンインストール時の依存チェック

依存元プラグインが残っているとアンインストールに失敗します。依存ツリーは findDependents が解決するため、循環依存を作らないように注意してください。

関連コマンド

  • skills — プロンプトベースの軽量拡張
  • config — プラグイン用の設定値管理
  • launch — インストール済みプラグインを Claude Code 経由で利用

関連項目

Last updated on
skillsterms