Diagrid Catalyst

catalyst-ai

プロンプトを使って Diagrid Catalyst を構築・運用します。Dapr Workflows、Durable Agents、実行中のシステムに対応します。

Claude Code でエンドツーエンドの動作を検証済み — 5 秒以内にインストールでき、すべてのスキルが登録され、実際の Catalyst に関する質問で適切なスキルが実行され、根拠に基づいた回答が得られます。 Codex と GitHub Copilot では、インストールとすべてのスキルを検証済みで、Codex がそれらをモデルに渡すことも確認しています。ただし、ここではどちらも Catalyst に関する質問への回答はまだ確認できていません。その理由は クライアントごとの検証済み事項と未検証事項に記載のとおり、スキルとは無関係です。

早期リリースです。 スキルはリモートの Catalyst MCP サーバーを通じて Catalyst を操作します。サーバーを追加して、1 回サインインしてください。例外はアプリトンネルです。これを使うと Catalyst からマシン上のプロセスを呼び出せます。この機能を開く MCP ツールはないため、catalyst-app-tunnels は Diagrid CLI をインストールし、この機能だけに使用します。MCP で現在利用できる機能と利用できない機能については、現在利用できる機能をご覧ください。

インストール

Claude Code

claude plugin marketplace add diagridio/catalyst-ai
claude plugin install catalyst-ai@diagrid

インストールされたことを確認してください — 2 つのコマンドを両方実行してください。2 つ目だけでは不十分です：

claude plugin list                           # expect Version: 0.7.0 or later
claude plugin details catalyst-ai@diagrid    # expect 12 skills

list は、実際にインストールされているバージョンを表示します。details はマーケットプレイスで提供されているバージョンを表示し、両者が一致する場合にのみインストール済みのコピーを読み込みます。そのため、単独で実行すると、セッションで読み込まれるのは 11 個でも、12 個のスキルが表示されることがあります。どちらかの結果がおかしい場合は、インストール済みバージョンが古い場合をご覧ください。

Catalyst MCP サーバーにサインインする

このプラグインは Catalyst MCP サーバー https://mcp.cloud.r1.diagrid.io/mcp も登録します。1 回サインインするまでは利用できません。Claude Code で /mcp を実行し、plugin:catalyst-ai:catalyst を選択して、ブラウザーでサインインを完了してください。API キーは不要です。

すでに claude mcp add でサーバーを自分で追加している場合は、プラグインをインストールした後に、そのエントリを削除してください（claude mcp remove catalyst --scope user）。削除しないと、すべての Catalyst ツールが 2 つずつ表示されます。

このプラグインは catalyst:read catalyst:write offline_access スコープを要求します。offline_access がないとリフレッシュトークンが発行されないため、セッションの有効期限が切れるたびに再度サインインする必要があります。ロールが読み取り専用の場合、またはサインイン時に書き込みスコープが許可されなかった場合、catalyst_apply などの書き込みツールはツールリストに一切表示されません。表示されない場合は、もう一度サインインして書き込みアクセスを許可してください。それでも表示されない場合は、ロールが読み取り専用です。

「Catalyst での自分のユーザー情報は？」と質問して、動作を確認してください。回答は catalyst_whoami から取得されます。

他のクライアントをリモート MCP サーバーに接続する

すべてのクライアントは同じリモートサーバー https://mcp.cloud.r1.diagrid.io/mcp に接続します（r1 は必須です）。ブラウザーで OAuth 認証を行います。認可サーバーは動的な登録に対応していないため、各クライアントは登録済みのクライアント ID codex、copilot-cli、vscode、または claude-code を使用します。まずクライアント用のスキルをインストールし（以下を参照）、その後、次の手順を実行してください。

Codex

codex mcp add catalyst --url https://mcp.cloud.r1.diagrid.io/mcp --oauth-client-id codex
codex mcp login catalyst

GitHub Copilot CLI

copilot mcp add にはクライアント ID を指定するフラグがないため、サーバーを追加した後、~/.copilot/mcp-config.json で oauthClientId を設定してください。

{
  "mcpServers": {
    "catalyst": {
      "type": "http",
      "url": "https://mcp.cloud.r1.diagrid.io/mcp",
      "oauthClientId": "copilot-cli",
      "tools": ["*"]
    }
  }
}

次に Copilot 内で /mcp を実行し、ブラウザーで catalyst サーバーを認証してください。

