# 自分のプラグインを作る

ローカルプラグインは、自分のために作るプラグインです。Gemini、AI Studio、ChatGPT、Claude、DeepSeek の見た目やレイアウトを変えられます。保存されるのは自分のブラウザの中だけです。プルリクエストも、Voyager のソースのコピーも必要ありません。

ほかの Voyager のプラグインと同じく、宣言的です。`plugin.json` のマニフェストと CSS で構成され、独自のコードは実行しません。Voyager はインポート時に内容をチェックし、変更を適用します。オフにすると、すべての変更を取り消します。インポートしたプラグインは最初はオフの状態なので、先に内容を確認できます。

## 作り方は 3 通り

### やりたいことを説明して、任意の AI に書いてもらう

1. 変更したいサイトを開き、Voyager のポップアップを開いて、**ローカルプラグイン** のカードを見つけます（Gemini と AI Studio では、設定の一番下にあります）。
2. **ひとことで画面を変える** を選び、やりたいことを一文で書きます（例：「自分のメッセージを細くして、サイドバーを隠す」）。そのうえで **プロンプトを作成** を選びます。
3. プロンプトを、ご自身で好きな AI のチャットにコピーします。返ってきた回答を丸ごと貼り戻し、**回答をチェック** を選びます。
4. Voyager が、そのプラグインで何が変わるのかを平易な言葉で示します。インポートしたら、プラグイン一覧でオンにしてください。

Voyager がプロンプトをどこかに送信することはありません。使う AI を選ぶのも、テキストを行き来させるのも、ご自身です。

### コーディングエージェントに任せる

Claude Code、Codex、Cursor などのコーディングエージェントを使っている場合は、Voyager のプラグインの skill を渡してください。

```text
https://voyager.nagi.fun/skills/write-voyager-plugin/SKILL.md
```

**ローカルプラグイン** のカードで **ひとことで画面を変える** を開くと、**skill のリンクをコピー** ボタンがあります。skill には、仕様の全体が含まれています。マニフェストのフィールド、各サイトが宣言する内容、プリミティブ、そしてプラグインにできないことです。変更したい内容をエージェントに伝えてください。エージェントはフォルダを作り、`plugin.json` と `style.css` を書き、それらをオフラインでチェックします。その後、ポップアップで **ファイルをインポート** を選び、2 つのファイルを指定します。

skill を残しておきたい場合は、エージェントの skills フォルダに `write-voyager-plugin/SKILL.md` として保存してください（Claude Code の場合は `~/.claude/skills/`）。

### 手で書く

Node.js 18 以降で、次のように実行します。

```sh
npx create-voyager-plugin@latest init my-plugin --site claude
# edit my-plugin/plugin.json and my-plugin/style.css
npx create-voyager-plugin@latest check my-plugin
```

`init` は、そのままチェックを通る `plugin.json` と `style.css` を書き出します。あわせて、そのサイト用のルールをまとめた `AGENTS.md` も作られます。`--site` には、`gemini`、`aistudio`、`chatgpt`、`claude`、`deepseek` のいずれかを指定します。

`check` は、ポップアップのインポートと同じチェックをオフラインで行います。プラグインをインポートできる場合は終了コード 0 を返します。できない場合は、問題ごとに `path: message` の形式で 1 行ずつ表示します。機械が読める形式が必要なら `--json` を付けてください。

## プラグインにできること

- CSS を追加する。スタイルは、プラグインがページに付与する `gv-` のクラスの下に限定されます。
- クラスを追加する、安全な属性やインラインスタイルを設定する、要素を非表示にする。対象は、サイトが宣言しているセマンティックなアンカー（`userTurn`、`assistantTurn`、`composer` など）か、CSS セレクタで指定します。
- ポップアップに設定を用意する（スイッチ、スライダー、ドロップダウン）。設定の値は `{{key}}` のトークンを通じて CSS に渡されます。
- ChatGPT、Claude、DeepSeek では、Voyager のプリミティブ（数式コピー、タイムライン、Mermaid の図など）を有効にできます。また、Voyager 自身の UI の色合いを変えられます。

## プラグインにできないこと

JavaScript の実行、クリックやキー入力への反応、ネットワークからの読み込み（フォント、画像、スタイルシート）、メッセージの内容の読み取りや書き換え、ほかのサイトでの動作はできません。依頼にそれらが含まれる場合は、作成のための資料によって、AI がそのことを伝えたうえで、動作する最も近い形を作るように指示されます。

