validate-skills

スキルの検証

skills/ 内のすべてのスキルを、agentskills.io の仕様および Claude Code のベストプラクティスに照らして検証します。

検証チェックリスト

各スキルディレクトリについて、次の項目を確認します。

仕様への準拠（agentskills.io）

チェック項目	ルール
name の形式	1〜64 文字、小文字の英数字とハイフンのみ。先頭・末尾のハイフンや連続するハイフンは使用不可
name とディレクトリ名の一致	ディレクトリ名は name フィールドと一致する必要があります
description の長さ	1〜1024 文字で、空欄ではないこと
オプションフィールドの有効性	license、metadata、compatibility が存在する場合

ベストプラクティス（Claude Code）

チェック項目	ルール
説明の形式	三人称で、内容と使用するタイミングを説明していること
本文の長さ	500 行未満
読み込みが1階層であること	SKILL.md のみが段階的開示のエントリーポイントです。すべての参照ファイルに SKILL.md から到達できる必要があります。以下の注記を参照してください。参照ファイル同士の相互リンクはナビゲーション目的で使用できます。
リンクが Markdown 形式であること	ファイル名だけではなく、[text](path) を使用すること
重複がないこと	本文で説明を繰り返さないこと
簡潔であること	Claude がすでに把握している内容は追加せず、必要な文脈だけを加えること

1階層ルールと相互リンクについて。 1階層ルールの対象は、段階的開示による読み込みチェーンです。参照ファイルを読み込まないと別の参照ファイルを見つけられない状態（SKILL.md → a.md → b.md。b.md は SKILL.md からリンクされていない）は不備です。読み込み側からコンテンツが見えなくなるためです。

ナビゲーション目的の相互リンクは禁止されていません。AGENTS.md に従い、参照ファイルの末尾には兄弟の参照ファイルにリンクする「Related Skills」フッターを付ける必要があります。両方のリンク先に SKILL.md から直接到達できる限り、相互リンクに問題はありません。別の参照ファイルを経由しないと到達できない参照ファイルのみを指摘してください。

実行方法

1. すべてのスキルディレクトリを検索します。

   fd -t d -d 1 . skills/
   

2. 各スキルの SKILL.md を読み、上記のルールに照らして確認します

3. 次の形式で問題を報告します。

   ## Validation Results
   
   ### skills/example-skill
   - [PASS] name format valid
   - [FAIL] name "example" doesn't match directory "example-skill"
   - [PASS] description length OK (156 chars)
   

参考資料

• agentskills.io の仕様
• Claude Code のベストプラクティス