ai-docs

Create a mod

Properties1
tagsclaude-code, plugins, mods, hooks

原典: Create a mod ／ 日本語版

一行要約

mod は Claude に頼めば書いてくれる（組み込みの plugin-authoring skill を使う）。Claude が書いた mod は承認するまで走らず、作ったセッションでしか読まれない。自分で書くなら .js / .ts を Node もビルドも無しにそのまま読ませ、claude plugin validate と生成される型定義を、どのページよりも正として扱う。

要点

Claude に書かせる

対話セッションで「プロンプトの上に今の git ブランチを出す mod を作って」のように頼む。Claude は ~/.claude/dev-mods/<セッション ID>/ の下に書く。

  • default / acceptEdits では、~/.claude は protected path なので、ファイルごとに作成の承認を求められる
  • 最初のファイルが保存されると、このセッションで hot reload を有効にするかを聞かれる。Enable for this session ならターンの終わりに読み込まれ、変えたターンの終わりごとに読み直される。Not now なら何も読まれない（そのセッションを次に始めたときに読まれる。読ませたくないならディレクトリを消す）
  • 作ったセッションでしか読まれず、そのフォルダは cleanupPeriodDays を過ぎると消される。残すなら自分の場所にコピーして --plugin-dir で読むか marketplace に載せる

Claude が書いた mod が読み込まれないセッション: 承認する人がいない（claude -p、dontAsk）、ワークスペースが未信頼、mod が止められている（--safe-mode / --bare / disableAllHooks / 組織の managed settings）。

自分で書く（3ファイル）

plugin.json、hooks/hooks.json（modules キーでコードのパスを指す —— これがあることで plugin が mod になる）、register.js（register 関数を export し、渡された on でイベントごとに hook を登録する）。

hook は3つの引数を受け取る —— mods API の $、イベントの e（凍結された平らなデータ）、next（他の mod と Claude Code 自身の動作へ渡して結果を返す）。

  • observe —— 何かして next(e) を返す
  • answer —— next を呼ばずに自分の結果を返す（/tally のコマンドなど。第2引数の matcher で対象を絞る）
  • rewrite —— 変えたコピーを next に渡す

--plugin-dir で読んだディレクトリは監視され、変更で hooks module が hot reload される。読み直すたびに register が走り直すので、モジュールの変数はリセットされる（残したい値は $.state）。

確かめる

The events and methods can change between releases, so trust these files over any page, this one included, when they disagree.

イベントとメソッドはリリースのたびに変わりうる。だから食い違ったら、このページを含めてどのページよりも、これらのファイルを信じよ。

（「これらのファイル」= 読み込むたびに mod の .claude-plugin/types/ に書かれる、その版の TypeScript 宣言ファイル）

claude plugin validate はセッションを始めずに、Claude Code が読み込み時に走らせるのと同じ静的解析をかけ、hooks: と calls: を出す。静的解析が読めるように書く規則:

  • mods API の呼び出しは $.store.get(...) のように完全な形で書く（$ を渡せるのは同じファイルのトップレベル関数だけ。メソッド・hook の中で定義した関数・別ファイルから import した関数に渡すと検証に落ちる）
  • on のイベント名は文字列リテラル（変数やループは不可）
  • register の中で on という名前を宣言し直さない
  • import はプラグイン内の相対パスだけ（裸の import は claude-code だけ）、ES module で、動的 import() は不可

テスト: claude plugin test でセッション・サインイン・ネットワーク無しに走る。

配る

plugin と同じ（直接渡す / 自分の marketplace / 組織の managed settings / Anthropic のディレクトリ）。claude- で始まるような Anthropic のものに見える名前は validate に落ちる。 開発は --plugin-dir のディレクトリに対して行う —— インストール済みのコピーは版ごとにキャッシュされ、版を上げて入れ直すまで編集が届かない。

そのまま使える具体例

claude --plugin-dir ./first-mod     # 1セッションだけ読み、ファイルの変更で hot reload
claude plugin validate ./first-mod  # hooks: / calls: と、静的解析のエラー
claude plugin test                  # mod のディレクトリで、セッション無しにテスト
make a mod that shows the current git branch above the prompt
/plugin-authoring

原典で言及されている関連文書

バックリンク