agent-skill-linter

エージェントスキルリンター

エージェントスキルが仕様に準拠し、公開できる状態かどうかを確認します。

想定されるレイアウト

ターゲットに .claude-plugin/plugin.json があるかどうかによって自動検出される、次の 2 つのレイアウトに対応しています。

• 単一スキル — リント対象は skill/ サブディレクトリ（またはレガシーリポジトリの場合はリポジトリのルート）です。skill/ レイアウトのリポジトリのルートを指定しても問題ありません。リンターは skill/ にリダイレクトし、その旨を stderr に表示します。
• プラグイン — リント対象はプラグインのルートです。マニフェストと各 skills/<name>/ をチェックします。

レイアウト図、ファイルごとの規約、モードごとの検出ルールについては、references/layouts.md を参照してください。

トリアージワークフロー

対象： リントするスキルディレクトリ — 現在のディレクトリ（.）またはユーザーが指定したパス。

ステップ 1 — 全体像を把握する

./scripts/skill-lint.py check <target>

出力を確認してエラーと警告を把握し、ステップ 2 に進む前に全体像を確認します。

ステップ 2 — まずエラーを修正する

ルール 1 のエラー（SKILL.md の仕様準拠）は公開を妨げます。何よりも先に修正してください。Claude Code の拡張フィールドに関する検出結果は警告なので、ステップ 4 で対応します。

ステップ 1 を再実行してエラーが報告されなくなった場合にのみ、ステップ 3 に進みます。2 回修正を試みてもエラーが残る場合は、作業を中止してリンターの出力をユーザーに提示してください。

ステップ 3 — 警告を自動修正する

./scripts/skill-lint.py check <target> --fix

CLI がない修正可能なルールについては、references/fix-templates.md のテンプレートを使用してください。

ステップ 4 に進む前に、自動修正可能な警告が残っていないことを確認します。

ステップ 4 — 残りの警告を手動で解決する

CSO の説明文のプレフィックス（ルール 11）、Python の呼び出し（ルール 13）、SKILL.md の README レベルのセクション（ルール 19）、フロントマターの Claude Code 拡張フィールド（ルール 1 の警告：スキルが Claude Code 専用の場合は残し、クロスプラットフォームで公開する場合は削除します）については、以下のルール表を参照してください。

ステップ 5 に進む前に、残りの警告がすべて解決済み（または明示的に許容済み）であることを確認します。

ステップ 5 — 意味のレビュー：CSO シグナル

ルール 11 は構造的なパターンを検出しますが、意味までは検出しません。フロントマターの description と name を読み、ルーティングシグナルとしてのみ機能しているかを確認してください。

例については、references/semantic-rules.md のルール 12 と 18 を参照してください。

次の場合は description にフラグを立てます。

• スキルがチェック、処理、またはサポートする内容を列挙している
• 機能の要約やワークフローの概要のように読める
• 説明を補足するラベル（Triggers on:、Use cases:、Checks:）や複数の文が含まれている
• ルーティングの精度を損なわずに 1 つの節に短縮できる

名詞句のように読める場合は name にフラグを立てます。名詞形（skill-creator、pdf-processor）より、動名詞（creating-skills、processing-pdfs）を優先してください。短く、よく知られた名前（pdf、commit）は問題ありません。

適切な description はトリガー条件のみを示します。それ以外はすべてスキル本文に記載します。

ステップ 6 に進む前に、description と name が純粋なルーティングシグナルとして機能していることを確認します。

ステップ 6 — 意味のレビュー：スタータープロンプト

ルール 7 はプロンプトの有無を検出しますが、有用かどうかは判定しません。Usage セクションのスタータープロンプトを読み、実際に異なるトリガーシナリオを反映しているかを確認してください。

次の場合はフラグを立てます。

• 曖昧または一般的である（例：Use this skill、Run the linter）
• 表現が少し異なるだけで、すべて同じシナリオを説明している
• 実際のユーザーが遭遇するさまざまな状況を反映していない

ステップ 7 に進む前に、スタータープロンプトが実際に異なるユースケースを網羅していることを確認します。

ステップ 7 — 意味のレビュー：内容の重複

リンターはこれをチェックしません。SKILL.md と README で、同じ情報を異なる言葉で伝えていないかを確認してください。

例については、references/semantic-rules.md のルール 8 を参照してください。

言い換えによる重複にはフラグを立てます。SKILL.md はエージェント向け（トリアージワークフロー、ルール）、README は人間向け（インストール、使用例）にします。

ステップ 8 に進む前に、言い換えによる重複が残っていないことを確認します。

ステップ 8 — セマンティックレビュー：段階的な情報開示

ルール 15 では、既知のリファレンス層のキーワードを検出しますが、反応的なコンテンツすべてに識別可能な見出しがあるとは限りません。**エージェントは、このセクションを最初から読むのではなく、必要に応じて参照するでしょうか？**と確認してください。

例については、references/semantic-rules.md — ルール 16 を参照してください。

次に該当するセクションは、references/ に移すよう指摘してください。

• 見出し名にかかわらず、リファレンス資料であるもの（例：「背景」、「仕組み」）
• 短く、ルール 15 で検出されない場合でも、情報量が多い、または条件付きのもの
• 最初から読む必要はないのに、メインのワークフローを膨らませている、手順固有の詳細ブロック

また、**セクションが条件付き（「…の後」、「…したら」、「…の場合」）の場合、その見出しか最初の行に、エージェントが確認できる具体的なトリガーイベントが示されていますか？**と確認してください。

例については、references/semantic-rules.md — ルール 27 を参照してください。

