貼り付けたSKILL.mdのYAMLフロントマターと本文をAgent Skills仕様に照らして検証します。エラー、警告、ノートを一覧表示し、CSV出力も可能です。
SKILL.mdファイルは、AIエージェントに特定のスキルやワークフローを教えるための標準フォーマットです。Agent Skills仕様に準拠したこのファイルは、通常 references/ フォルダなどの関連リソースを含むディレクトリ内に配置されます。ファイルの先頭にはYAML形式のフロントマターが記述され、その下にMarkdown形式の指示文が続きます。エージェントはまず name と description を読み込み、そのスキルが必要かどうかを判断します。必要と判断された場合にのみ、本文の詳細な指示が読み込まれ、実行に移されます。この仕組みにより、エージェントはコンテキストウィンドウを無駄に消費することなく、多数のスキルから適切なものを選択できます。SKILL.mdバリデーターを使用すると、このファイルが仕様に準拠しているかを即座に確認できます。
フロントマターはスキルのメタデータを定義する重要な部分です。必須フィールドと任意フィールドには、それぞれ厳格な文字数制限と書式ルールが存在します。name は必須であり、小文字、数字、単一のハイフンのみを使用でき、最大 [number=64] 文字です。また、オプションで指定するフォルダ名と一致する必要があります。description も必須で、最大 [number=1024] 文字です。compatibility は任意ですが、使用する場合は [number=500] 文字以内に収める必要があります。YAMLのインデントやコロンが原因で構文エラーが発生した場合は、JSONをYAMLに変換するツールなどで構文を確認すると便利です。
| フィールド | 必須 | 制限 |
|---|---|---|
name |
はい | [number=64] 文字以内、小文字と数字と単一ハイフン |
description |
はい | [number=1024] 文字以内 |
compatibility |
いいえ | [number=500] 文字以内 |
description は単なる説明ではなく、エージェントがそのスキルを使用するかどうかを決定するトリガーです。多くの場合、スキルがエージェントによって選択されない原因は、この description が曖昧であることにあります。仕様では、description が [number=60] 文字未満の場合に警告が発せられます。これは、スキルの目的と使用タイミングを十分に説明できていない可能性を示唆しています。優れた description には、そのスキルが何をするものかだけでなく、「いつ使用するべきか」という条件が明確に含められています。例えば、「CSVファイルを処理する」という記述は弱く、「ユーザーが大量の売上データをCSV形式で集計したい場合に使用する」という記述の方が強力なトリガーとなります。SKILL.mdバリデーターは、このような使用タイミングの文言が含まれているかもチェックし、不足している場合は注意を促します。
本文の指示は簡潔かつ構造化されている必要があります。Agent Skills仕様では、本文の長さを [number=500] 行以内、推定 [number=5000] トークン以内に抑えることが推奨されています。トークン数は1トークンあたり4文字として概算されますが、日本語のような非ラテン文字を含むテキストでは、実際のトークナイザーの挙動と乖離が生じる点に注意が必要です。本文が [number=20] 語未満の場合は警告となり、情報不足とみなされます。詳細な仕様や長いコードスニペットは本文に直接書かず、references/ フォルダ内の別ファイルに分離し、相対パスで参照するのがベストプラクティスです。その際、絶対パスや深くネストされたパスを使用すると警告の対象となるため、フラットなディレクトリ構造を心がけます。見出しを活用してエージェントがスキミングしやすい構造にすることが、安定した動作につながります。
SKILL.mdを複数のAIエージェント環境で使い回す場合、フィールドのポータビリティを理解しておく必要があります。model や hooks といったフィールドは、Claude Code専用の拡張機能です。これらのフィールドが記述されていてもエラーにはなりませんが、SKILL.mdバリデーターは「注意」としてレポートし、他のエージェント環境では無視されることを知らせます。不明なフィールドを独自に追加したい場合は、仕様で定義されている metadata フィールドの下にネストして記述するのが正しいアプローチです。また、allowed-tools フィールドは実験的な機能であり、YAMLのリスト形式ではなくスペース区切りの文字列として記述する必要があります。リスト形式で記述すると警告が発生します。環境に依存しない汎用的なスキルを構築するためには、標準仕様のフィールドのみを使用し、環境固有の設定は metadata に分離する設計が求められます。
SKILL.mdバリデーターの出力は、エラー、警告、注意の3つのレベルで構成されます。エラーは仕様の違反であり、1つでも存在するとファイルは無効と判定されます。例えば、フロントマターの欠落や name の書式違反がこれに該当します。警告は仕様のガイドラインからの逸脱です。ファイル自体は有効ですが、エージェントの動作に悪影響を及ぼす可能性があります。注意は、Claude Code専用フィールドの使用や、トークン推定の目安に関する補足情報です。レポートにはファイルの統計情報や結果テーブルが含まれ、CSV形式でエクスポートしてチーム内で共有できます。重要な点として、このツールはリンク先ファイルの実在確認や、指示文の品質評価は行いません。あくまで形式とガイドラインのチェックに特化しています。企業内部のワークフローや機密情報を含むスキルを扱う場合でも、すべての解析処理がブラウザ内で完結するため、データが外部サーバーにアップロードされることはありません。
SKILL.mdファイルの内容全体をテキストエリアに貼り付け、必要に応じてフォルダ名を入力して実行ボタンを押すだけです。ブラウザ上で即座にYAMLフロントマターと本文の解析が行われ、エラーや警告の一覧が表示されます。アカウント登録やインストールは一切不要です。
いいえ、データが外部に送信されることはありません。SKILL.mdバリデーターはすべての解析処理をブラウザ内で完結させるため、機密性の高い内部ワークフローやプロンプトを含むファイルでも安心してチェックできます。
必須フィールドは name と description の2つだけです。name は小文字、数字、単一のハイフンのみ使用可能で最大64文字、description は最大1,024文字という制限があります。その他の license や compatibility などは任意項目です。
最も多い原因は description の記述が曖昧で短いことです。エージェントはまずこの説明文を読んでスキルを読み込むか判断するため、具体的な機能と「いつ使うか」が明記されていないと選択されません。SKILL.mdバリデーターで警告が出ていないか確認し、60文字以上の具体的な記述に修正することをお勧めします。
エラーにはなりません。これらはClaude Code専用の拡張フィールドであり、SKILL.mdバリデーターではノート（備考）として表示されます。他のエージェントでは無視されますが、フォーマット自体は仕様上有効です。
コロンの後にスペースがない、インデントにタブ文字が使われている、またはキーのクォートが不足しているといった一般的なYAMLの構文ミスが原因です。複雑な構造のYAMLに不安がある場合は、JSONからYAMLへの変換ツールなどのツールで事前に構文を確認してから貼り付けるとスムーズです。
1トークンを4文字として計算する概算値です。英語のテキストには比較的正確ですが、日本語などの非ラテン文字を含むテキストでは実際のトークナイザーと大きく乖離する場合があります。あくまで本文のボリュームを把握するための目安としてご利用ください。
コマンドラインツールがフォルダ全体をチェックするのに対し、SKILL.mdバリデーターは単一のファイル内容をブラウザで手軽に検証できます。仕様のルールチェックに加え、文字数制限やClaude Code固有のフィールドに関するアドバイスも提供されるため、インストール不要で素早く確認したい場合に最適です。
はい、有効とみなされます。SKILL.mdバリデーターにおいて「有効」とはエラーがゼロであることを指します。警告は仕様のガイドラインに対する推奨事項や改善点であり、エージェントがスキルを読み込むこと自体を妨げるものではありません。
