> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# プラグイン

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

## クイックスタート

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

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

```bash theme={null}
mkdir -p ~/my-plugin/.qoder-plugin
mkdir -p ~/my-plugin/skills/hello
```

### 2. manifest を作成

すべてのプラグインで `plugin.json` を宣言することを推奨します。安定したメタ情報を持たせるため、最低限 `name` を含めてください (詳細は後述の [manifest フィールド](#manifest-フィールド)):

`~/my-plugin/.qoder-plugin/plugin.json`:

```json theme={null}
{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "私の最初のプラグイン"
}
```

### 3. Skill を追加

`~/my-plugin/skills/hello/SKILL.md`:

```markdown theme={null}
---
name: hello
description: ユーザーに挨拶する。「挨拶して」と言われたときに使用。
---

# Hello Skill

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

### 4. インストール

```bash theme={null}
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.json` | Hook 設定。`{ "hooks": ... }` ラップ形式で、内側の `hooks` の値が `settings.json` の `hooks` フィールドと同じ構造 |
| `output-styles/`   | カスタム出力スタイル                                                                             |
| `bin/`             | プラグインの実行ファイル                                                                           |
| `.mcp.json`        | プラグイン同梱の MCP server 宣言                                                                 |

`agents/` で配布する Subagent も `isolation: worktree` を宣言できます。隔離されたコピーで実行したい実装系 Subagent に向いています。

## 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`

ローカルディレクトリパスからインストール:

```bash theme={null}
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`

```bash theme={null}
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`

```bash theme={null}
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`

```bash theme={null}
qodercli plugins list
qodercli plugins list --json
qodercli plugins list --plugin-dir ./local-plugins ./more-plugins
```

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

### 検証: `plugins validate`

ローカルプラグインディレクトリが慣例に沿っているか検証します。開発時に便利:

```bash theme={null}
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` フィールドに保存されます:

```json theme={null}
{
  "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` フィールドと同じ構造になります:

```json theme={null}
{
  "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 の書き方の詳細は[フック](./hooks)を参照。

## マーケットプレイス（Marketplace）

マーケットプレイスはプラグインの集中配布ソースです。マーケットプレイスを追加することで、ローカルディレクトリを手動管理せずにプラグインを検索・インストールできます。

### マーケットプレイスの追加

複数のソース形式に対応しています:

```bash theme={null}
# Git リポジトリ (HTTPS / SSH)
qodercli plugins marketplace add https://git.example.com/org/my-marketplace.git
qodercli plugins marketplace add git@git.example.com:org/my-marketplace.git

# Owner/repo ショートハンド（対応する git ホスト向け）
qodercli plugins marketplace add org/my-marketplace

# ローカルディレクトリ
qodercli plugins marketplace add /path/to/marketplace

# marketplace.json を指す URL
qodercli plugins marketplace add https://example.com/marketplace.json
```

### 設定済みマーケットプレイスの一覧

```bash theme={null}
qodercli plugins marketplace list
qodercli plugins marketplace list --json
```

### マーケットプレイスの更新

ソースからプラグインカタログを再取得します:

```bash theme={null}
# 指定マーケットプレイスを更新
qodercli plugins marketplace update my-marketplace

# すべてのマーケットプレイスを更新
qodercli plugins marketplace update
```

### マーケットプレイスの削除

```bash theme={null}
qodercli plugins marketplace remove my-marketplace
```

削除すると、そのマーケットプレイスからインストールされたプラグインも一緒にアンインストールされます。

### マーケットプレイスからプラグインをインストール

マーケットプレイスを追加した後、プラグイン名でインストールできます:

```bash theme={null}
qodercli plugins install hello-world
```

CLI は設定済みのマーケットプレイスから自動的にプラグインを探してインストールします。インストール後のプラグイン ID は `name@marketplace-name` の形式になります。

### インストール可能なプラグインの一覧

```bash theme={null}
qodercli plugins list --available --json
```

設定済みマーケットプレイスからまだインストールされていないプラグインの一覧を返します。

### インストール済みマーケットプレイスプラグインの更新

```bash theme={null}
qodercli plugins update hello-world
```