skill-check

SkillCheck（無料版）

スキルが Anthropic のガイドラインおよび agentskills 仕様に準拠しているか確認します。このファイルには、無料版の検証ルールが記載されています。

より詳細な分析をご希望ですか？ Pro にアップグレードすると、スロップ検出、セキュリティスキャン、トークン最適化、WCAG 準拠チェック、エンタープライズ向けチェック、Eval Kit（スキル用テストプロンプトの自動生成）をご利用いただけます。

前提条件

• ファイルの読み取り機能を持つ AI アシスタント（Claude Code、Cursor、Windsurf、Codex CLI）
• あらゆるプラットフォーム（Unix/macOS/Windows）で動作します
• 特別なツールは不要です（読み取り専用です。Invisible Unicode チェックでも Grep を使用しますが、こちらも読み取り専用です）
• 環境変数や API キーは不要です。チェックは完全にオフラインで実行されます

インターフェース

• 入力：SKILL.md ファイルのパス（複数可）、および同じスキルフォルダー内の references/*.md ファイル
• 出力：各問題について、チェック ID、重大度（Critical / Warning / Suggestion）、行番号、修正方法を記載した検証レポート。強みは別のリストに記載されます
• モード：単一のスキルに対して単独で実行するか、スキルのディレクトリ全体に対して実行します。スキルごとにレポートを1つ生成します

ワークフロー

対象スキルごとに、4つのステージを順番に実行します。データは次のステージへ引き継がれます。ステップ1のファイル一覧をステップ2に渡し、読み込んだ内容をステップ3に渡し、検出結果をステップ4に渡します。

• ステップ1：検索 — Glob を使って対象の SKILL.md ファイルを検索します
• ステップ2：読み取り — SKILL.md の内容と references/ ファイルを読み込みます
• ステップ3：検証 — 読み込んだ内容に以下の各ルールを適用します
• ステップ4：レポート — 検出した問題を重大度、行番号、修正方法とともに列挙します

実行上限：最大反復回数：スキルごとに検証パスは1回です。検索した各スキルについてレポートを1回出力した時点で終了してください。SKILL.md を読み取れない場合は中止し、その旨をレポートに記載してください。このチェックは読み取り専用で冪等です。安全に再実行でき、ファイルが変更されていなければ、繰り返し実行しても同じレポートが生成されます。

---

無料版の検証ルール

以下の各チェックについて、妥当な例と妥当でない例を references/examples.md に掲載しています。このファイルを読みやすく保つため、ルールはこちらにまとめ、例は別ファイルに記載しています。

以下のチェックを順番に適用します。各サブセクションでは、照合するパターンと報告する問題を定義しています。

1. フロントマターの構造

すべての SKILL.md は、--- マーカーで囲まれた YAML フロントマターで始まる必要があります。

必須フィールド

フィールド	必須	ルール
name	はい	小文字、使用できるのはハイフンのみ、1～64文字、予約語は不可
description	はい	WHAT + WHEN の形式、1～1024文字

フロントマターのセキュリティ

チェック 1.9-xml-in-frontmatter（Critical）：フロントマターの値に XML の山括弧（< または >）を含めてはいけません。フロントマターは Claude のシステムプロンプトに含まれるため、山括弧がプロンプトインジェクションを引き起こすおそれがあります。

検出方法：フロントマター内のすべての文字列値（name、description、compatibility など）をスキャンし、< または > の文字がないか確認します。

修正方法：フロントマターから山括弧を削除します。説明にはプレーンテキストを使用してください。SKILL.md の本文では、Markdown の書式設定や XML タグを使用できます。

オプションフィールド（仕様）

agentskills.io の仕様で定義されているフィールド：

フィールド	用途
license	ライセンス名、または同梱のライセンスファイルへの参照
allowed-tools	スキルが使用できるツール（スペース区切り、または YAML リスト）
compatibility	プラットフォームの互換性情報（最大500文字）
metadata	追加のキーと値のペア

Claude Code 拡張機能

Claude Code では認識されます（Claude Code スキルのドキュメントを参照）が、agentskills.io の仕様には含まれません。他のエージェントはこれらのフィールドを無視する場合があり、claude.ai へのアップロードと Skills API では拒否されます（1.19 を参照）。

フィールド	用途
when_to_use	追加のトリガーコンテキストです。スキル一覧の description に追加されます
argument-hint	想定される引数のオートコンプリート用ヒントです
arguments	$name 置換に使用する名前付き位置引数です（スペース区切りの文字列または YAML リスト）
model	使用するモデルを上書きします（claude-opus-4-6 のような完全な ID、エイリアス：opus、sonnet、haiku、または inherit）
effort	労力レベルです。low、medium、high、xhigh、max のいずれかです
disallowed-tools	スキルが有効な間に削除されるツールです（スペース区切りまたはカンマ区切りの文字列、あるいは YAML リスト）
context	実行コンテキストです（サブエージェントの場合は "fork"）
agent	context が fork の場合のエージェントの種類です
background	context: fork の場合、フォークした処理の結果を待つには false を設定します（デフォルト：true）
hooks	ライフサイクルフックです（PreToolUse、PostToolUse、Stop）
paths	スキルの自動有効化の条件を限定する Glob パターンです（カンマ区切りの文字列または YAML リスト）
shell	インラインコマンドで使用するシェルです。bash（デフォルト）または powershell です
user-invocable	スラッシュメニューに表示するかどうかです（デフォルト：true）
disable-model-invocation	手動実行専用のスキルです

コミュニティ拡張機能

いずれの仕様にも含まれず、Claude Code も読み取りません（通知なしで無視します）。コミュニティのツールやレジストリで使用されます。1.8 または 1.19 の対象として報告しないでください。

フィールド	用途
category	発見とフィルタリングに使用するスキルの分野です
produces	このスキルが出力する成果物の種類です（カンマ区切り）
consumes	このスキルが他のスキルから読み取る成果物の種類です（カンマ区切り）
type	スキルの種類を示す値です
author	スキルの作成者です
date	作成日または更新日です

フィールドの認識と値

Check 1.8-unexpected-field（提案）：上記3つの表（仕様、Claude Code、コミュニティ）のいずれにもないトップレベルのキーです。Claude Code は未知のキーをエラーなしで無視するため、タイプミスがあっても何も起こりません。claude.ai へのアップロードと Skills API ではファイル全体が拒否されます。metadata 内のキーは自由形式であり、報告されることはありません。

Check 1.13-disallowed-camelcase（提案）：disallowedTools はサブエージェント用の表記です。SKILL.md のフィールドは disallowed-tools であり、camelCase のキーは無視されます。1.8 ではなく、この項目として報告してください。

Check 1.12-maxturns-not-skill-field（提案）：maxTurns はサブエージェント用のフィールドであり、スキル用ではありません。Claude Code は SKILL.md 内のこのフィールドを無視します。1.8 ではなく、この項目として報告してください。

Check 1.19-non-portable-field（提案）：仕様に含まれない、存在するすべてのキーを1件にまとめて列挙します。対象は Claude Code の表とコミュニティの表の両方です。Claude Code はこれらを読み込むか無視しますが、claude.ai へのアップロードと Skills API が受け付けるのは name、description、license、compatibility、metadata、allowed-tools のみです。

Check 1.11-effort-invalid（警告）：effort が low、medium、high、xhigh、max のいずれでもありません。

Check 1.18-bool-value（警告）：user-invocable、disable-model-invocation、background のいずれかに、true、false、yes、no、on、off、1、0 以外の値が設定されています（大文字と小文字は区別されません）。

Check 1.14-listing-cap（警告）：description と when_to_use の合計が1,536文字を超えています。スキル一覧では、結合されたテキストがその文字数で切り詰められるため、末尾のトリガーが失われます。主な使用例を先頭に記載してください。

Check 1.15-shell-invalid（警告）：shell に bash または powershell 以外が設定されています。

Check 1.16-background-no-fork（提案）：background が設定されていますが、context: fork は設定されていません。このフィールドはフォークしたスキルにのみ適用されます。

Check 1.17-paths-invalid（警告）：paths が Glob 文字列（カンマ区切り可）または Glob 文字列の YAML リストではありません。たとえば、マップ、数値、ブール値、空の値などです。

カテゴリの検証

注：category はコミュニティによる拡張であり、agentskills.io の仕様には含まれません。category フィールドがないことを指摘しないでください。存在する場合にのみ、形式を検証してください。

形式：文字列、または文字列の配列。使用できるのは小文字、数字、ハイフンのみです。

パターン：^[a-z][a-z0-9-]*[a-z0-9]$（スキル名と同じルール）

一般的なカテゴリ：development、productivity、data、automation、writing、design、security、devops、api、testing、documentation、legal、financial、marketing、ai-ml

成果物の受け渡しの検証

注：produces と consumes は、スキル間で成果物を受け渡すためのコミュニティ拡張です。フィールドがないことを指摘しないでください。存在する場合にのみ、形式を検証してください。

形式：成果物タイプ名をカンマで区切ったリスト。各タイプは小文字とハイフンのみで指定します。

既知の成果物タイプ：content-brief、knowledge-note、reading-log-entry、sift-article

チェック 1.10-artifact-types（警告）：produces または consumes に上記の既知のリストにないタイプが含まれている場合、エラーではなく警告として指摘します。新しいタイプも有効です。既知のリストは出発点であり、登録簿ではありません。

チェック 1.11-consumes-without-tools（警告）：スキルに consumes: が宣言されているのに、allowed-tools に Read または Glob が含まれていない場合、警告として指摘します。成果物を受け取るには、ファイルを読み取る必要があります。

名前の検証

パターン：^[a-z][a-z0-9-]*[a-z0-9]$

命名の提案：スキルの内容を説明しない一般的な用語は避けてください：helper、utils、tools、misc、stuff、things、manager、handler。製品固有の用語（claude、anthropic、mcp）は使用できますが、エージェント間での移植性が制限される場合があります。

説明の検証

次の内容を含める必要があります：

1. WHAT：スキルの機能を説明する動作動詞
2. WHEN：いつ使用するかを示すトリガーフレーズ
3. 主な機能（推奨）：対応する具体的なタスクやファイルタイプ

推奨される構成：[機能] + [使用する場面] + [主な機能]

動作動詞：作成、生成、構築、変換、抽出、分析、加工、処理、検証、整形、エクスポート、インポート、解析、検索、発見

WHEN トリガー：「次の場合に使用」「次の用途に使用」「次の場合にこのスキルを使用」「次の場合に呼び出す」「次の場合に有効化」「次の場合にトリガー」「自動的に有効化」「次の場合に実行」「次に適用」「次を支援」

allowed-tools の検証

スペース区切り形式（allowed-tools: Read Glob）と YAML リスト形式のどちらも有効です。両方の形式については references/examples.md を参照してください。

ディレクトリ構造の検証

agentskills の仕様では、スキルに次の任意のサブディレクトリを含めることができます：

ディレクトリ	目的	検証
references/	追加ドキュメント（REFERENCE.md など）	ファイルは .md 形式にしてください
scripts/	実行可能なコード（Python、Bash、JS）	実行権限を設定してください
assets/	静的リソース（テンプレート、データ）	検証は不要です

README.md を含め、その他のファイルも agentskills の仕様に従ってスキルフォルダーに配置できます。これらを指摘しないでください。

サポートされるスキルパス形式：

• 標準：~/.claude/skills/{skill-name}/SKILL.md
• 名前空間付き：~/.claude/skills/{namespace}/{skill-name}/SKILL.md

名前空間のサポート：名前空間を使うと、スキルをソース（個人、チーム、プロジェクト）別に整理できます：

• ~/.claude/skills/internal/weekly-reports/SKILL.md
• ~/.claude/skills/shared/code-review/SKILL.md

ディレクトリ名はスキル名と一致している必要があります：親ディレクトリ名は、フロントマターの name フィールドと完全に一致している必要があります。

---

2. 命名の品質

名前は単語ひとつではなく、説明的な複合語にしてください。

長さの目安：最小 3 文字、最適 10～30 文字、最大 64 文字。

アンチパターンの形式チェック

チェック 2.8-antipattern-format（提案）：スキルでアンチパターンを説明する場合（見出しに「anti-pattern」「what not to do」「avoid」「common mistakes」「bad practices」「pitfalls」が含まれるセクション）、長文の文章ではなく、構造化された形式（表または箇条書き）を使用する必要があります。

次の場合に検出します：

• アンチパターンのセクションに、「don't／avoid／never」を含む長い文章の行（100文字以上）がある
• アンチパターンのセクションに、回避を指示する表現が3つ以上含まれる文章の行が3行以上ある

次の場合は検出しません：

• セクションですでに表（| col | col |）または箇条書き（- item）を使用している
• セクションの見出しにアンチパターンを示すキーワードが含まれていない

---

3. 意味チェック

スキルの指示に論理的な一貫性と明確さがあるかを検証します。

矛盾の検出

同じ行動を同時に要求し、禁止する矛盾した指示を検出します。

曖昧な用語

より具体的にする必要がある曖昧な表現を検出します。「複数の項目」や「適切な設定」のような用語では、具体性が不足しています。代わりに、正確な数や具体的な基準を使用してください。

例外（検出対象外）：

• コードブロックまたは引用ブロック内の用語
• インラインコードのスパン（バッククォート）内の用語。バッククォートで囲まれた文字列は曖昧な記述ではなく、引用された例です
• 例／使用法／パターンのセクション内の内容
• Before／Afterや正しい例／誤った例の比較行
• 修飾語を伴う用語（例：「特定のファイルの一部」）

出力形式の指定

出力に言及するスキルでは、具体例を用いて形式を指定する必要があります。

検出方法：

• ## Output セクションがないのに、スキルが「output／returns／produces」に言及している
• 出力セクションがあるものの、コードブロック、JSON、表のいずれもない

格言・一般論の検出

チェック 4.6-wisdom-platitude（提案）：実行可能な内容を伴わない一般的な助言（「格言」）を検出します。スキルには、動機づけを目的とした文章ではなく、具体的な指示を記載する必要があります。

3つの検出レイヤー：

1. 冒頭のパターン：「Remember that」「It's important to」「Keep in mind that」「Think about」「Never forget that」「Always keep in mind」「Consider the importance of」など、格言的な表現で始まる行
2. 一般論の構文：「[名詞] is essential/crucial/important to [名詞]」という行中のパターン
3. 曖昧な命令：「Ensure quality」「maintain standards」「strive for best practices」

例外（検出対象外）：

• コードブロックまたは引用ブロック内の内容
• 例／使用法／パターンのセクション内の内容
• Before／Afterや肯定例／否定例の比較行

説明文のトリガースタイル

チェック 4.8-description-trigger-style（提案）：説明フィールドは、機能の概要ではなく、トリガー条件として読めるようにする必要があります。Claude は説明をスキャンし、「このリクエストに対応するスキルはあるか」を判断します。リクエストをトリガーとする説明は適切な場面で有効になりますが、概要中心の説明は見過ごされる可能性があります。

検出方法：説明文がトリガーを示す表現ではなく、概要を示す表現で始まっている場合：

• 概要を示す冒頭表現（検出対象）：「This skill」「A tool that」「Provides」「Offers」「Handles」「Manages」「Enables」
• トリガーを示す冒頭表現（検出対象外）：「Use when」「Generate」「Build」「Convert」「Extract」「Validate」「Run」「Create」「Find」「Search」

次の場合は検出しません：

• 説明文が概要を示す表現で始まっていても、後半に WHEN トリガー句が含まれる（「Handles X. Use when user says Y」は問題ありません）
• 説明文が動作を示す動詞で始まっている

重大度：提案

修正方法：動作を示す動詞で始め、「Use when」の句を含めるように書き換えてください。説明は文書ではなく、ルーティング指示です。

先走りの検出

チェック 4.9-railroading（提案）：スキルでは、厳密な手順を指示するのではなく、Claude に情報とコンテキストを与える必要があります。過度に指示的な表現は、ユーザーの実際の状況に応じて Claude が対応する能力を低下させます。

検出方法：例のブロック、コードブロック、アンチパターンのセクション以外にある指示的な表現を数えます。

• 「必ず常に〜すること」、「常にまったく同じように〜すること」、「決して逸脱しないこと」、「以下の手順に厳密に従うこと」、「これを変更しないこと」、「これが唯一の方法である」、「〜することが必須である」

該当条件：例以外のコンテンツに指示的な表現が 5 つ以上ある場合。

該当しない条件：

• 指示的な表現がコードブロック、引用ブロック、または例のタグ内にある
• 指示的な表現がアンチパターン／注意点のセクションにあり、してはいけないことを説明している
• スキルが安全上重要なものであり（セキュリティ、コンプライアンスなど）、厳密な指示が妥当である

重大度：提案

ルーティング情報の配置ミス

チェック 4.4：本文に、説明フィールドに記載すべき起動条件が含まれています。

検出方法：本文に ## When to Use または ## When to Use This Skill に一致する見出しがある、あるいは本文に「ユーザーが〜したときに有効化」、「次の場合にこのスキルを起動」、「次の場合にこのスキルを使用」といったルーティング表現が含まれている。

問題点：本文は Skill ツールが呼び出された後にのみ読み込まれます。ここに起動条件を記載しても、ルーティングの判断には影響しません。Claude はルーティング中に description フィールドを読み取ります。「次の場合に使用」のパターン、起動キーワード、例となるフレーズはそこに記載してください。

重大度：警告

修正方法：本文のセクションから独自の起動条件を description フィールドに統合し、重複する本文のセクションを削除します。

中身のないコンテンツ

チェック 22.7-hollow-content（提案）：具体的な知識がなく、一般的な埋め草だけで構成された注意点／トラブルシューティングのセクションは、中身がありません。苦労して得た助言を期待させる一方で、ありきたりなことしか述べていません。

検出方法：## Gotchas／## Troubleshooting／## Tips／## Caveats／## Pitfalls セクション内で、以下の一般的な埋め草表現のリストに一致する行が 3 行以上あり、かつ具体的な知識を示す要素（具体的なしきい値／単位付きの数値、「Y なので X」のような結果、番号付きのデバッグ手順、またはファイル／関数への参照）が含まれる行がない場合に該当します。

follow team standards
ensure proper handling
handle appropriately
consider relevant factors
use appropriate methods
maintain quality

例外（該当しません）：コードブロック内のコンテンツ、および具体的なしきい値、結果、またはデバッグ手順を少なくとも 1 つ含むセクション。

安全上の例外を設けない抑制

チェック 28.2-restraint-without-carveout（警告）：スキルが抑制や最小限主義を指示しているにもかかわらず、検証、セキュリティ、アクセシビリティに関する例外を設けていない場合に警告します。この例外がないと、単なる過剰な作り込みを避けるだけでなく、必須事項を省くことまで推奨しかねません。「怠惰であっても、怠慢ではない」ことが基準です。

検出方法：抑制／過剰な作り込みを避ける指示（YAGNI、「最小限にとどめる」、「作り込みすぎ／過剰に複雑化しない」、「動作する最も単純な方法」、「追加したい衝動を抑える」、「標準ライブラリを優先する」など）があり、かつ、安全に関する名詞（検証、セキュリティ、アクセシビリティ／a11y）と「決して削らない」、「常に維持する」、「引き続き必須である」、「妥協できない」といった維持／削減禁止の表現を組み合わせた行がない場合に該当します。「セキュリティ」や「検証」に触れていても、維持を示す表現がなければ例外として認められません。

該当しない条件：抑制を促す指示がない場合、または明示的な例外条項がある場合。

重大度：警告

---

4. 品質パターン（強み）

スキルに見られる肯定的なパターンを認識します。問題ではなく「強み」として報告されます。チェック 8.1～8.9 では、例のセクション、エラー処理、起動フレーズ、出力形式、構造化された指示、前提条件、否定的なトリガー、注意点のセクションを検出します。各パターンの検出方法と実例は references/examples.md に記載されています。

---

5. 不可視の Unicode（Cat 30）

不可視文字は、人間のレビュアーには見えないように指示を隠しながら、すべての AI エージェントに読み取らせます。SKILL.md とすべての references/*.md ファイルに対して、次の 3 つの Grep 検索を実行してください。ファイルを読んで見つけようとしてはいけません。文字は何も表示されないため、確実に検出できるのはパターン検索だけです。

ASCII スマグリング

チェック 30.1-ascii-smuggling（重大）：Unicode のタグ文字を使うと、ASCII メッセージ全体を隠せます。

検出：Grep パターン [\x{E0000}-\x{E007F}]。

除外：このブロックの正当な用途は、正しい形式の旗絵文字だけです。U+1F3F4 の後に 2～6 個のタグ文字（英字または数字）が続き、最後にキャンセルタグ U+E007F が付く形式です（スコットランド旗／ウェールズ旗）。マッチ箇所が U+1F3F4 の直後にあり、U+E007F で終わっていれば絵文字なので、問題として報告しないでください。このブロック内のそれ以外の文字はすべてスマグリングです。

報告：ペイロードをデコードし（U+E0020～U+E007E の各文字について、コードポイントから 0xE0000 を引き、ASCII として読み取ります）、検出結果にデコードしたテキストを引用してください。これにより、作成者は何が隠されていたかを正確に確認できます。

Trojan-Source の BiDi オーバーライド

チェック 30.2-bidi-override（重大）：双方向制御文字によって、表示されるテキストと実際のテキストが異なる場合があります（CVE-2021-42574）。画像のように見えるファイル名が、実際には実行可能ファイルを指していることもあります。

検出：Grep パターン [\x{061C}\x{200E}\x{200F}\x{202A}-\x{202E}\x{2066}-\x{2069}]。

検出対象外となる場合：スキルがアラビア語やヘブライ語などの右から左に書く文字体系を正当に含むバイリンガルの内容であり、その文章内にマークが現れる場合です。英語のみのスキル、コードブロック、ファイル名、コマンドに含まれる BiDi マークは、必ず検出対象として報告してください。

ゼロ幅文字

チェック 30.3-invisible-run／30.4-invisible-char：ゼロ幅文字は、単語を見えない形で分割したり、隠しデータを符号化したりします。

検出：Grep パターン [\x{034F}\x{180E}\x{200B}\x{200C}\x{2060}\x{FEFF}\x{2061}-\x{2064}\x{206A}-\x{206F}]。

重大度：1 行に 10 個以上連続してマッチする場合は重大（30.3、隠しデータのチャネル。40 個以上なら意図的であることは明白です）。3 個以上がまとまっている場合は警告、単独の場合は提案（30.4）です。

除外：ファイルの先頭にある U+FEFF は、ツールによって付加されたバイトオーダーマークです。何も報告しないでください。ゼロ幅接合子と異体字セレクターは意図的にパターンから除外されています。これらは絵文字の並び（家族の絵文字、❤️）において構造上必要なものであり、検出対象にすると作成者がこのカテゴリを無視するようになるためです。