OpenClawのスキル管理：カスタムスキルの作成と優先順位設定

場所と優先順位

OpenClawは、以下のソースからスキルを読み込みます。

Extra skill folders: skills.load.extraDirs で設定
Bundled skills: インストール時に同梱（npm パッケージまたは OpenClaw.app）
Managed/local skills: ~/.openclaw/skills
Personal agent skills: ~/.agents/skills
Project agent skills: <workspace>/.agents/skills
Workspace skills: <workspace>/skills

スキル名が重複した場合の優先順位は以下の通りです。

<workspace>/skills (最高) → <workspace>/.agents/skills → ~/.agents/skills → ~/.openclaw/skills → bundled skills → skills.load.extraDirs (最低)

エージェントごとのスキルと共有スキル

マルチエージェント構成では、各エージェントが独自の workspace を持ちます。つまり、スキルの扱いは以下のようになります。

エージェントごとのスキルは、そのエージェント専用の <workspace>/skills に配置します。
プロジェクトエージェントスキルは <workspace>/.agents/skills に配置され、通常の workspace 内の skills/ フォルダよりも先に適用されます。
パーソナルエージェントスキルは ~/.agents/skills に配置され、そのマシン上のすべての workspace で利用できます。
共有スキルは ~/.openclaw/skills (Managed/local) に配置され、同じマシン上のすべてのエージェントから参照可能です。
共有フォルダは、複数のエージェントで共通のスキルパックを使いたい場合に、skills.load.extraDirs（優先順位は最低）経由で追加することもできます。

同じ名前のスキルが複数の場所に存在する場合、通常の優先順位ルールが適用されます。workspace が最優先され、次にプロジェクト、パーソナル、Managed/local、同梱スキル、追加ディレクトリの順になります。

エージェントスキルの許可リスト

スキルの「場所」とスキルの「可視性（Visibility）」は、別々のコントロールになっています。

場所と優先順位は、同名のスキルのうちどれが優先されるかを決定します。
エージェントの許可リスト（allowlists）は、可視化されているスキルのうち、どのスキルをエージェントが実際に使用できるかを決定します。

agents.defaults.skills で共有のベースラインを設定し、必要に応じて agents.list[].skills でエージェントごとに上書きするのが良い方法です。

{
  agents: {
    defaults: {
      skills: ["github", "weather"],
    },
    list: [
      { id: "writer" }, // inherits github, weather
      { id: "docs", skills: ["docs-search"] }, // replaces defaults
      { id: "locked-down", skills: [] }, // no skills
    ],
  },
}

ルールは以下の通りです。

デフォルトですべてのスキルを制限なく使わせたい場合は、agents.defaults.skills を省略します。
agents.defaults.skills を継承させる場合は、agents.list[].skills を省略します。
スキルを一切使わせたくない場合は、agents.list[].skills: [] と設定します。
空ではない agents.list[].skills リストを指定すると、それがそのエージェントの最終的なセットになります。デフォルト設定とマージされることはありません。

OpenClawは、prompt building、スキルのスラッシュコマンドの検出、sandbox sync、およびスキルスナップショットにおいて、この有効なスキルセットを適用します。

プラグインとスキル

プラグインは、openclaw.plugin.json 内で skills ディレクトリを指定することで、独自のスキルを提供できます（パスはプラグインのルートからの相対パスです）。プラグインのスキルは、そのプラグインが有効になったときに読み込まれます。

現在、これらのディレクトリは skills.load.extraDirs と同じ低優先順位のパスにマージされます。そのため、同名の bundled、managed、agent、または workspace スキルがある場合は、それらによって上書きされます。プラグインの設定エントリにある metadata.openclaw.requires.config を使って、スキルの使用を制限することも可能です。プラグインの検出や設定については Plugins を、これらのスキルが教えるツールのインターフェースについては Tools を参照してください。

ClawHub (インストールと同期)

ClawHubはOpenClawのパブリックスキルレジストリです。https://clawhub.ai でスキルを探すことができます。スキルの検索、インストール、更新にはネイティブの openclaw skills コマンドを使用してください。スキルの公開や同期のワークフローが必要な場合は、専用の clawhub CLIを使用します。詳細なガイドはこちら：ClawHub

一般的なフロー：

ワークスペースにスキルをインストールする：
- openclaw skills install <skill-slug>
インストール済みのすべてのスキルを更新する：
- openclaw skills update --all
同期（スキャンと更新の公開）：
- clawhub sync --all

ネイティブの openclaw skills install は、アクティブなワークスペースの skills/ ディレクトリにインストールします。独立した clawhub CLIも、現在の作業ディレクトリの下にある ./skills にインストールします（または設定されたOpenClawワークスペースにフォールバックします）。OpenClawは、次回のセッションでこれを <workspace>/skills として認識します。