VS Code（Copilot Chat）の場合は、.vscode/mcp.json またはユーザーの MCP 設定に追加してください。

{
  "servers": {
    "catalyst": {
      "type": "http",
      "url": "https://mcp.cloud.r1.diagrid.io/mcp",
      "oauth": { "clientId": "vscode" }
    }
  }
}

VS Code は初回接続時に認可用のブラウザーを開きます。VS Code MCP 設定リファレンスをご覧ください。

その他のクライアント（Gemini CLI、Zed、Antigravity など）：URL をリモート（ストリーミング可能な HTTP）MCP サーバーとして、そのクライアント独自の MCP 設定に追加し、クライアントの MCP サインインを使用してください。

このサーバーは公式 MCP レジストリにも io.diagrid/catalyst として登録されています（レジストリを検索）。レジストリ連携のサーバーギャラリーを備えたクライアントからは、そこで見つけることができます。

GitHub Copilot（および Gemini CLI、Zed、Antigravity）

npx -y skills add diagridio/catalyst-ai --agent github-copilot --skill '*' --yes

複数指定する場合は、--agent フラグを繰り返し使用してください。カンマ区切りの形式 （-a codex,github-copilot）は上流の README に記載されていますが、Invalid agents: と表示され、 何もインストールされず、終了コード 1 で終了します。つまり、正しく失敗し、終了コードを 確認するステップで検出できます。1.5.22 および 1.5.23 で再計測しました。この行の以前のバージョンでは 終了コード 0 と記載していましたが、計測ミスでした。

実際に気づかれずに失敗するのは、プロンプトに応答できるものがない場合に -y を指定し忘れることです。 これはすべての CI ランナーに当てはまります。Done! と表示され、スキルは 0 件インストールされず、 終了コード 0 で終了します。-y を渡し、終了コードではなくスキル数を検証してください。

これにより 12 個すべてのスキルが .agents/skills/ に書き込まれ、Copilot 自身の一覧表示でも 読み込まれていることを確認できます。

copilot skill list        # all 12 under "Project skills"

Copilot はプロジェクトのスキルを .github/skills/、.agents/skills/、.claude/skills/ から探すため、 ディレクトリは 1 つで十分です。この確認に npx skills list を使わないでください。 その「Agents:」の行には、お使いのマシンにインストール済みと検出されたエージェントだけが表示されるため、 まだインストールしていないクライアントは気づかれないまま除外されます。

Codex

npx -y skills add diagridio/catalyst-ai --agent codex --skill '*' --yes

.agents/skills/ は Codex のプロジェクトスキル用ディレクトリでもあります。インストーラーは 設計どおり codex をそこに割り当てるため、.codex/ が作成されないのはインストール失敗ではなく、 正しい動作です。Codex はスキルを読み込みます。codex debug prompt-input でモデルに表示されるプロンプトを レンダリングでき、スキルはすべて、説明も 1 バイトも変わることなく <skills_instructions> ブロックに 表示されます。Codex 自身のガイダンスには、スキルの自動選択がデフォルトで許可されていると書かれているため、 スキル名を指定する必要はないはずです。ただし、実際のセッションで確認した人はまだいません。

クライアントごとの検証状況

	スキルのインストール	スキルの登録	質問への回答
Claude Code 2.1.241	✅ 4.7 秒	✅ 10/10	✅ 指示しなくても適切なスキルが起動し、根拠に基づいて回答
Codex 0.149.0	✅ 2.0 秒	✅ 10/10、モデルに表示されるプロンプト内	まだ未検証
GitHub Copilot 1.0.80	✅ 2.0 秒	✅ 10/10	まだ未検証

最初の 10 個のスキルを使って計測しました。catalyst-app-tunnels と catalyst-agent-harness は、これらのクライアントではまだ再計測していません。

Codex または Copilot に Catalyst に関する質問へ回答させることができたら、その報告が何よりも 役に立ちます。入力した文面と、起動したスキルも添えてください。スキルが一度も起動しない場合は、 関連する内容が会話に出てこなかったセッションと見分けがつきません。そのため、これはインストーラーの 終了コードではなく、人による確認が必要です。

あとは質問するだけ

Catalyst を初めて使う方は、Claude Code で次のいずれかを入力すると、クラッシュからの復旧までを 一通り確認できます。どれも 1 行なので、貼り付ける必要はありません。

