メインコンテンツへスキップ
プラグイン (Plugin) は Qoder CLI で、コマンド、子 Agent、Skill、Hook、MCP server などの拡張機能を 1 つのディレクトリにまとめ、インストール・有効化・共有しやすくする仕組みです。プラグインのディレクトリには 1 つ以上の拡張リソースを含めることができ、インストール後に CLI が自動で発見・読み込みます。

​
クイックスタート

以下では Skill を 1 つだけ含む最小プラグインを作成し、ローカルディレクトリとしてインストールします。

​
1. プラグインディレクトリを作成

mkdir -p ~/my-plugin/.qoder-plugin
mkdir -p ~/my-plugin/skills/hello

​
2. manifest を作成

すべてのプラグインで plugin.json を宣言することを推奨します。安定したメタ情報を持たせるため、最低限 name を含めてください (詳細は後述の manifest フィールド): ~/my-plugin/.qoder-plugin/plugin.json: 
{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "私の最初のプラグイン"
}

​
3. Skill を追加

~/my-plugin/skills/hello/SKILL.md: 
---
name: hello
description: ユーザーに挨拶する。「挨拶して」と言われたときに使用。
---

# Hello Skill

ユーザーにフレンドリーに挨拶します。

​
4. インストール

qodercli plugins install ~/my-plugin
Plugin "my-plugin@local" installed successfully. Run /plugins reload to apply. が表示されたら、CLI を再起動するか TUI で /plugins reload を実行すると、プラグインが提供する Skill を使えるようになります。

​
プラグインのディレクトリ構成

.qoder-plugin/plugin.json は Qoder が推奨する manifest 配置です。宣言が無い場合も CLI は慣例に従って読み込み、ディレクトリ名をプラグイン名として扱います。慣例ディレクトリは存在すれば自動発見、無ければ無視されます。 
my-plugin/
├── .qoder-plugin/
│   └── plugin.json        # 推奨: manifest (name/version などのメタ情報を宣言)
├── commands/              # カスタムコマンド (.md ファイルまたはサブディレクトリ)
├── agents/                # カスタム子 Agent
├── skills/                # カスタム Skill
├── hooks/
│   └── hooks.json         # Hook 設定
├── output-styles/         # 出力スタイル
├── bin/                   # プラグインの実行ファイル
└── .mcp.json              # プラグイン同梱の MCP server 宣言
各慣例ディレクトリの役割:
ディレクトリ / ファイル用途
commands/カスタムスラッシュコマンドを登録。~/.qoder/commands/ と同じ構造
agents/カスタム子 Agent を登録
skills/Skill を登録。~/.qoder/skills/ と同じ構造
hooks/hooks.jsonHook 設定。{ "hooks": ... } ラップ形式で、内側の hooks の値が settings.json の hooks フィールドと同じ構造
output-styles/カスタム出力スタイル
bin/プラグインの実行ファイル
.mcp.jsonプラグイン同梱の MCP server 宣言

​
manifest フィールド

plugin.json は name のみ必須で、他のフィールドはすべて省略可能です。
フィールド必須説明
nameはいプラグインの一意な識別子。空白不可、kebab-case 推奨 (例: my-plugin)
versionいいえセマンティックバージョン (例: 1.0.0)
descriptionいいえ短い説明
authorいいえ著者情報
homepageいいえドキュメントやホームページの URL
repositoryいいえソースリポジトリの URL
licenseいいえSPDX ライセンス識別子 (例: MIT)
keywordsいいえ検索・分類用のタグ配列
上級: manifest では commands / agents / skills / hooks / outputStyles を明示的に宣言して、デフォルトのディレクトリ慣例の上書きやインラインコンテンツの利用も可能です (manifest のフィールド名は camelCase outputStyles、対応する慣例ディレクトリ名は output-styles/ の点に注意)。明示しない場合、CLI は上記の慣例に従って自動発見します。

​
インストールスコープ

プラグインは 3 種類のスコープにインストールできます:
スコープ説明用途
userグローバル。現在のユーザーのすべてのプロジェクトに適用 (デフォルト)個人がよく使うプラグイン
project現在のプロジェクトのみ。プロジェクトレベル settings.json に書き込み、git にコミットしてチーム共有可チーム共有のプロジェクト固有プラグイン
local現在のプロジェクトのみ。プロジェクトローカル settings.local.json に書き込み、.gitignore への追加を推奨ローカル実験用プラグイン

​
コマンド