セキュリティに関する注意点

サードパーティのスキルは信頼できないコードとして扱ってください。有効にする前に必ずコードを読んでください。
信頼できない入力やリスクのあるツールを使用する場合は、サンドボックスでの実行をおすすめします。Sandboxing を参照してください。
ワークスペースおよび追加ディレクトリ（extra-dir）でのスキル検出は、解決された実パスが設定されたルート内に収まっているスキルルートと SKILL.md ファイルのみを受け入れます。
Gateway経由のスキル依存関係のインストール（skills.install、オンボーディング、Skills設定UI）では、インストーラーのメタデータを実行する前に、組み込みの dangerous-code scanner が実行されます。critical な問題が見つかった場合は、呼び出し側が明示的に dangerous override を設定しない限り、デフォルトでブロックされます。不審な（suspicious）問題の場合は、警告のみが表示されます。
openclaw skills install <slug> は動作が異なります。これはClawHubのスキルフォルダをワークスペースにダウンロードするだけで、上記のインストーラーメタデータのパスは使用しません。
skills.entries.*.env や skills.entries.*.apiKey は、そのエージェントのターンにおいてホストプロセスにシークレットを注入します（サンドボックス内ではありません）。プロンプトやログにシークレットが含まれないように注意してください。
より広範な脅威モデルやチェックリストについては、Security を参照してください。

フォーマット (AgentSkills + Pi互換)

SKILL.md には、少なくとも以下の内容を含める必要があります。

---
name: image-lab
description: Generate or edit images via a provider-backed image workflow
---

注意点：

レイアウトとインテントについては AgentSkills 仕様に従っています。
組み込みエージェントが使用するパーサーは、1行の frontmatter キーのみをサポートしています。
metadata は1行の JSON オブジェクトである必要があります。
インストラクション内でスキルフォルダのパスを参照するには {baseDir} を使用してください。
オプションの frontmatter キー：
- homepage — macOS の Skills UI で「Website」として表示される URL（metadata.openclaw.homepage でもサポートされます）。
- user-invocable — true|false（デフォルト：true）。true の場合、スキルはユーザーのスラッシュコマンドとして公開されます。
- disable-model-invocation — true|false（デフォルト：false）。true の場合、スキルはモデルのプロンプトから除外されます（ユーザーによる呼び出しは可能です）。
- command-dispatch — tool（オプション）。tool に設定すると、スラッシュコマンドはモデルをバイパスして直接ツールにディスパッチされます。
- command-tool — command-dispatch: tool が設定されている場合に呼び出すツール名。
- command-arg-mode — raw（デフォルト）。ツールディスパッチにおいて、生の引数文字列をツールに渡します（コアによるパースは行われません）。
  
  ツールは以下のパラメータで呼び出されます： { command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }

ゲーティング (ロード時のフィルタリング)

OpenClawは、metadata（1行の JSON）を使用してロード時にスキルをフィルタリングします。

---
name: image-lab
description: Generate or edit images via a provider-backed image workflow
metadata:
  {
    "openclaw":
      {
        "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] },
        "primaryEnv": "GEMINI_API_KEY",
      },
  }
---

metadata.openclaw のフィールド：

always: true — 常にスキルを含めます（他のゲートをスキップします）。
emoji — macOS の Skills UI で使用されるオプションの絵文字。
homepage — macOS の Skills UI で「Website」として表示されるオプションの URL。
os — プラットフォームのオプションリスト（darwin, linux, win32）。設定されている場合、スキルはそれらの OS 上でのみ有効になります。
requires.bins — リスト。各バイナリが PATH 上に存在する必要があります。
requires.anyBins — リスト。少なくとも1つのバイナリが PATH 上に存在する必要があります。
requires.env — リスト。環境変数が存在するか、設定で提供されている必要があります。
requires.config — openclaw.json のパスのリスト。すべてが truthy である必要があります。
primaryEnv — skills.entries.<name>.apiKey に関連付けられた環境変数名。
install — macOS の Skills UI で使用されるインストーラースペックのオプション配列（brew/node/go/uv/download）。

サンドボックスに関する注意：

requires.bins は、スキルロード時にホスト上でチェックされます。
エージェントがサンドボックス化されている場合、バイナリはコンテナ内にも存在する必要があります。 agents.defaults.sandbox.docker.setupCommand（またはカスタムイメージ）を使用してインストールしてください。 setupCommand はコンテナ作成後に一度だけ実行されます。パッケージのインストールには、ネットワークへの外部接続、書き込み可能なルートファイルシステム、およびサンドボックス内の root ユーザーが必要です。例：summarize スキル（skills/summarize/SKILL.md）を実行するには、サンドボックスコンテナ内に summarize CLI が必要です。

インストーラーの例：

