スキルバンドルの作成

スキルバンドルは、WebAssemblyをまったく同梱しない唯一のプラグイン種別です。マークダウンスキルのディレクトリであり、プラグイン機構を通じてパッケージ化および配布されます。同じマニフェスト、同じ検出、同じ署名ポリシー、同じ zeroclaw plugin install です。追加する機能がコードではなく指示、プロンプト、ワークフローであり、スキルディレクトリ内のばらばらのファイルではなくプラグイン配布セマンティクス（署名、レジストリインストール、バージョニング）が必要な場合に使用します。

まずバイナリを確認してください。 スキルバンドルはプラグインの仕組みの上で動作します。64ビットのデスクトップおよびサーバー向けターゲットのリリースアーカイブにはプラグインホストが含まれています。32ビットARM向けの2つのアーカイブ、実験的なAndroid向けアーカイブ、およびCargoのデフォルト設定によるソースビルド（cargo install zeroclaw、install.sh --source）にはプラグインホストが含まれていません。これらのバイナリではzeroclaw plugin ...は認識されないサブコマンドとなり、プラグイン経由のスキルは読み込まれません。ホストを含むアーカイブでは、各リリースがいずれかのプラグインを実行します。すべてのアーカイブについては成果物ごとの対応表を参照してください。プラグインホストを含まないバイナリを使用している場合は、プラグイン実行バックエンドを有効にしてソースからビルドするか（例：cargo build --release --features plugins-wasm-cranelift）、代わりにSkillsで説明されているネイティブバンドルを使用してください。zeroclaw skills bundle add <alias>でバンドルを作成し、zeroclaw skills install <source> --bundle <alias>でそのバンドルにインストールできます。これにより、プラグイン配布の仕組みを介さずに同じスキルを利用できます。

このガイドは、crates/zeroclaw-plugins/src/host.rs（validate_skill_bundle、validate_skill_md_frontmatter）の検証パスと、crates/zeroclaw-runtime/src/skills/mod.rs のローダーに照らして確認されています。

スキルそのものが何か、およびエージェントがそれらをどう使うかについては、まず Skills を読んでください。このページではバンドルのパッケージングのみを扱います。

レイアウト

スキルのみのプラグインは wasm_path を省略し、agentskills.io 形式の skills/ ディレクトリを含みます:

my-toolkit/
  manifest.toml           # capabilities = skill only, no wasm_path
  README.md               # optional bundle-level overview
  skills/
    design-review/
      SKILL.md
      scripts/            # optional
      references/         # optional
    code-review/
      SKILL.md
    data-analysis/
      SKILL.md
      references/

検証: discovery が強制する内容

ホストは検出時とインストール時にバンドルの構造を検証し、最初の失敗でプラグイン全体を拒否します（host.rs の validate_skill_bundle）。具体的なルールは次のとおりです。

1. skills/ は存在し、ディレクトリである必要があります。
2. 少なくとも1つのサブディレクトリを含んでいる必要があります。空の skills/ は無効なマニフェストであり、空のバンドルではありません。
3. すべてのサブディレクトリには SKILL.md が含まれている必要があります。
4. すべての SKILL.md は YAML フロントマターで始まる必要があります（1行目に --- フェンスがあり、閉じる --- で終端）。そのフロントマターは空でない name と description キーを宣言する必要があります。

frontmatter チェックは意図的に検出時に実行されます。スキルが name または description を省略しているバンドルは、エージェントが会話の途中でスキルを初めて呼び出したときではなく、プラグインの読み込み時に失敗します。

有効なスキルヘッダー:

---
name: design-review
description: Structured design review workflow for architecture proposals.
---

# Design Review

...instructions...

名前空間化

読み込まれたバンドルスキルは、プラグイン修飾IDの下に登録されます: plugin:<plugin-name>/<skill-name>、例: plugin:my-toolkit/design-review（skills/mod.rs の namespace_plugin_skill）。各スキルは plugin:<plugin-name> タグも受け取ります。これにより、ユーザー作成スキルとの衝突およびバンドル間の衝突を防ぎます。2つのバンドルがどちらも code-review スキルを同梱して共存できます。

