SKILL.md ファイルとして定義します。このページでは、効果的なスキルを記述するために必要な情報をすべて説明します。
ファイル構成
スコープに応じて、スキルを適切なディレクトリに配置します。/my-skill の呼び出しで利用されます) 。SKILL.md ファイルには、省略可能な YAML フロントマター と、スキル のプロンプト内容が含まれます。
Windows では、
%APPDATA% は通常 C:\Users\<YourUser>\AppData\Roaming に展開されます。フロントマター リファレンス
すべてのフロントマター項目
モデルのオーバーライド
model フィールドを利用すると、現在のセッションでアクティブなモデルとは別のモデルでスキルを実行できます。単純なタスクにはより高速なモデルを、複雑なタスクにはより高性能なモデルを使い分けたい場合に便利です。
--model CLI フラグと同じ値 (例: opus、sonnet、swe、codex) を使用します。完全な一覧については、Modelsを参照してください。
サブエージェントとしてスキルを実行する
デフォルトでは、スキルのプロンプトは現在の会話に挿入され、エージェントがインラインで処理します。代わりに、スキルをサブエージェントとして実行することもできます。これにより、独自のコンテキストウィンドウを持つ独立したワーカーが起動します。これは、出力でメインの会話を煩雑にしたくない、集中的で単独で完結するタスクを実行するスキルに便利です。 スキルをサブエージェントとして実行する方法は 2 つあります。subagent: true
subagent: true を設定すると、デフォルトの subagent_general プロファイルを使用して、スキル をサブエージェントとして実行します。
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 ツールを自動承認することもできます:
使用例
コードレビュースキル
コンポーネントジェネレーター
デプロイチェックリスト
検索エキスパート
ヒント
プロンプトは焦点を絞る
スキルは1つのことを確実にこなせるようにしましょう。1つの巨大なスキルを作るのではなく、複数のスキルに分けて作成してください。
使用例を含める
プロンプト内で、望ましい出力の例をエージェントに示しましょう。
スキルに禁止したい操作は deny する
ツールをブロックするには
permissions.deny (またはカスタムサブエージェントプロファイル) を利用してください。allowed-tools は確認プロンプトを省略するだけです。/skill-name でテストする
スキルを呼び出して、出力が意図どおりになるまでプロンプトを調整しましょう。

