Agent Skills ヘッダーフィールド仕様について

2026/02/25 時点の情報を自分なりに整理したメモです。

概要

本メモは、エージェント・スキル（Agent Skills）の標準仕様における SKILL.md のヘッダーフィールド（YAMLフロントマター）および、各プラットフォームでの実装仕様について記述します。

前提条件

• エージェント・スキル標準（Agent Skills Standard）準拠
• 対応プラットフォーム：Claude Code, VS Code (GitHub Copilot)

1. ディレクトリ構造とファイル配置

スキルは独立したディレクトリとして構成し、その直下に SKILL.md を配置する必要があります。

推奨ディレクトリ構成

my-skill/
├── SKILL.md          # メタデータと指示（必須）
├── scripts/          # 実行可能なスクリプト
├── references/       # 補足ドキュメント
└── assets/           # テンプレートや静的リソース

配置場所（自動認識パス）

VS Code および Claude Code は、以下のディレクトリにあるスキルを自動的にロードします。

種類	パス（プロジェクト内）	パス（ユーザープロファイル内）
共通/推奨	.agents/skills/	~/.agents/skills/
Claude互換	.claude/skills/	~/.claude/skills/
VS Code標準	.github/skills/	~/.copilot/skills/

2. ヘッダーフィールド定義

SKILL.md の冒頭に記述する YAML フロントマターの仕様は以下の通りです。

共通必須フィールド

パラメータ	型	必須	説明
name	String	Yes	スキルの一意識別子。小文字、数字、ハイフンのみ。ディレクトリ名と一致させる必要があります。
description	String	Yes	スキルの役割と使用場面。エージェントが呼び出しを判断するために使用します（最大1024文字）。

共通オプションフィールド

パラメータ	型	必須	デフォルト値	説明
license	String	No	null	ライセンス情報。
compatibility	String	No	null	実行環境の要件（特定のOS、パッケージ、ネットワーク等）。
metadata	Map	No	{}	任意のメタデータ（author, version 等）。
allowed-tools	String	No	null	事前承認済みツールのリスト（実験的機能）。

VS Code (GitHub Copilot) 拡張フィールド

パラメータ	型	必須	デフォルト値	説明
argument-hint	String	No	null	チャット入力欄に表示される引数のヒントテキスト。
user-invokable	Boolean	No	true	スラッシュコマンド（/）として表示するか。
disable-model-invocation	Boolean	No	false	エージェントによる自動的なスキルロードを無効にするか。

3. 記述ルールと制約

ファイル参照の階層制限

SKILL.md 内で他のファイル（スクリプトやドキュメント）を参照する場合、参照先は SKILL.md から 1レベル（1階層）以内 に留めることが推奨されます。深い階層構造を持つ参照チェーンは、エージェントの処理効率を低下させるため避けるべきです。

相対パスの指定

リソースの参照には、スキルディレクトリのルートからの相対パスを使用します。

• 例：[参照ドキュメント](./references/DOC.md)

トラブルシューティング

問題1： スキルがエージェントに認識されない。

• 原因： name フィールドの値とディレクトリ名が一致していないか、配置場所が自動認識パスに含まれていません。
• 解決策： name フィールドとディレクトリ名を完全に一致させ、.agents/skills/ 等の推奨ディレクトリに配置してください。

問題2： ファイル参照が機能しない。

• 原因： 絶対パスを使用しているか、2階層以上深いファイルを参照しています。
• 解決策： 相対パス（./ 開始）を使用し、参照先を1階層以内に配置してください。

参照元

• Agent Skills Standard Specification
• VS Code Docs - Use Agent Skills
• Anthropic: Claude Code Overview