• /catalyst-ai:try-workflow：永続ワークフローが実行途中でクラッシュし、中断したところから再開します。
• /catalyst-ai:try-agent：永続 AI エージェントでも同じ動作を確認します（LangGraph、API キー不要）。

ほかのクライアントでは、commands/ にある対応するプロンプトを貼り付けてください。 内容は同じです。

その後、コマンドを覚える必要はありません。たとえば、次のように試してみてください。

Diagrid Catalyst をセットアップして、プロジェクトの内容を見せてください。

または

このリポジトリに、カードへの請求と部屋の予約を行い、予約に失敗した場合は補償処理をするワークフローを追加してください。

または

ワークフローの実行に失敗しました。原因は何ですか？

スキルは質問の内容に応じて自動で起動します。スキル名を指定する必要はないはずです。指定しなければならない場合は、 報告する価値のあるバグです（フィードバックを参照）。

含まれる内容

スキル	用途
catalyst-setup	このセッションを Catalyst に接続し、動作することを確認します
catalyst-workflow-scaffold	Dapr Workflow を追加します — オーケストレーター、アクティビティ、プロジェクトの設定
catalyst-workflow-from-diagram	フローチャート、シーケンス図、BPMN ファイル、ホワイトボードの写真をワークフローに変換します
catalyst-agent-scaffold	Catalyst エージェントを前面に配置し、独自アプリとして Durable Agent を立ち上げます
catalyst-agent-harness	独自のエージェントループを耐障害性のあるものにします — モデル呼び出しとツール呼び出しをそれぞれ独立したアクティビティにします
catalyst-develop	稼働中の Catalyst インフラストラクチャを使った、編集 → 再実行 → 観察のループ
catalyst-app-tunnels	Catalyst からマシン上のプロセスを呼び出せるようにします：アプリ間の呼び出し、pub/sub 配信、ローカルで実行する MCP サーバーを呼び出すエージェント
catalyst-deploy	アプリケーションをノート PC から Catalyst に移行します
catalyst-operate	実行中のプロジェクトを読み取り専用で調べます
catalyst-debug	動作しない原因を診断します
catalyst-workflow-determinism	オーケストレーター本体のリプレイ安全性を確保するためのガードレール
catalyst-activity-idempotency	アクティビティを二度実行しても安全な状態にします

言語とフレームワークは質問するのではなく、自動検出します。catalyst-workflow-python スキルはありません。ワークフロースキルがリポジトリを読み取り、Python プロジェクトであることを判別します。

コスト： 12 個すべてで、常時およそ 1240 トークン（最初の 10 個からの推定で各約 103 トークン）が追加され、スキルが起動するかどうかにかかわらず、すべての セッションで発生します。各スキルは実際に起動した場合にのみ、さらに数千トークンを消費します。この数値はモデルごとのものです。claude plugin details はアクティブなモデルからトークナイザーを特定するため、同じ 10 個の説明でも Sonnet 5 と Opus 5 ではそれぞれ約 103 トークン、Haiku 4.5 では約 68 トークンになります。再現可能な数値にするには、モデル名も併記してください。

現在動作する機能

差が重要であり、実際に気づく点なので、明確に記載します。

	ステータス
作成 — ワークフロー、エージェント	✅ 現在動作します
運用 — 調査、デバッグ、実行履歴の閲覧	✅ MCP サーバー経由で現在動作します
決定性と冪等性のレビュー	✅ 現在動作します
リソースの作成、変更、削除、デプロイ	✅ 書き込み可能なロールであれば、catalyst_apply と catalyst_delete_resource を利用できます
ワークフロー実行の操作とアクセス制御	✅ 書き込み可能なロールであれば利用できます
アプリ、エージェント、MCP サーバーをローカルで実行し、Catalyst を呼び出す	✅ catalyst_get_connection 経由で現在動作します
マシン上のプロセス（呼び出し先、サブスクライバー、エージェントエンドポイント、MCPServer の背後にある MCP サーバー）を Catalyst から呼び出し、受信リクエストを出力する	✅ アプリトンネル経由で利用できます。Diagrid CLI を使う唯一の手順です（catalyst-app-tunnels）
Catalyst のワークフローパス（dapr.internal.mcp.* の子ワークフロー）を通じて、マシン上の MCP サーバーをエージェントが呼び出す	⛔ ワークフローパスはまだトンネル経由の MCP サーバーに到達できません。スキルはエージェントを Catalyst の HTTP MCP エンドポイントに誘導します。こちらは動作します
ログ	⚠️ catalyst_get_logs はデータ共有レベルが full の場合に限り、サイドカーの API 呼び出しのみを対象とします
アプリの呼び出し、パブリッシュ、ステートの読み取りや書き込み、クラスターの診断	⛔ まだ MCP 経由では利用できません

