claude-plugin-converter

Claude Plugin Converter

Claude Code プラグイン（.claude-plugin/plugin.json マニフェストとコンポーネント）を、自己完結型のインストール可能な Hermes プラグイン（plugin.yaml + __init__.py + 同梱スキル／フック）に変換します。

使用するタイミング

• ユーザーが Hermes Agent で Claude Code プラグインを使いたい場合
• ユーザーが「この Claude プラグインを変換して」や「これを Hermes で動くようにして」と依頼した場合
• ユーザーが Claude プラグインのディレクトリ、Git URL、またはマーケットプレイスの参照情報を提供した場合

概要

2 段階のワークフローです。

1. 検出 — Claude プラグインを分析し、変換できる内容とできない内容を報告します
2. 変換 — ユーザーが hermes plugins enable <name> でインストールできる、完全な Hermes プラグインディレクトリを生成します

出力は自己完結型の単一の Hermes プラグインです。スキル、フック、MCP 設定はすべて 1 つの ~/.hermes/plugins/<name>/ ディレクトリにまとめられます。成果物が分散することはありません。

⚠️ セキュリティと信頼境界

信頼できるソースのプラグインのみを変換してください。 コンバーターは、ソースプラグインのシェルコマンド、Python フック、MCP サーバー設定を読み取り、Hermes の出力に反映します。変換されたフックは、ソースプラグインのシェルコマンドを subprocess.run(..., shell=True, ...) 経由で実行する場合があります。

変換したプラグインを有効にする前に、次の内容を確認してください。

• hooks.py を確認する — すべての subprocess.run 呼び出しと _CMD_* 変数を調べ、危険なコマンドがないか確認します
• __init__.py を確認する — 登録される内容（ツール、フック、スラッシュコマンド）を確認します
• mcp_config.yaml を確認する — MCP サーバーのコマンドと環境変数が安全であることを確認します
• MANUAL_STEPS.md を確認する — コンバーターが自動化できなかった内容を把握します

生成された出力を事前に確認せず、信頼できない GitHub リポジトリやマーケットプレイスのプラグインを、むやみに変換して有効にしないでください。

フェーズ 1：検出

分析スクリプトを実行します。

python3 {SKILL_DIR}/scripts/analyze.py <claude_plugin_dir> --output <output_dir>/analysis.json

このスクリプトは .claude-plugin/plugin.json とすべてのコンポーネントディレクトリを読み込み、各コンポーネントの変換可能性評価を含む構造化 JSON を生成します。

調査結果を次の内容を示す表にしてユーザーに提示します。

• そのまま問題なく変換できるもの（✅）
• 一部のみ変換できるもの（⚠️）
• Hermes に相当するものがないもの（⏭️）

コンポーネント間の対応関係の詳細は、references/mapping-tables.md を参照してください。

フェーズ 2：変換

ユーザーの承認後、変換スクリプトを実行します。

python3 {SKILL_DIR}/scripts/convert.py <claude_plugin_dir> --analysis <output_dir>/analysis.json --output <output_dir>/<plugin_name>

これにより、完全な Hermes プラグインディレクトリが生成されます。

<plugin_name>/
├── plugin.yaml              # Translated manifest
├── __init__.py              # register(ctx) — wires tools, hooks, skills, commands
├── schemas.py               # Tool schemas (if MCP servers had custom tools)
├── tools.py                 # Tool handlers (if any)
├── hooks.py                 # Hook callback functions (only if hooks exist)
├── skills/                  # Bundled skills (registered via ctx.register_skill)
│   └── <skill-name>/
│       └── SKILL.md
├── engines/                 # Non-skill data dirs copied from source (engines, foundations, etc.)
├── foundations/
├── connectors/
├── mcp_config.yaml          # MCP server config snippet (for user to merge)
├── CONVERSION_REPORT.md     # Full report: converted, partial, skipped, manual steps
└── MANUAL_STEPS.md           # What the user must do by hand

インストール

変換後、プラグインをインストールします。

cp -r <output_dir>/<plugin_name> ~/.hermes/plugins/
hermes plugins enable <plugin_name>
# Then restart: /reset in CLI or /restart in gateway