名前空間はスキルの優先順位と相互に作用します。エージェントの実効スキル解決では、異なるソース由来の同名スキルは優先順位に基づいて重複排除され、敗れた側は shadowed として記録されます。プラグイン修飾子を使えば、同じバンドル名の別のコピーが存在しない限り、あなたのバンドルはこの競合に一切巻き込まれません。

スクリプト

スキルは scripts/ ディレクトリを含む場合があります。スクリプトを含むスキルが読み込まれるかどうかは、オペレーターの skills.allow_scripts 設定によって制御され、プラグインスキルローダーはこれを変更せずに通過させます（skills/mod.rs 内の discover_plugin_skills）：スクリプトを含むバンドルスキルは、ワークスペーススキルとまったく同じ監査およびドロップのルールの対象となります。バンドルがインストールされたからといって、スクリプトが実行されると想定しないでください。

マニフェスト

マニフェストとは、プラグインディレクトリ内にある manifest.toml という名前のファイルです。そのフィールドは crates/zeroclaw-plugins/src/lib.rs 内の PluginManifest の serde サーフェスであり、これが信頼できる情報源となります。

Wait — that’s the source text itself, and I shouldn’t return it verbatim. Here is the Japanese translation:

コンポーネントのバイト列そのものに対する16進数表記のSHA-256ハッシュ。指定されている場合は常に強制されます。厳格な署名ポリシーでは、署名済みマニフェストが許可された実行ファイルに紐付けられるよう、これが必須です。| |capabilities|はい、空ではありません|プラグインの種類: tool、channel、memory、observer、skill のいずれか（PluginCapability、snake_case でシリアライズ）。| |provides|いいえ|channel プラグインで、コンパイル済みのチャネルのドロップイン代替となるもの。ミラーする snake_case の設定 ID は telegram、gmail_push です。ホストは、有効なエージェントがルーティングする、設定済みかつ有効な [channels.<id>.<alias>] ごとに論理インスタンスを1つだけ受け入れるため、正規のチャネル設定が、これらの設定の唯一の保管場所であり続けます。config_read が必要です。plugin ファミリーは予約されており拒否されます。本ビルドで定義されていない ID は拒否されます。同じ ID を主張する2つのインストール済みパッケージは、両方とも拒否されます。省略時（デフォルト）は、[channels.plugin.<alias>] から設定される新規チャネルを意味します。ミラーは受け入れられますが、まだ構築されていません。アクティベーション計画については crates/zeroclaw-runtime/src/plugin_runtime.rs を参照してください。| |permissions|いいえ|コードが到達しうるホストサービス: http_client、config_read、state_read、state_write、file_read、file_write、memory_read、memory_write（PluginPermission）。HTTP、config、および正確なインスタンス単位の state の権限は、ツール／チャネルアダプターに対して適用されます。ファイルシステムおよびメモリの権限は無効のままです。config_read を宣言するには config_schema が必要です。| |config_schema|config_read と完全に一致して|このプラグインのプライベート設定用の Draft 2020-12 JSON Schema。canonical manifest バイト列に含まれるため、マニフェストの署名時に対象となります。ルートは properties マップと additionalProperties = false を持つオブジェクトでなければなりません。すべてのトップレベルプロパティは、直接または、ローカルの JSON Pointer を介して、明示的にサポートされる型を1つ持たなければなりません: string、boolean、integer、number、array、または object。ツールおよびチャネルの利用側は、トップレベルの文字列プロパティに直接 x-secret = true を設定することができます。これにより、そのプロパティは公開設定から削除され、スコープ付きの secrets.get ホストインポートを通じて公開されます。secret プロパティ名は、1～128 バイトの移植性のある ASCII 名であり、英字、数字、_、-、. のみを含みます。ツールは公開設定を __config の下で受け取り、execute の実行中にシークレットを読み取ることができます。チャネルは configure および運用時の呼び出し中に、config.get を通じて現在の公開オブジェクトを読み取り、secrets.get を通じてシークレットを読み取ります。インスタンス化および静的メタデータ検出の間は、両方のインポートは利用できません。ネストされた、false の、または非ブール値の secret マーカー、および文字列以外の secret プロパティは拒否されます。config_read のないスキーマ、またはスキーマのない config_read は拒否されます。| |signature|いいえ|正規化されたマニフェストバイト列に対する Base64url Ed25519 署名。配布用に署名する際に設定されます。| |publisher_key|いいえ|署名者の16進数エンコードされたEd25519公開鍵。| |エグレス|いいえ|任意の [egress] テーブル。hosts リストを保持し、このプラグインが必要とする接続先を宣言します。指定できるのは完全一致のホスト（api.example.com）か、明示的なサフィックスパターン（*.example.com）で、後者はサブドメインには一致しますが apex（ドメイン自身）には一致しません。このテーブルは正規化されたマニフェストのバイト列の一部であるため、署名時に保護対象となり、変更するには再署名が必要です。不正な文法は、検出時およびインストール時にマニフェスト全体を拒否します。省略された状態、空の状態、「何も宣言しない」状態は同一として扱われます。|