---
name: gemini
description: Use Gemini CLI for coding assistance and Google search lookups.
metadata:
  {
    "openclaw":
      {
        "emoji": "♊️",
        "requires": { "bins": ["gemini"] },
        "install":
          [
            {
              "id": "brew",
              "kind": "brew",
              "formula": "gemini-cli",
              "bins": ["gemini"],
              "label": "Install Gemini CLI (brew)",
            },
          ],
      },
  }
---

注意点：

複数のインストーラーがリストされている場合、Gatewayは優先されるオプションを1つ選択します（利用可能な場合は brew、それ以外は node など）。
すべてのインストーラーが download の場合、OpenClaw は利用可能なアーティファクトを確認できるように各エントリをリストします。
インストーラースペックには、プラットフォームごとにオプションをフィルタリングするための os: ["darwin"|"linux"|"win32"] を含めることができます。
Node のインストールは、openclaw.json の skills.install.nodeManager に従います（デフォルト：npm、オプション：npm/pnpm/yarn/bun）。これはスキルのインストールにのみ影響します。Gateway のランタイムは引き続き Node である必要があります（WhatsApp/Telegram では Bun は推奨されません）。
Gateway によるインストーラーの選択は、Node 限定ではなく優先順位に基づいています。インストールスペックが混在している場合、OpenClaw は skills.install.preferBrew が有効で brew が存在すれば Homebrew を優先し、次に uv、設定された Node マネージャー、そして go や download などのフォールバックの順で選択します。
すべてのインストールスペックが download の場合、OpenClaw は1つの優先インストーラーに絞り込むのではなく、すべてのダウンロードオプションを表示します。
Go のインストール：go が見つからず brew が利用可能な場合、Gateway はまず Homebrew 経由で Go をインストールし、可能であれば GOBIN を Homebrew の bin に設定します。
Download インストール：url（必須）、archive（tar.gz | tar.bz2 | zip）、extract（デフォルト：アーカイブ検出時は auto）、stripComponents、targetDir（デフォルト：~/.openclaw/tools/<skillKey>）。

metadata.openclaw が存在しない場合、そのスキルは常に有効になります（設定で無効にされている場合や、バンドルされたスキルが skills.allowBundled でブロックされている場合を除きます）。

設定のオーバーライド (`~/.openclaw/openclaw.json`)

同梱されているスキルや管理下のスキルは、個別に有効・無効を切り替えたり、環境変数を設定したりできます。

