finestructure-ai/claude-plugin の内側: 七つのファイルでできた Claude Code プラグイン

リポジトリ全体が七つのファイル

クローンすると、ファイルツリーは一画面に収まります。

.claude-plugin/
  plugin.json        686 B
  marketplace.json   507 B
commands/
  deploy.md          3.3 KB
  fs-domain.md       905 B
  fs-status.md       741 B
skills/
  fine-structure/
    SKILL.md         4.0 KB
LICENSE              MIT
README.md            2.3 KB

package.json もロックファイルも CI も dist もありません。コンパイルもバンドルも行われず、ビルドに失敗しうるバージョンがそもそも存在しません。ツールチェーンが必要だと思い込んでプラグインの作成を先延ばしにしていたのなら、ここが訂正点です。この形式はディレクトリの取り決めと二つの JSON ファイルであり、残りは散文です。

plugin.json はプログラムではなくポインタ

マニフェストには通常の識別用フィールド (name、バージョン 0.1.0、description、author、homepage、repository、license、keywords) が並び、その後に興味深い仕事をすべて引き受けるブロックが一つだけ置かれています。

"mcpServers": {
  "finestructure": {
    "type": "http",
    "url": "https://finestructure.ai/api/mcp"
  }
}

キーは二つだけです。command も args も env もありません。多くの MCP 設定が取る形と比べてみてください。ローカルプロセス (npx、uvx、実行ファイルへのパス)、引数の並び、そして API キーを収めた env マップという構成です。代わりに streamable HTTP のエンドポイントを宣言すると、サーバーは利用者のマシンから外へ出ます。だからこそ 105 個のツール (skill ファイルが挙げている数) が 686 バイトのマニフェストの背後に収まります。利用者の Node や Python のバージョンがインストールを壊すことはなく、サーバー側の変更はプラグインのリリースなしに反映されます。引き換えになるのは再現性で、ツールの面をクライアント側から固定することはできません。

marketplace.json がリポジトリを自前の配布経路にする

Claude Code はパッケージレジストリではなく marketplace からプラグインを導入します。marketplace とは、プラグインとそのソースパスを列挙した JSON ファイルです。.claude-plugin にある二つ目のファイルがまさにそれで、唯一のプラグイン項目には "source": "./" と書かれています。リポジトリはプラグインであると同時にそれを配る marketplace でもあるため、公開とは公開リポジトリへの git push そのものです。

/plugin marketplace add finestructure-ai/claude-plugin
/plugin install finestructure@finestructure

二行目に同じ語が二度出てくるのは、marketplace 名のもとにあるプラグイン名という並びだからで、どちらも finestructure という名前なので重なって見えます。この構成を写すのであれば、別々の名前を付けてください。インストール手順が読みやすくなり、後から二つ目のプラグインを足す余地も残ります。

コマンドは frontmatter 付きのプロンプトのひな形

commands/ の各ファイルは YAML の frontmatter と散文でできています。deploy.md は description と argument-hint を宣言します。これは選択画面に表示される二つの文字列です。続いて番号付きの判断手順を並べます。まずプロジェクト直下に app_id を持つ .finestructure.json があるか確認し、なければ list_apps を呼んで名前の一致を探し、それでもなければ初回デプロイとみなして $ARGUMENTS をアプリ名として使う、という流れです。fs-status.md は 741 バイトで、CLI のサブコマンド相当の仕事をします。対象アプリを特定し、get_app_status、get_app_links、get_errors を呼び、要約します。fs-domain.md は add_custom_domain、get_domain_verification、check_domain_verification、get_domain_ssl_status、set_primary_domain の順に進みます。

設計上の要点として、これらのファイルは何も呼び出しません。ツールの名前を挙げ、順序を定め、ある手順が失敗したときの対処を述べるだけです。実行はモデルが MCP ツールを呼んだ時点で起こります。スラッシュコマンドはバージョン管理下に置かれたプロンプトなので、そのレビューは論理が正しいかを問う作業ではなく、指示があいまいでないかを問う作業になります。

最も出来のよい行は禁止を述べた行です。deploy.md は、利用者が明示的に求めない限り削除系ツールを禁じます。fs-domain.md は DNS の伝播に数分から数時間かかると記し、検証を繰り返す代わりに後で再試行するよう促せと指示します。これは文章として書かれた再試行方針とガードレールであり、素朴なプラグインが省いてしまう部分です。

skill と command: 引くか押すか

skills/fine-structure/SKILL.md の frontmatter は name と description の二つだけで、その description は要約ではなく起動条件として読めます。利用者がアプリをデプロイ、作成、更新したいとき、ドメインをつなぎたいとき、データやシークレットを扱いたいときに使う、という書き方です。この言い回しは意図的なものです。コマンドは人が打ち込んだから動きます。skill はモデルが説明文と目の前の状況を突き合わせたから動きます。