トリガーが曖昧な条件付きセクションを指摘してください。「出力を確認した後」、「コンテキストを理解したら」などの表現では、エージェントはいつそのセクションに進むべきか判断できません。

ステップ 9 に進む前に、反応的なコンテンツがすべて references/ に移され、条件付きセクションすべてに観測可能なトリガーが明記されていることを確認してください。

ステップ 9 — セマンティックレビュー：複数ステップのワークフローの品質

このステップは、スキルに複数ステップのワークフロー（### Step N 見出しが 3 つ以上）がある場合にのみ適用してください。

各ステップの本文を読み、**実質的な各ステップに、エージェントが完了を判断する方法が示されていますか？**と確認してください。

例については、references/semantic-rules.md — ルール 22 を参照してください。

本文に「何をするか」しか記載されておらず、終了条件、ゲートとなる表現、「次に進むのは…の場合のみ」といった合図がないステップを指摘してください。非常に短いステップ（1 行のみ）には、明示的なゲートは不要です。

また、**ワークフローには、言葉での報告だけでなく、実際のツール出力を確認するステップが少なくとも 1 つありますか？**と確認してください。

各ステップで操作を指示しているだけで、ツールが実際に返した内容を読むよう求めていない場合は、ワークフローを指摘してください。

さらに、**ツール出力を基にワークフローを繰り返す場合、再試行の上限と代替手段が明記されていますか？**と確認してください。

「うまくいくまで」といった表現以外に終了条件がないまま、再試行、反復、またはツールの成功を待つよう指示しているワークフローを指摘してください。

ステップ 10 に進む前に、これら 3 つの質問すべてを満たしていることを確認してください。

ステップ 10 — セマンティックレビュー：平易な文章

ルール 28 は、読者向けドキュメント（README、ユーザーガイド）にありがちな、質の低い表現を検出します。それぞれを、エージェントスキルについては知っていても、このプロジェクトを見たことのない開発者の立場で読み、**マーケティング的な誇張や AI 風の水増し表現を使わず、短く能動的な文で、スキルの機能と対象読者を説明していますか？**と確認してください。

チェックリストと委任に関する注記は、references/semantic-rules.md — ルール 28 を参照してください。

critiquing-articles を利用できる場合は、その AI 風表現の監査を委任してください（リファレンスにあるジャンル別の注記と代替チェックリストを参照してください）。

書き換え案を提示し、ユーザーの同意を得てから適用してください。ステップ 11 に進む前に、読者向けドキュメントがすべて平易な文章になっていることを確認してください。

ステップ 11 — Info 項目を仕上げとして対応する

本文の長さ（ルール 9）、標準外のディレクトリ（ルール 10）、スキルの分離（ルール 17）。

チェック項目

#	ルール	重大度	自動修正
1	SKILL.md の仕様準拠（skills-ref 経由）。Claude Code の拡張フィールド（disable-model-invocation、model、hooks…）は警告として扱います	エラー／警告	—
2	LICENSE が存在し、Apache-2.0 または MIT で、現行年が記載されている	警告	一部
3	SKILL.md のフロントマターに metadata.author がある	警告	はい
4	README にバッジ（CI、ライセンス、Agent Skills）がある	警告	はい
5	.github/workflows/ に CI ワークフローがある	警告	はい
6	README にインストールセクションがある	警告	はい
7	README にスタータープロンプトと CLI のサブセクションを含む使用方法セクションがある	警告	一部＋ステップ 6
9	SKILL.md の本文が 500 行未満である	情報	—
10	標準外のディレクトリにフラグを付ける	情報	—
11	CSO：説明が「Use when...」で始まる	警告	ステップ 5
13	Python の実行方法が一貫している（uv プロジェクトでは uv run python を使用）	警告	—
14	段階的開示：埋め込みテンプレート（4 連バッククォートのフェンス）を references/ に移動する	警告	はい
15	段階的開示：リファレンス層の見出し（トラブルシューティング、FAQ、詳細など）を references/ に移動する	警告	はい＋ステップ 8
17	スキルの分離：スキル以外の成果物とともにリポジトリのルートに SKILL.md がある（SKILL.md が skill/ にある場合は通知されません）	情報	—
19	役割分担：README 向けのセクション（インストール、機能、はじめになど）が SKILL.md にある	警告	—
20	トリアージのワークフローに 3 つ以上の手順があるが、意味的なレビュー手順（例：「〜かどうかを確認する」）がない	情報	ステップ 5～10
21	scripts/ 内の Python エントリーポイントスクリプトに PEP 723 のインライン依存関係メタデータがない	警告	—
24	プラグインマニフェスト .claude-plugin/plugin.json が存在し、解析可能で、name と version がある	エラー	—
25	標準ライブラリ以外のコードをインポートするスキルスクリプトで、依存関係のソース（PEP 723、プラグインルートの pyproject.toml、または隣接ディレクトリ）が宣言されている	エラー	—
28	ユーザー向けドキュメント（README、ユーザーガイド）の通常の文章：過剰な最上級表現、要点が埋もれた導入や前置き、長い文や段落、em ダッシュの連続	情報	ステップ 10

ルール 24 と 25 は、リント対象に .claude-plugin/plugin.json があるプラグインモードでのみ適用されます。

CLI リファレンス

./scripts/skill-lint.py check .                            # Auto-detect: skill, skill/ subdir, or plugin
./scripts/skill-lint.py check ./my-skill --fix             # Single-skill, auto-fix
./scripts/skill-lint.py check ./my-plugin                  # Plugin: validates manifest +
                                                           # iterates skills/<name>/
./scripts/skill-lint.py check ./my-skill --format json     # JSON output for CI

エラーがある場合は終了コード 1、ない場合は 0 です。