## インポート時にチェックされるルール

共通のマニフェストのチェック（[プラグイン貢献ガイド](./plugin-contribution.md) を参照）に加えて、ローカルプラグインは次のことを満たす必要があります。

- Voyager が対応しているサイトの中の URL にだけ一致すること。
- 一致するすべてのサイトが宣言しているセマンティックなアンカーだけを使うこと。
- `addClass` ごとに、`gv-` で始まるクラスを 1 つだけ追加すること。
- 設定に使えるのは boolean、number、select のみであること（string と color は、まだポップアップの UI がありません）。
- Gemini と AI Studio では `theme` を使わないこと。また、各サイトで許可されたプリミティブだけを使うこと。Gemini では `formulaCopy`、`vimInput`、`userLatex`、`codeCollapse`、`mermaid`、`wavedrom`、`echarts`、`sendShortcut`、`draftSave`、`turnNavigator` が使えます。AI Studio では `formulaCopy` と `sendShortcut` が使えます。これらは、Voyager 自身の設定と同じコードを実行します。`formulaCopy` と `vimInput`（数式コピーと入力欄の Vim モード）は、ページごとに 1 つだけ動きます。組み込みの設定とプラグインの両方が動くことはありません。ページの読み込み時や、どちらも動いていないときは、組み込みの設定が優先されます。その後は、すでに動いている方がそのまま動き続け、もう一方は一時停止と表示されます。一方をオフにすると、もう一方に機能が引き継がれます。`userLatex`、`codeCollapse`、`mermaid`、`wavedrom`、`echarts` は、要素ごとに担当を決めるため、組み込みの設定と並んで動作します。相手がすでに扱っている行やコードブロックには、手を出しません。

個人向けの Gemini では、`params.dataBackend: "shared"` と `engine: ">=1.9.0"` を指定すると、ローカルの `turnNavigator` を使えます。公式のタイムラインと同じ、ネイティブのスターと階層のデータを読み書きします。会話、アカウント、ターンの識別に関するパラメータは上書きできません。公式の **タイムラインを表示** の設定と競合するため、ローカルプラグインを有効にする前に、その設定をオフにしてください。公式のタイムラインに戻すには、先にローカルプラグインを無効にし、そのあとで設定をオンにします。Business、Enterprise、独自のサイトの範囲は対象外です。

翻訳（`i18n`）は任意です。

## 共有する

ローカルプラグインは、ご自身のブラウザの中だけに残ります。別の環境に移すには、プラグイン一覧から JSON をエクスポートしてください。みんなの役に立つと考えるなら、公式カタログへの掲載を提案することもできます。その流れについては、[プラグイン貢献ガイド](./plugin-contribution.md) で説明しています。

どのサイトでも、送信ショートカットのプラグインは、ページごとに 1 つだけが動きます。送信モードをほかのプラグインが使っている場合、もう一方は競合として報告され、一時停止のままになります。任意の `mode`（`"engine": ">=1.9.0"` が必要）には、`ctrlEnterSends`（既定）または `enterSends` を指定できます。IME の確定では送信されません。Gemini と AI Studio でも利用できます。対応するモードは次のとおりです。

Gemini では、`sendShortcut` で公式の Ctrl/Cmd+Enter 機能を置き換えられます。まず公式の設定をオフにし、そのあとでローカルプラグインを有効にしてください。対応しているのは `ctrlEnterSends` だけで、Enterprise では動作しません。`composerRoot` は通常の入力欄と編集用の入力欄の両方を対象にし、`sendButton` は停止ボタンを除外します。

AI Studio の `sendShortcut` には、`params.mode: "enterSends"` が必要です。ローカルプラグインに引き継ぐには、公式の Enter 送信の設定をオフにします。Ctrl/Cmd+Enter は改行になり、Shift/Alt+Enter はホストの動作に従います。

Gemini の `draftSave` は、公式と同じ `gvDraft_<完全な pathname>` の記録を共有します。`/u/N` と Gem の経路も含まれます。無効にしても、保存された下書きは残ります。同じページで複数のプラグインが、これらの記録を使うことがあります。ページを閉じる前に、最後の入力を保存しようとします。ただし、ブラウザを閉じる場合は、非同期の保存が完了することは保証できません。書き込みと整理の調整は、このページの中だけで行われます。同じ `/u/N` のスロットの中でメールアドレスを切り替えた場合も、保存済みの下書きは共有されます。