内容の切り分けもここから導かれます。SKILL.md は作業一覧ではなく考え方の地図です。ここでのアプリとは何か (JSX のページ、共有コンポーネント、エンティティのスキーマ、任意のサーバーコードは書けないこと)、エンティティとは何か、どの操作がクレジットを消費するかを述べます。次に作業手順をツールの連なりとして示し、get_app_files から read_app_file、write_app_file、validate_app、publish_app へと進み、複数ファイルの編集には変更セットを使います。そしてエラーの意味づけが続きます。ここが一バイトあたりの重みが最も大きい部分です。認証エラーは再接続を意味し、クレジットのエラーは残高の補充を意味し、どちらも再試行の対象ではありません。この知識を持たないエージェントは再試行しても無駄な失敗を繰り返し、従量課金の基盤ではその繰り返しに費用が発生します。

自作プラグインへの指針もきれいに出てきます。コマンドのファイルが自社製品の説明をしているなら、その段落は skill に置くべきものです。コマンドは手順のままにしておきます。

マニフェストに秘密情報がないのは OAuth のおかげ

エンドポイントは OAuth 2.1 と動的クライアント登録で認証するため、最初のツール呼び出しでブラウザに同意画面が開き、トークンはリポジトリではなく Claude Code の資格情報ストアに保存されます。フォークは構造上安全で、失効はサーバー側で行われるので、全端末に届けなければならない設定変更にはなりません。長期間有効な鍵を、うっかり一度コミットすれば公開差分に載ってしまうファイルへ貼り付けるよう求められることもありません。

自作プラグインに取り入れたい点

具体的な指針を、おおむね作業順に挙げます。

• まず name、version、description を持つ .claude-plugin/plugin.json から始めてください。それ以外はすべて任意です。
• ホスト型の MCP エンドポイントを運用しているなら、ローカルコマンドではなく url を添えて "type": "http" と宣言してください。利用者の実行環境をサポート範囲から外せます。
• プラグインが一つのうちは、marketplace.json を同じリポジトリに "source": "./" 付きで置き、プラグインとは別の名前を付けてください。
• どのコマンドにも frontmatter の description と argument-hint を用意し、これは何をするのか、後に何を打つのかという二つの問いへの答えとして書いてください。
• 位置指定の独自構文を考案せず、$ARGUMENTS を使ってください。パーサーはなく、あるのは置換だけです。
• コマンド本文は判断手順として書き、ツール名を明示してください。「設定ファイルがあれば app_id を読み、なければ list_apps を呼ぶ」の方が、意図を述べた段落より長持ちします。
• 失敗の意味づけを文章に残してください。どのエラーが打ち切りで、どれが再試行可能で、再試行の代わりに何を伝えるのかを書きます。
• 破壊的なツールは本文で名指しし、求められない限り使用を禁じてください。
• ドメインの考え方は SKILL.md に、手順はコマンドに置いてください。両者の重複はよくない兆候です。
• 誰かを main に案内する前に、ローカルのパスか自分のフォークに対して /plugin marketplace add で試しておいてください。

粗い部分

正直なところ三点あり、いずれも致命的ではありません。すべて英語で書かれており、形式の側にそれを直す取っ掛かりがありません。frontmatter に locale のキーがないため、地域化はコマンドファイルの複製か、言語の不一致を受け入れるかの二択になります。

API キーが不要という話には注釈が付きます。SKILL.md は、メディア生成系のツールが OAuth の接続の外にあり、メディア権限を持つ静的な MCP トークンを必要とすると認めています。このトークンは基盤の Studio で作成し、bearer ヘッダーで送ります。プラグインの扱いは適切で、壁に向かって再試行するのではなく機能がない理由を説明せよとモデルに指示していますが、経路が一つで済むことを売りにした設計に、二つ目の認証経路が後付けされている形です。

そしてバージョンは 0.1.0 で、changelog もテストも CI もありません。markdown であればそれは擁護できますが、pre-commit の hook に JSON スキーマ検査を入れれば、インストールを実際に壊す唯一の種類の誤り、つまり壊れたマニフェストを捕まえられます。ディレクトリへの登録申請は執筆時点で審査中のため、当面はリポジトリ参照での導入になります。

まず三つのコマンドファイルを読み、次に SKILL.md、最後に二つの JSON ファイルを読んでください。この順番なら形式が自分で自分を説明します。markdown は何をどの順で行うかを決め、MCP サーバーは実際に何が動くかを決め、マニフェストはその間にある薄い継ぎ目です。