コードが実際に使用する権限のみを宣言してください。宣言されていない権限はコンポーネントが到達できないホストサーフェスであり、不要に宣言された権限は自ら求めた攻撃対象領域であり、プラグインをレビューする人にとっての監査負担です。

[egress] は宣言であり、権限の付与ではありません。マニフェストによってネットワークへの到達性が与えられることはありません。ホストが適用する許可リストは、インスタンス自身の zpi1_… 行に対するオペレーターの plugins.entries[].egress_hosts であるため、独自の [egress] テーブルを書いた未署名のコンポーネントであっても、どこにも到達できません。宣言が果たす役割はインストール時の手続きです。zeroclaw plugin install はそれを、同コマンドが作成する行に設定し、何が付与されたかを表示します。既存の行を広げることは決してありません。詳しくは Declaring and granting egress を参照してください。

オペレーター値は plugins.entries 内では文字列のまま保持され、永続化時には、ホスト所有のパッケージ、ケイパビリティ、バインディングの識別情報から導出されたバージョン付きの zpi1_… 文字列をキーとして暗号化されます（インストール時に出力され、デフォルトのツールバインディングのフルインスタンスキーにシードされます）。文字列はそのまま保存され、ブール値と数値には JSON スカラーのテキストが使用され、配列とオブジェクトには JSON テキストが使用されます。ゲストコードが実行される前に、ホストはそれらの文字列をパッケージスキーマの型に実体化し、ツールアダプターとチャンネルアダプターについてオブジェクト全体を検証します。シークレットではないツールプロパティで __config が構成され、チャンネルは config.get を介してシークレットではないオブジェクトを取得します。x-secret = true とマークされたプロパティは両方の公開サーフェスから省略され、認可されたサービスフレーム内で secrets.get("property") を介してのみ利用できます。1 回の呼び出し中のチャンネルの公開読み取りとシークレット読み取りは単一の正規リビジョンを共有し、ホストは呼び出しの終了時にその実体化されたビューを破棄します。準拠するチャンネルプラグインは、利用する各時点でその両方を 必ず 解決し、ウォームなゲスト状態に設定や資格情報の値を保持してはなりません。ゲストに平文を返すと、ホストは悪意のあるコードに対して値を保持しないことを強制できなくなります。config_read が要求されたものの実効的に許可されなかった場合、ホストは空のオブジェクトを検証します。そのため、必須プロパティを持つスキーマは、必須設定なしで起動するのではなくフェイルクローズします。空のオブジェクトが有効な場合、ツールは空の __config を省略し、チャンネルの設定/シークレットインポートは access-denied を返します。認可されたフレーム外の呼び出し、解決失敗、ホスト呼び出し予算の枯渇は unavailable を返します。

