メインコンテンツへスキップ
スキルは、名前付きディレクトリ内の SKILL.md ファイルとして定義します。このページでは、効果的なスキルを記述するために必要な情報をすべて説明します。

ファイル構成

スコープに応じて、スキルを適切なディレクトリに配置します。
ディレクトリ名は スキル の識別子です (/my-skill の呼び出しで利用されます) 。SKILL.md ファイルには、省略可能な YAML フロントマター と、スキル のプロンプト内容が含まれます。
Windows では、%APPDATA% は通常 C:\Users\<YourUser>\AppData\Roaming に展開されます。

フロントマター リファレンス

すべてのフロントマター項目


モデルのオーバーライド

model フィールドを利用すると、現在のセッションでアクティブなモデルとは別のモデルでスキルを実行できます。単純なタスクにはより高速なモデルを、複雑なタスクにはより高性能なモデルを使い分けたい場合に便利です。
モデル名には、--model CLI フラグと同じ値 (例: opussonnetswecodex) を使用します。完全な一覧については、Modelsを参照してください。スキル の完了後、セッションはそれまでアクティブだったモデルに戻ります。

サブエージェントとしてスキルを実行する

スキルをサブエージェントとして実行する機能は実験的です。subagent フィールドと agent フィールドは、今後のリリースで変更される可能性があります。
デフォルトでは、スキルのプロンプトは現在の会話に挿入され、エージェントがインラインで処理します。代わりに、スキルをサブエージェントとして実行することもできます。これにより、独自のコンテキストウィンドウを持つ独立したワーカーが起動します。これは、出力でメインの会話を煩雑にしたくない、集中的で単独で完結するタスクを実行するスキルに便利です。 スキルをサブエージェントとして実行する方法は 2 つあります。

subagent: true

subagent: true を設定すると、デフォルトの subagent_general プロファイルを使用して、スキル をサブエージェントとして実行します。
呼び出されると、このスキルはフォアグラウンドでサブエージェントを起動し、そのスキルのプロンプトをタスクとして実行させます。親エージェントはサブエージェントが完了するまで待機し、その後、結果を読み取って要約します。

agent: <profile>

特定のカスタム サブエージェント プロファイルを指定してスキルをサブエージェントとして実行するには、agent フィールドを利用します。
agent の値は、登録済みのサブエージェントプロファイル名と一致している必要があります (subagent_explore / subagent_general などの組み込みプロファイル、またはユーザー定義のカスタムプロファイル) 。サブエージェントはそのプロファイルのシステムプロンプト、ツールの制限、モデルを継承し、スキル の内容がタスクになります。
agentsubagent の両方が設定されている場合は、agent が優先されます。両方が指定されている場合、スキル の model フィールドがサブエージェントプロファイルのモデルを上書きします。
サブエージェントとして実行される スキル では、ネストされたサブエージェントは生成されません。無限再帰を防ぐため、スキル がすでにサブエージェント内で実行されている場合は、代わりにインラインで実行されます。

スキルを利用したサブエージェントのオーケストレーション

スキルはサブエージェントとして実行できるため、複数のステップにまたがる作業のオーケストレーションに利用できます。まず、それぞれが特定のタスクを担当するサブエージェント用スキルを定義し、次にそれらを呼び出す通常のスキルを作成します。外側のスキルはオーケストレーターとなり、各サブエージェントを呼び出して結果を収集し、次に何をするかを判断します。 たとえば、以下に 2 つのサブエージェント用スキルと、それらを連携させるオーケストレーターを示します。
/health-check を呼び出すと、メインエージェントでオーケストレーターが実行されます。次に /research-changes が呼び出され、repo を調査するためのサブエージェントが起動されます。それが完了すると、/validate-tests が呼び出され、テストを実行する別のサブエージェントが起動されます。最後に、オーケストレーターが両方の結果を統合して最終サマリーを作成します。 サブエージェントのスキルは、ほかのスキルを呼び出すとき、そのスキルに subagent: true が設定されていても、決して サブエージェントを利用しません。代わりに、インラインで実行されます。つまり、ネストが際限なく深くなることを心配する必要はありません。オーケストレーションのパターンは常に 1 階層だけです。オーケストレーターがサブエージェントを起動し、それらのサブエージェントがそれ以外のすべてをインラインで実行します。

プロンプトの内容

SKILL.md ファイルの本文 (フロントマターの後の部分) は、そのスキルが呼び出されたときに挿入されるプロンプトです。

権限

スキルごとに、メインの権限設定と同じ構文で独自の権限スコープを定義できます。
スキル権限の仕組み:
  • allow — これらのスコープはスキルの実行中に自動承認されます
  • deny — これらのスコープはスキルの実行中にブロックされます
  • ask — これらのスコープでは常にuserに確認を求めます
Skill permissions はセッションの基本権限を置き換えるのではなく、その上に追加されます。スキルは、より上位のレベル (project または組織の設定) で拒否されている権限を付与することはできません。

許可するツール

スキル が利用できるツールを制限します:
使用可能なツール名: read, edit, grep, glob, exec MCP ツールも許可できます:
allowed-tools が指定されていない場合、スキルはすべてのツールにアクセスできます。安全性が重視されるスキルでは、必ず必要最小限のツールのみに制限してください。

使用例

コードレビュースキル

コンポーネントジェネレーター

デプロイチェックリスト

検索エキスパート


ヒント

プロンプトは焦点を絞る

スキルは1つのことを確実にこなせるようにしましょう。1つの巨大なスキルを作るのではなく、複数のスキルに分けて作成してください。

使用例を含める

プロンプト内で、望ましい出力の例をエージェントに示しましょう。

allowed-tools を利用する

利用できるツールを制限すると、スキルの安全性と予測しやすさが向上します。

/skill-name でテストする

スキルを呼び出して、出力が意図どおりになるまでプロンプトを調整しましょう。