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

ファイル構成

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

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

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


モデルのオーバーライド

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

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

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

subagent: true

subagent: true を設定すると、デフォルトの subagent_general プロファイルを使用して、スキル をサブエージェントとして実行します。
呼び出されると、このスキルはフォアグラウンドでサブエージェントを起動し、そのスキルのプロンプトをタスクとして実行させます。親エージェントはサブエージェントが完了するまで待機し、その後、結果を読み取って要約します。
スキルをサブエージェントとして実行する場合、その allowed-tools および permissions のフロントマターは適用されません。サブエージェントは自身のプロファイルのツールセットで実行され、subagent_general はすべてのツールにアクセスできます。サブエージェントのスキルが利用できるツールを制限するには、allowed-tools を指定したカスタムサブエージェントプロファイルを定義し、subagent: true の代わりに agent: で参照してください。

agent: <profile>

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

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

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

プロンプトの内容

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

権限

スキルごとに、メインの権限設定と同じ構文で独自の権限スコープを定義できます。
スキル権限の仕組み:
  • allow — これらのスコープはスキルの実行中に自動承認されます
  • deny — これらのスコープはスキルの実行中にブロックされます
  • ask — これらのスコープでは常にuserに確認を求めます
deny は、インラインのスキルに対してツールを完全にブロックする手段です。exec や edit のようなツール名のエントリはそのツール全体をブロックし、mcp__server__tool のパターンは MCP ツール をブロックします — Tool-Based Permissions を参照してください。
Skill permissions はセッションの基本権限を置き換えるのではなく、その上に追加されます。スキルは、より上位のレベル (project または組織の設定) で拒否されている権限を付与することはできません。
Skill permissions は、スキルがインラインで実行される場合にのみ適用されます。スキルがサブエージェントとして実行される場合 (subagent: true または agent:) には適用されません。

自動承認されるツール

allowed-tools には、スキルの実行中に自動承認されるツールを列挙します。これにより、エージェントは権限プロンプトなしでそれらのツールを利用できます。
各項目は、そのツール名に対する permissions.allow の項目と同等です。使用できるツール名: read、edit、grep、glob、exec MCP ツールを自動承認することもできます:
allowed-tools は制限ではありません。記載されていないツールもスキルから引き続き利用でき、通常の権限チェック (ユーザーへの確認、またはセッションの権限ですでに許可されている場合は確認なしでの実行) を経ます。allowed-tools を省略しても、スキルが利用できるツールの範囲は変わりません。事前承認されるツールがなくなるだけです。スキルによるツールの利用を実際に禁止するには:
  • インラインスキルの場合は、ツール名を permissions.deny に追加します (権限を参照) 。
  • サブエージェントスキルの場合は、allowed-tools を指定したカスタムサブエージェントプロファイルを定義し、agent: <profile> を指定してスキルを実行します。サブエージェントプロファイルでは allowed-tools がツールセットを制限しますが、スキルでは制限しません。

使用例

コードレビュースキル

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

デプロイチェックリスト

検索エキスパート


ヒント

プロンプトは焦点を絞る

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

使用例を含める

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

スキルに禁止したい操作は deny する

ツールをブロックするには permissions.deny (またはカスタムサブエージェントプロファイル) を利用してください。allowed-tools は確認プロンプトを省略するだけです。

/skill-name でテストする

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