スキルバンドルの場合: capabilities に正確に skill のみが含まれ、wasm_path はなく、通常は permissions もまったくない。バンドルはデータであり、パーミッションセットは markdown が決して呼び出さないホスト関数をゲートする。

混合ケイパビリティのプラグイン（たとえば tool + skill）は許可されます。その場合、ツールワールド用の有効な wasm_path and 有効な skills/ バンドルを備え、両方の検証が実行されます。

インストールと検証

これらのコマンドには、プラグインホストがコンパイルに含まれたバイナリが必要です。 64ビットのデスクトップ・サーバー向けターゲット（glibc または musl の x86_64 および aarch64 Linux、Apple silicon と Intel の macOS、x86_64 の Windows）のリリースアーカイブにはこれが含まれており、各リリースは公開前に、それぞれのアーカイブからプラグインを1つ実行します。32ビット ARM のアーカイブ2種と実験的な Android アーカイブには含まれておらず、Cargo のデフォルト設定によるソースビルド（cargo install zeroclaw、install.sh --source、または features なしの cargo build）にも含まれていません。これらの場合、zeroclaw plugin ... は認識されないサブコマンドとなり、インストール済みのプラグインは検出されません。そのような環境では、プラグイン実行バックエンドを有効にしてソースからビルドしてください（例えば cargo build --release --features plugins-wasm-cranelift）。アーティファクトごとのプラグイン対応状況は、プロトコルのページに記載されています。

各プラグインは、プラグインディレクトリ（デフォルト ~/.zeroclaw/plugins/、plugins.plugins_dir を通じて解決）の独自のサブディレクトリに配置され、マニフェストとマニフェストの wasm_path に一致する名前のコンポーネントを保持します:

~/.zeroclaw/plugins/
└── my-plugin/
    ├── manifest.toml
    └── my-plugin.wasm

ローカルディレクトリからインストール（これはマニフェストの形状を検証し、何かをコピーする前に署名ポリシーを実行します）:

zeroclaw plugin install ./my-plugin/

プラグインシステムを有効にして検出を確認する:

zeroclaw config set plugins.enabled true
zeroclaw plugin list
zeroclaw plugin info my-plugin

zeroclaw plugin list と zeroclaw plugin info は、パッケージがインストールされ、検出可能であることを確認しますが、検出は有効化を意味しません。plugins.enabled = true によってプラグインホストが有効になります。自動検出されたツールおよびスキルの機能は、plugins.auto_discover = true も設定されている場合にのみ実行時に読み込まれ、このフラグはデフォルトでは false です（フェイルクローズド）:

zeroclaw config set plugins.auto_discover true

したがって、plugins.enabled = true だけでは、[channels.plugin.<alias>] の下で宣言したチャンネルのみが有効になり、プラグインのツールやスキルは有効になりません。ツールまたはスキルのパッケージが zeroclaw plugin list に表示されていても、実行時には何も提供しないことがあります。明示的なチャンネルバインディングは自動検出ではなくオペレーターが名前を指定するものなので、auto_discover は不要です。このフラグが制御するのは、自動検出されたツールとスキルだけです。

zeroclaw plugin list にないプラグインは検出時にスキップされました: 起動ログでスキップ警告を確認してください（形式が不正なマニフェスト、wasm_path ファイルの欠落、または署名ポリシーによる拒否）。

検出後、スキルはスキルサーフェス（スキルリスト、ダッシュボード）に plugin:<your-bundle>/<skill> として名前空間付きで表示されます。エンドツーエンドで確認するために、エージェントに1つを使用するよう依頼してください。

次へ

• プラグインの配布: スキルバンドルは公開が最も簡単で、署名の仕組みは WASM プラグインと同一です。