{
  skills: {
    entries: {
      "image-lab": {
        enabled: true,
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string
        env: {
          GEMINI_API_KEY: "GEMINI_KEY_HERE",
        },
        config: {
          endpoint: "https://example.invalid",
          model: "nano-pro",
        },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

注意点として、スキル名にハイフンが含まれる場合は、キーを引用符で囲んでください（JSON5では引用符付きのキーが許可されています）。

もし OpenClaw の内部で標準的な画像生成や編集を行いたい場合は、同梱スキルではなく、agents.defaults.imageGenerationModel を指定したコアの image_generate ツールを使用することをおすすめします。ここでのスキル設定の例は、カスタムワークフローやサードパーティ製のワークフローを想定したものです。

ネイティブの画像解析には agents.defaults.imageModel を指定した image ツールを使用してください。ネイティブの画像生成や編集には、agents.defaults.imageGenerationModel を指定した image_generate を使用します。openai/*、google/*、fal/*、またはその他のプロバイダー固有の画像モデルを選択した場合は、そのプロバイダーの認証/API キーも忘れずに追加してください。

設定のキーは、デフォルトでスキル名と一致します。もしスキルが metadata.openclaw.skillKey を定義している場合は、skills.entries の下でそのキーを使用してください。

ルール：

enabled: false: スキルが同梱またはインストールされていても、無効化されます。
env: 変数がプロセス内ですでに設定されていない場合にのみ注入されます。
apiKey: metadata.openclaw.primaryEnv を宣言しているスキルのための便利な設定です。プレーンテキストの文字列、または SecretRef オブジェクト ({ source, provider, id }) をサポートしています。
config: スキルごとのカスタムフィールド用のオプションです。カスタムキーはここに配置してください。
allowBundled: **同梱（bundled）**スキル専用のオプションの許可リストです。これが設定されている場合、リスト内の同梱スキルのみが対象となります（管理下やワークスペースのスキルには影響しません）。

環境変数の注入（エージェント実行ごと）

エージェントの実行が開始されると、OpenClaw は以下の処理を行います。

スキルのメタデータを読み込みます。
skills.entries.<key>.env または skills.entries.<key>.apiKey を process.env に適用します。
対象となるスキルを使用してシステムプロンプトを構築します。
実行終了後、元の環境を復元します。

これはエージェントの実行スコープ内に限定されたものであり、グローバルなシェル環境を書き換えるものではありません。

同梱されている claude-cli バックエンドの場合、OpenClaw は対象となるスキルのスナップショットを一時的な Claude Code プラグインとして実体化し、--plugin-dir を使って渡します。これにより、Claude Code はネイティブのスキルリゾルバーを使用しつつ、OpenClaw 側で優先順位、エージェントごとの許可リスト、ゲーティング、そして skills.entries.* による環境変数や API キーの注入を制御できるようになります。その他の CLI バックエンドはプロンプトカタログのみを使用します。

セッションスナップショット（パフォーマンス）

OpenClaw は、セッションが開始されたときに対象となるスキルのスナップショットを作成し、同じセッション内の以降のターンでそのリストを再利用します。スキルや設定への変更は、次の新しいセッションから有効になります。

スキルウォッチャーが有効な場合や、新しい対象リモートノード（後述）が現れた場合は、セッションの途中でもスキルが更新されることがあります。これはホットリロードのようなもので、更新されたリストは次のエージェントのターンで反映されます。

そのセッションで有効なエージェントスキルの許可リストが変更された場合、OpenClaw はスナップショットを更新し、表示されるスキルが現在のエージェントの設定と常に一致するように保ちます。

リモート macOS ノード（Linux Gateway）

Gateway が Linux 上で動作していても、macOS ノードが接続されており、かつ system.run が許可されている（Exec approvals のセキュリティが deny に設定されていない）場合、OpenClaw はそのノードに必要なバイナリがあれば、macOS 専用のスキルを対象として扱うことができます。エージェントは host=node を指定した exec ツールを介して、それらのスキルを実行します。

この機能は、ノードが自身のコマンドサポートを報告することと、system.run を介したバイナリの確認（bin probe）に依存しています。もし macOS ノードが後でオフラインになったとしても、スキルは表示されたままになりますが、ノードが再接続されるまで呼び出しは失敗する可能性があります。

Skills watcher (自動更新)

OpenClawはデフォルトでスキルのフォルダを監視しており、SKILL.mdファイルが変更されるとスキルのスナップショットを自動的に更新します。この動作はskills.loadセクションで設定できます。

{
  skills: {
    load: {
      watch: true,
      watchDebounceMs: 250,
    },
  },
}

トークンへの影響 (スキルリスト)

スキルが利用可能な状態になると、OpenClawはシステムプロンプトの中に、利用可能なスキルのリストをコンパクトなXML形式で挿入します（これはpi-coding-agent内のformatSkillsForPromptによって行われます）。この際にかかるコストは、次のように計算できます。

ベースのオーバーヘッド（スキルが1つ以上ある場合のみ）: 195文字
スキル1つあたり: 97文字＋ XMLエスケープされた<name>、<description>、<location>の各値の長さ

計算式（文字数）は以下の通りです。

total = 195 + Σ (97 + len(name_escaped) + len(description_escaped) + len(location_escaped))

注意点：

XMLエスケープ処理によって、& < > " ' などの記号はエンティティ（&や<など）に変換されるため、元の文字列よりも長くなります。
トークン数はモデルのTokenizerによって変わります。OpenAIスタイルの大まかな見積もり（1トークンあたり約4文字）では、スキル1つにつき 97文字 ≒ 約24トークン に、実際の各フィールドの長さを加えたものになります。

管理されるスキルのライフサイクル

OpenClawをインストールすると（npm package または OpenClaw.app）、標準的なスキルセットが bundled skills として提供されます。

~/.openclaw/skills ディレクトリは、ローカルでの上書き（例えば、バンドルされたコピーを変更せずにスキルを固定したりパッチを適用したりする場合）に使用します。Workspace skills はユーザーが管理するスキルであり、名前が競合した場合は、バンドルされたスキルやローカルの上書き設定よりも優先されます。

設定リファレンス

設定スキーマの全容については、Skills config を参照してください。

もっと多くの Skill をお探しですか？

https://clawhub.ai をぜひご覧ください。

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。

OpenClawのスキル管理：カスタムスキルの作成と優先順位設定

場所と優先順位

エージェントごとのスキルと共有スキル

エージェントスキルの許可リスト

プラグインとスキル

ClawHub (インストールと同期)

セキュリティに関する注意点

フォーマット (AgentSkills + Pi互換)

ゲーティング (ロード時のフィルタリング)

設定のオーバーライド (~/.openclaw/openclaw.json)

環境変数の注入（エージェント実行ごと）

セッションスナップショット（パフォーマンス）

リモート macOS ノード（Linux Gateway）

Skills watcher (自動更新)

トークンへの影響 (スキルリスト)

管理されるスキルのライフサイクル

設定リファレンス

もっと多くの Skill をお探しですか？

関連情報

まだ解決しませんか？

設定のオーバーライド (`~/.openclaw/openclaw.json`)