MCP 経由ではまだ利用できない機能について、スキルは代替手段を即興で提示せず、その旨を 1 行で伝えます。書き込みツールが見つからない場合は、接続の問題ではなく、ロールが読み取り専用です。

スキルにすでに含まれている、見落としやすい重要事項

これらはすでにスキルに含まれていますが、何時間も無駄にする原因になり、しかもすべて気づきにくい形で失敗するか、役に立たないエラーを返すため、ここに挙げています。

• プロジェクトを作成しないでください。 組織にはすでに、サインアップ時にプロビジョニングされたdefaultプロジェクトがあり、マネージド pub/sub、KV、ワークフローストア、エージェントのインフラストラクチャが備わっています。バッチにProjectマニフェストを含めると、指定したプロジェクトが作成されます。プロジェクト数はリージョンごとの上限にカウントされ、その上限はcatalyst_get_usageで確認できます。
• プランにかかわらず、プロジェクトごとにpub/subは1つ、KVストアは1つです。 無料プランでも有料プランでも同じで、プランをアップグレードしても2つ目は使えません。マルチエージェントのトポロジでは、複数のトピックで1つのpub/subを共有します。これらの値はコード内の定数ではなく、組織ごとに適用されるプラン値なので、スキルは上限が1だと断定せず、実際のクォータを読み取ります。
• Agentはあなたのアプリの前面に立つものです。 受け取るのはエンドポイントとアーカイブ設定であり、モデル設定ではありません。LLMの設定を探しているなら、対象のリソースを間違えています。
• アプリが存在する前に、マネージドワークフローストアを有効にしてください。 サイドカーは起動時にワークフローの設定を読み取るため、後から有効にすると、後付けで対応されないサイドカーにFAILED_PRECONDITIONが残ります。
• 同じ名前のほかのものを作成する前に、AgentまたはMCPサーバーを作成してください。 自身が所有していないIDを引き継ぐことはできず、その後はエラー状態のままになります。
• IDはリージョンごとに組織全体でカウントされます。 アプリ、エージェント、MCPサーバーごとに1つずつ、すべて同じ枠を使います。そのため、トポロジを複数のプロジェクトに分割しても枠は増えません。
• 存在しないことと空であることは異なります。 デフォルトのmetadataデータ共有レベルでは、ワークフローのinput、output、customStatusは空なのではなく、非公開になります。出力が表示されない実行でも、実際には大量の出力が生成されている場合があります。
• 接続値はローカル開発専用です。 デプロイ済みのアプリには、プラットフォームから独自の値が割り当てられます。起動コマンドに直接指定するか、アプリのフォルダー内にあるGit管理対象外の.envに記述するか、ツールの環境変数オプションを使用してください。チャット、プルリクエスト、コミットには絶対に含めないでください。
• アプリのトンネルを開く場合を除き、Catalystに関するすべての操作で、スキルはCatalyst MCPツールを使用します。 アプリのトンネルには、パブリックトンネル（cloudflared、ngrok）を絶対に使用しないでください。App IDのID・アクセスポリシーを迂回してしまいます。

インストールが古い場合

ここで起きる問題は2種類あり、それぞれ対処法が異なります。まずclaude plugin listを実行してください。実際にインストールされているものを確認できるコマンドです。

バージョンがmainより古い。 マーケットプレイスは、最後に取得したコミットに固定されたGitクローンなので、先週インストールしたものは先週のバージョンのままで、スキルも更新されません。claude plugin installを実行しても更新されません。「すでにインストール済み」と表示され、何も変更されません。

claude plugin marketplace update diagrid
claude plugin update catalyst-ai@diagrid     # the command that actually upgrades
claude plugin list                           # expect Version: 0.7.0 or later

バージョンは正しいが、スキルが不足している。 Claude Codeは、宣言されたバージョンに基づいてプラグインを~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/にキャッシュし、すでに存在するバージョンのディレクトリは更新しません。実測では、部分的にしか内容がないバージョンディレクトリから10個中4個のスキルが提供されていましたが、marketplace updateもplugin installも成功と表示するだけで、修復は行いませんでした。ディレクトリを削除するのが唯一の対処法です。