プラグイン関連のコマンドは qodercli plugins サブコマンドにまとまっており、エイリアスは plugin です。

​
インストール: plugins install

ローカルディレクトリパスからインストール: 
qodercli plugins install ~/my-plugin
qodercli plugins install ./relative/path/to/plugin
qodercli plugins install /abs/path/to/plugin --scope project
引数 / オプション説明
<plugin>ローカルプラグインディレクトリのパス (絶対、相対、~/... いずれも可)
-s, --scope <scope>インストールスコープ: user (デフォルト)、project、local
インストール後は CLI を再起動するか TUI で /plugins reload を実行すると変更が反映されます。

​
アンインストール: plugins uninstall

qodercli plugins uninstall my-plugin
qodercli plugins uninstall my-plugin --scope project --keep-data
エイリアス: remove / rm。
引数 / オプション説明
<plugin>インストール済みプラグイン名
-s, --scope <scope>対象スコープ: user (デフォルト)、project、local
--keep-dataプラグインのデータディレクトリを保持

​
有効化 / 無効化: plugins enable / plugins disable

qodercli plugins enable my-plugin
qodercli plugins disable my-plugin
qodercli plugins enable my-plugin --scope project
qodercli plugins disable --all
引数 / オプション説明
<plugin>インストール済みプラグイン名
-s, --scope <scope>書き込み先スコープ。省略時は自動判定
-a, --all(disable のみ) スコープ内で有効化されているすべてのプラグインを一括無効化
有効化 / 無効化は対応するスコープの settings.json の enabledPlugins フィールドを更新することで行われます。無効化されたプラグインは新しいセッションで読み込まれません。

​
一覧: plugins list

qodercli plugins list
qodercli plugins list --json
qodercli plugins list --plugin-dir ./local-plugins ./more-plugins
オプション説明
--jsonJSON 出力
-o, --output-format <format>text または json (--json と等価)
--plugin-dir <dirs...>指定したディレクトリのプラグインを追加でスキャンしてリストにマージ (自動インストールはしません)

​
検証: plugins validate

ローカルプラグインディレクトリが慣例に沿っているか検証します。開発時に便利: 
qodercli plugins validate ~/my-plugin
検証では発見されたコマンド、Skill、Hook などのコンポーネントが一覧表示され、慣例サブディレクトリが何も無い場合は通知が出ます。ただし validate 自体はそれで失敗しません。plugins install でローカルプラグインをインストールするときは、認識可能なコンポーネントまたはリソースが少なくとも 1 つ必要です (慣例ディレクトリでも、manifest で明示的に宣言されたリソースでも構いません)。
推奨: .qoder-plugin/plugin.json で name、version 等のメタ情報を必ず宣言してください。Qoder が推奨するプラグインの組織方法です——宣言が無い場合、plugins list や enabledPlugins 設定などの場所でディレクトリ名がそのまま識別子として使われ、環境間での識別や共有がしにくくなります。

​
enabledPlugins 設定

有効化 / 無効化の状態は settings.json の enabledPlugins フィールドに保存されます: 
{
  "enabledPlugins": {
    "my-plugin@local": true,
    "another-plugin@local": false
  }
}
  • true: プラグインを有効化
  • false: プラグインを明示的に無効化
設定キーはインストール済みのプラグイン ID と完全一致する必要があります (ローカルインストールしたプラグインの ID は name@local 形式)。plugins list で各プラグインの識別子を確認できます。
このフィールドを直接編集するより、plugins enable / plugins disable の利用を推奨します。スコープ選択や依存関係などをコマンドが処理してくれます。

​
プラグイン Hook の書き方

プラグインは hooks/hooks.json で独自の Hook を宣言できます。ファイルはラップ形式です: トップレベルがオブジェクトで、その中の hooks フィールドの値が settings.json の hooks フィールドと同じ構造になります: 
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "$QODER_PLUGIN_ROOT/scripts/check.sh"
          }
        ]
      }
    ]
  }
}
settings.json との違い: settings.json には直接 hooks フィールドを書きますが、プラグインの hooks/hooks.json は外側に { "hooks": ... } のラップが必要です。
プラグイン由来の Hook 実行時には次の 2 つの環境変数が追加されます:
環境変数説明
QODER_PLUGIN_ROOT現在のプラグインのインストールルートディレクトリ
QODER_PLUGIN_DATA現在のプラグインのデータディレクトリ (インストールディレクトリとは別。アップグレードを跨いで状態を保持しやすい)
Hook の書き方の詳細はフックを参照。