プラグインに MCP サーバーが含まれている場合は、mcp_config.yaml の内容を ~/.hermes/config.yaml にマージします。

cat <plugin_name>/mcp_config.yaml >> ~/.hermes/config.yaml
# Or use: hermes mcp add <name> --command <cmd> --args <args>

コンポーネント対応表の概要

Claude のコンポーネント	Hermes の変換先	場所	変換可能性
マニフェスト（plugin.json）	plugin.yaml	プラグインのルート	✅ フィールドを直接対応付け
スキル（skills/*/SKILL.md）	同梱スキル	skills/*/SKILL.md + ctx.register_skill()	✅ フロントマターを対応付け
コマンド（commands/*.md）	スラッシュコマンド	__init__.py 内の ctx.register_command()	⚠️ 形式がより単純なため、ラッパーが必要
フック（hooks/hooks.json）	プラグインフック	hooks.py + ctx.register_hook()	⚠️ 30 件中約 10 件のイベントに相当するものがあります
エージェント（agents/*.md）	委任スキル	skills/<agent-name>/SKILL.md	⚠️ パラダイムの変更が必要
MCP サーバー（.mcp.json）	MCP 設定	mcp_config.yaml のスニペット	✅ 設定形式を変換
LSP サーバー（.lsp.json）	❌ 相当するものなし	—	⏭️ スキップし、レポートに記載
モニター（monitors/*.json）	Cron ジョブ	MANUAL_STEPS.md に記載	⚠️ 概念が異なるため、手動で設定
bin/（PATH 実行ファイル）	プラグインデータファイル	プラグインディレクトリにコピー	✅ 優先度は低い

フロントマターのマッピング（SKILL.md）

Claude フィールド	Hermes フィールド	備考
description	description	そのままコピー
name	name	そのままコピー（ctx.register_skill で使用）
disable-model-invocation	❌	相当するものはありません。Hermes のスキルは常にモデルによって呼び出されます。削除して、その旨を記載してください。
$ARGUMENTS（本文内）	❌	相当するプレースホルダーはありません。「ユーザーのリクエスト」を参照するように書き換えるか、手動確認が必要であることを示してください。
（なし）	version	plugin.json のバージョンを継承
（なし）	author	plugin.json の作成者を継承

フックイベントのマッピング

イベントのマッピング一覧（30 件以上）は、references/mapping-tables.md を参照してください。

主なマッピング：

• PreToolUse → pre_tool_call（どちらも処理をブロックできます）
• PostToolUse → post_tool_call
• SessionStart → on_session_start
• SessionEnd → on_session_end
• UserPromptSubmit → pre_llm_call（どちらもコンテキストを追加できます）
• SubagentStart → subagent_start
• SubagentStop → subagent_stop
• Stop → post_llm_call（最も近い対応イベント）
• PermissionRequest → pre_approval_request

Hermes に相当するイベントがないもの：PostToolBatch、PreCompact、PostCompact、Notification、FileChanged、WorktreeCreate/Remove、CwdChanged、InstructionsLoaded、ConfigChange、TeammateIdle、Elicitation、TaskCreated/Completed。

フックタイプのマッピング

Claude のフックタイプ	Hermes での実装	備考
command（シェル）	subprocess を使う hooks.py 内の Python コールバック	または config.yaml 内のシェルフック
http（URL への POST）	httpx.post() を使う Python コールバック	そのまま実装できます
mcp_tool（MCP ツールの呼び出し）	ctx.dispatch_tool() を使う Python コールバック	スコープ付きのツール名をマッピング
prompt（LLM による評価）	⚠️ 直接相当するものはありません	MANUAL_STEPS に記載してください。一度限りのエージェントを起動する方法が考えられます
agent（エージェントによる検証）	⚠️ 直接相当するものはありません	MANUAL_STEPS に記載してください。delegate_task を使用する方法が考えられます

エージェントから委譲スキルへの変換

Claude のエージェントは、システムプロンプトとフロントマター（model、effort、maxTurns、tools）を含む Markdown ファイルです。

Hermes には単独のエージェント定義がありません。代わりに、各エージェントは delegate_task の使用を指示する同梱スキルになります。

---
name: <agent-name>
description: <from Claude agent description>
---

# <Agent Name>

When the user's task matches this agent's specialty, delegate it:

1. Call `delegate_task` with:
   - `goal`: "<from Claude agent description>"
   - `context`: "<full system prompt from the Claude agent .md file>"
2. Do not attempt the task yourself — delegate it.

## Original Agent Config
- Model: <from frontmatter>
- MaxTurns: <from frontmatter>
- Tools: <from frontmatter, if restricted>

注意点

1. $ARGUMENTS に相当するものは Hermes にありません — Claude のスキルでは、ユーザー入力に $ARGUMENTS を使用します。Hermes のスキルはコンテキストに読み込まれ、エージェントがユーザーのメッセージを自然に読み取ります。手動レビューが必要な項目としてフラグを立てます。

2. disable-model-invocation — Claude では、スキルを手動でのみ実行できます。Hermes のスキルは常にモデルによって呼び出されます。このフィールドを削除し、その旨を記録します。

3. エージェントのパラダイムの違い — Claude には独立したエージェント定義があります。Hermes では実行時に delegate_task を使用します。コンバーターは各エージェントを委任スキルとしてラップしますが、動作は完全には一致しません。

4. Hermes に相当するものがないフックイベントが多数あります — Claude のイベント30件のうち、約20件は変換できません。レポートに明記されます。

5. prompt と agent のフックタイプ — Hermes に直接相当するものはありません。必要に応じてユーザーが手動で実装できるよう、MANUAL_STEPS に記載します。

6. LSP サーバー — Hermes には LSP 統合がありません。スキップされ、レポートに記載されます。

7. ${CLAUDE_PLUGIN_ROOT} がフックだけでなくスキル本文にも登場します — Claude のスキルでは、プラグインのツリー内のファイルを参照するために、Markdown のリンクやインラインコードで ${CLAUDE_PLUGIN_ROOT} を使用します（例：[${CLAUDE_PLUGIN_ROOT}/foundations/doctrine.md](../../foundations/doctrine.md)）。実際のプラグインでは、21個のスキル全体で120か所に登場しました。コンバーターは ${CLAUDE_PLUGIN_ROOT} を ..（skills/<name>/ からプラグインのルートへの相対パス）に置き換えます。Python フックでは、代わりに Path(__file__).parent を使用します。

8. MCP サーバーのスコープ付き名前 — Claude では mcp__plugin_<plugin-name>_<server-name>__<tool> を使用します。Hermes では mcp__<server-name>__<tool> を使用し、プラグインの名前空間はありません。コンバーターでプラグインの名前空間のプレフィックスを削除する必要があります。

9. コマンドとスキルの違い — Claude の commands/ は skills/ よりもシンプルで、フラットな Markdown であり、フロントマターはありません。Hermes のスラッシュコマンドには Python ハンドラーが必要です。コンバーターは各コマンドを、Markdown の内容をプロンプトとして返す ctx.register_command() でラップします。

10. スキル以外のデータディレクトリもコピーする必要があります — Claude のプラグインには、スキルが相対パスで参照するサポート用ディレクトリ（engines/、foundations/、connectors/、docs/）が含まれていることがよくあります。相対リンクが切れないよう、変換したスキルとともに Hermes プラグインの出力ディレクトリへコピーする必要があります。コンバーターは .git、__pycache__、.pytest_cache、tests、隠しディレクトリをスキップし、それ以外はすべてコピーします。

11. __init__.py での条件付きフックインポート — Claude のプラグインにフックがない場合、生成される __init__.py で hooks モジュールをインポートしてはいけません。コンバーターは analysis["components"]["hooks"] を確認し、フックがある場合にのみ from . import hooks の行を生成します。

検証

変換後、プラグインが読み込まれることを確認します。

# Copy to plugins dir (if not already there)
cp -r <output_dir>/<plugin_name> ~/.hermes/plugins/

# Check it's discovered
HERMES_PLUGINS_DEBUG=1 hermes plugins list

# Enable and test
hermes plugins enable <plugin_name>
# Then test skill loading (plugin skills are opt-in, not in available_skills):
hermes chat -q 'Load skill "plugin-name:skill-name" and tell me what it does' -t skills

プラグインのスキルはオプトインであり（<available_skills> には表示されません）、skill_view("plugin-name:skill-name") で読み込まれます。これは想定どおりの動作であり、変換の失敗ではありません。

注意点：パーサーのバグ（テストで発見）

12. monitors.json は単独のリストの場合があります — 常に {"monitors": [...]} とは限りません。アナライザーは isinstance(monitors_data, list) を処理し、リストを直接使用する必要があります。辞書の場合は .get("monitors", []) にフォールバックします。

13. Claude の hooks.json は入れ子構造になっています — 各イベントエントリーには、その内側に hooks 配列があります：{"Stop": [{"hooks": [{"type": "command", "command": "..."}]}]}。アナライザーは外側のエントリーから type／command を直接読み取るのではなく、内側のフック定義を取得するために hook_entry.get("hooks", []) を反復処理する必要があります。外側のエントリーには、内側のすべてのフックに適用される matcher フィールドが含まれる場合もあります。内側に hooks 配列がない場合は、フラットな構造（エントリー自体から type／command を読み取る形式）にフォールバックします。

14. フックのコールバック名は convert_hooks() から generate_init_py() に渡す必要があります — convert_hooks() はコールバック関数名（例：_on_post_llm_call_0）を生成し、hook_infos で返しますが、generate_init_py() は ctx.register_hook() 呼び出しを出力するために、それらの名前を必要とします。{event_name: [callback_name, ...]} の辞書として渡してください。これを省略すると、__init__.py のフックセクションが空になり、フックは実行されません。

15. 複雑な引用符を含むシェルコマンドは、手作業でのエスケープでは正しく処理できません — Claude のフックコマンドには、入れ子になった一重引用符、二重引用符、バックスラッシュが含まれることがよくあります（例：python3 -c "import os; os.environ.get('CLAUDE_PLUGIN_ROOT')..."）。.replace("'", "\\'") を使って手作業でエスケープしないでください。無効な Python コードが生成されます。Python の repr()（!r 書式指定）を使って安全に引用符で囲んだモジュールレベル変数を生成し、その変数を subprocess.run() で参照してください：_CMD_0 = {command!r} として保存し、続けて subprocess.run(_CMD_0, shell=True, ...) を呼び出します。

検証チェックリスト

1. 生成したすべての .py ファイルに対して python3 -c "import py_compile; py_compile.compile('hooks.py', doraise=True)" を実行します
2. プラグインをインストールします：cp -r <name> ~/.hermes/plugins/ && hermes plugins enable <name>
3. ロード失敗がないかログを確認します：grep -i "failed to load plugin" ~/.hermes/logs/agent.log
4. スキルの読み込みをテストします：hermes chat -q 'Load skill "plugin-name:skill-name" and tell me what it does' -t skills
5. プラグインのスキルはオプトイン方式です（<available_skills> には含まれません）。正しいテスト方法は skill_view("plugin:skill") による読み込みであり、skills_list に表示されるかどうかの確認ではありません。

テスト対象

• 21 個のスキルを含む会計スタイルのプラグイン（Python エンジン、基盤、コネクター） — 21 個すべてのスキルを問題なく変換し、${CLAUDE_PLUGIN_ROOT} の参照 120 件を書き換え、データディレクトリをコピーしました。プラグインをロードし、skill_view が正常に動作することを確認しました。

• 複数のコンポーネントを含む 51 個のスキルを持つプラグイン（6 個のエージェント、2 個のフック、1 個のモニター、bin/） — 51 個のスキルを変換し、6 個のエージェントを委譲スキルに、2 個の Stop フックを post_llm_call に変換しました。モニターは手動で cron に設定するものとして記録しました。4 件のバグ（monitors.json のリスト形式、フックの入れ子構造、コールバック名の引き渡し、シェルコマンドの引用符処理）が発生しましたが、すべてスクリプトで修正しました。プラグインをロードし、通常のスキルと委譲スキルの両方で skill_view が正常に動作することを確認しました。