rm -rf ~/.claude/plugins/cache/diagrid/catalyst-ai
claude plugin install catalyst-ai@diagrid
claude plugin details catalyst-ai@diagrid    # expect 12 skills

現在、プラグインのバージョンを上げずにコンテンツを変更するとCIで失敗するため、2つ目の問題は再発しないはずです。

フィードバック

最も役立つ報告は、使われるべきときに使われなかったスキルと、実際に使った正確な表現です。この失敗は私たちの側からは見えません。関連する処理が何も起きなかったセッションとまったく同じように見えるためです。そして、原因を突き止めるには、その表現が欠かせません。

価値の高い順に、次の内容もぜひご報告ください。

1. スキルが指定したものの、存在しなかった、または機能しなかったツール。すべての catalyst_* 名は、CI で contracts/catalyst-mcp-tools.txt と照合されます。不一致があれば、サーバーが変更されたか、チェックに抜け穴があることを意味します。どちらも見つける価値があります。
2. 別のスキルを使うべきときに使われたスキル。
3. スキルから伝えられた内容に、誤りがあった場合。

このリポジトリに Issue を作成してください。

セキュリティ上の問題については、Issue を作成しないでください。SECURITY.md をご覧ください。

コントリビューション

すべての PR でゲートが実行され、それぞれに専用のテストスイートがあります。どのゲートも、実際にレビューや claude plugin validate --strict をすり抜けた問題を防ぐために存在します。

python3 scripts/lint_skills.py            # the real gate
python3 scripts/test_lint_skills.py       # proves the gate still catches what it claims
python3 scripts/check_mcp_surface.py      # tools, CLI and hosts, across skills, evals and README
python3 scripts/test_check_mcp_surface.py
python3 scripts/check_version_bump.py     # a plugin change must bump the version
python3 scripts/test_check_version_bump.py
python3 scripts/check_server_json.py      # server.json: registry name, and the same URL as the plugin
python3 scripts/test_check_server_json.py
python3 scripts/test_plan_registry_version.py   # the MCP Registry version planner
python3 scripts/build_install_data.py --check   # web/install/ data matches commands/ and this README
(cd web/install && npm test)

web/install/ は npm パッケージ @diagrid/catalyst-ai-install で、ドキュメントとウェブサイト向けの <catalyst-ai-install> ウェブコンポーネントです。このデータは生成されます。commands/ またはここにあるインストール手順を変更した後は、python3 scripts/build_install_data.py を実行し、生成結果をコミットしてください。

lint_skills.py は、クライアントが実際に必要とする要件を検証します。ディレクトリ名と一致する name、解析可能で260文字未満の説明、frontmatter の許可リスト、../ リンクがないこと、スキルが単独でインストールされた場合にすべてのリンクが解決すること、そして同じトリガーを奪い合わないよう、任意の2つの説明間の類似度が0.20以下であることです。また、それぞれ過去にどこかで使われ、問題を引き起こした部分文字列のリストも禁止します。

check_mcp_surface.py は、スキル、評価テスト、およびこの README をリモート MCP の提供範囲と照合します。すべての catalyst_* 名は contracts/catalyst-mcp-tools.txt に含まれている必要があります。このファイルはサーバーの tools/list の返却内容を複製したものなので、サーバーのツール一覧が変わったら更新してください。このゲートは、Diagrid CLI の呼び出しがあれば失敗します。ただし、skills/catalyst-app-tunnels/ と evals/tunnel-*/ 内のトンネルコマンド（インストール確認、サインイン、および2つのトンネルコマンド）は除きます。また、リモートサーバー以外を指すもの、さらに許可リストにない Diagrid ドメイン配下のホスト（MCP サーバー、コンソール、ドキュメントとダウンロード用のホスト、およびメインサイト）も対象です。 ツール名は大文字と小文字を区別せずに照合されます。スキルは Catalyst をリモート MCP サーバー経由でのみ操作するため、対応するツールがない機能については、別の手段を使うのではなく、まだ MCP 経由では利用できないと説明します。

スキルを追加する場合、またはいずれかのスキルの内容を変更する場合は、.claude-plugin/plugin.json の version を更新してください。そうしないと、すでにインストール済みのユーザーには古い内容が残り、更新を知らせるものもありません。

ライセンス

Apache-2.0 です。LICENSE をご覧ください。