Claude Agent Skillsが発火しない原因は「description」にあり：設計パターン完全ガイド¶

この記事で学べること

descriptionの役割（what+when / 第三人称）発火率を上げる設計パターンとテンプレート日本語入力・音声入力でのトラブル回避策

はじめに：このガイドの対象¶

本記事は Anthropic Platformの「Agent Skills（SKILL.md）」 を前提に、descriptionを設計するための完全ガイドです。

Agent Skillsでは、各Skillはディレクトリで管理され、エントリポイントは SKILL.md です。先頭のYAML frontmatterには name と description が必須で、descriptionは non-empty / 最大1024文字 / XML禁止 などの要件が定義されています。

この descriptionは単なる説明文ではありません。公式ベストプラクティスが強調する通り、Claudeが「いつそのSkillを使うべきか」を判断するためのディスカバリ用メタデータであり、what（何ができるか）＋when（いつ使うか）＋具体的トリガー語を含めることが求められます。

注

ClaudeアプリのCustom Skills UIでは descriptionが200文字上限など制約が異なります。本記事はPlatform Agent Skills（1024文字上限）を基準に説明し、差分は付録で扱います。

この記事の対象者

Claude Code Skillsを配置しているが期待通りに発火しない開発者

descriptionの役割：what + when + 第三人称¶

公式が求める3つの要素¶

descriptionは「説明文」ではなく索引です。公式ドキュメントは次の要素を求めています。

What（何をするか） - Skillが生成する成果物やフォーマット
When（いつ使うか） - 発火すべき状況やトリガー語
第三人称で書く - システムプロンプトに注入されるため、視点の不整合を避ける

✅ Good: "Processes Excel files and generates reports"
❌ Avoid: "I can help you process Excel files"
❌ Avoid: "You can use this to process Excel files"

なぜ第三人称か

descriptionはシステムプロンプトに注入されます。「I/you」が混在すると、Claudeのディスカバリ処理で視点の不整合が起き、探索品質が落ちると公式が明言しています。

Progressive Disclosure（段階的開示）の入り口¶

Skillsは段階的開示として設計されています。起動時に読み込まれるのは メタデータ（name/description）だけ で、必要なときにだけ本文や追加リソースへ進みます。

この設計から導ける実務原則はシンプルです。

description = 発火条件（when）＋能力宣言（what）＋検索語彙（keywords）本文（SKILL.md body）= 実装・手順・例・辞書（同義語や誤変換）

descriptionで「いつ・何を」を明確にし、詳細は本文に任せる。この分業ができていないと、発火しないか、誤発火します。

仕様：descriptionの制約¶

バリデーション対象（違反するとエラー）¶

項目	制約
空	不可（must be non-empty）
長さ	最大1024文字
XMLタグ	禁止
name	最大64文字、小文字/数字/ハイフンのみ

Best Practice（違反しても動くが品質が落ちる）¶

what + when を含める - 何をするか、いつ使うかを明記
第三人称で書く - I/you を避ける
具体的なトリガー語を含める - ユーザーが自然に使う言葉を入れる

発火率を上げるdescription設計パターン¶

「what → when → do-not」の黄金形¶

効果的なdescriptionには3つの要素が必要です。

What：何をするSkillか（出力やフォーマットまで言う）
When：いつ使うか（トリガー語＋状況）
Do-not：やらないこと（誤発火防止）

テンプレート：仕様書（Spec）¶

description: Produces software specification documents in Markdown: purpose, scope,
  assumptions, functional/non-functional requirements, interfaces, constraints,
  and acceptance criteria. Use when user requests "仕様書", "要件定義", "スペック",
  "requirements", "spec", provides business goal, user stories, constraints,
  or asks to formalize ambiguous ideas. Do NOT use for casual explanations
  or long-form essays; prefer this only when a structured spec artifact is needed.

分解すると

What: Produces software specification documents in Markdown: purpose, scope, assumptions, functional/non-functional requirements, interfaces, constraints, and acceptance criteria
When: "仕様書", "要件定義", "スペック", "requirements", "spec", business goal, user stories
Do-not: Do NOT use for casual explanations or long-form essays

テンプレート：議事録¶

description: Produces meeting minutes in Markdown with attendees, decisions,
  and action items including owner and due date. Use when user requests "議事録",
  "minutes", "meeting summary", or uploads a meeting transcript.
  Do NOT use for long-form reports or general document creation.

テンプレート：データ分析¶

description: Analyzes CSV/Excel files to produce summary statistics, trends,
  outliers, and charts. Use when user requests "分析", "sales report",
  mentions CSV/Excel, "前月比", "推移グラフ", or uploads tabular data files.
  Do NOT use for document writing or general explanations.

日本語入力と英語descriptionの照合¶

公式が保証していること¶

descriptionには what + when + key terms を入れて、Claudeがいつ使うべきか判断できるようにせよ
Claudeは 多言語に強い（multilingual support）

公式が明示していないこと¶

「日本語入力でも英語descriptionが意味でマッチする」といった照合アルゴリズム（embeddingで相互言語検索する等）は明示されていません。

実務の結論¶

ユーザー入力が日本語なら、descriptionに日本語トリガー語を含めるのが堅い設計です。これは「ユーザーが自然に言うキーワードを入れろ」という公式方針を日本語運用に適用しただけで、矛盾しません。

おすすめ運用

descriptionは JP/ENの上位5語 を入れる
同義語・表記ゆれ・誤変換は 本文（SKILL.md body）や参照ファイル に逃がす

音声入力（STT）で「仕様書→使用書」になる問題¶

Dictation vs Voice Mode¶

Claudeモバイルアプリには2つの音声機能があります。

機能	日本語対応	説明
Dictation（音声入力）	対応	音声がテキスト化されて送信される
Voice Mode（会話モード）	英語のみ	リアルタイム音声会話

Dictationは日本語を含む12言語に対応しています。発火は最終的に生成されたテキストで評価されるため、テストで担保できます。

STT誤変換への対策¶

誤変換（例：仕様書→使用書）が起きた場合の設計は、次の順で堅くなります。

descriptionに代表的な誤変換を1〜2個だけ入れる
本文（SKILL.md）に正規化ルールを置く（網羅は本文へ）

# descriptionへの組み込み例
description: Draft specs in Markdown. Use for 仕様書/使用書/要件/spec.
  Not for general Q&A.

「使用書」を誤変換の代表例として1つだけ入れています。網羅的な辞書は本文に置きます。

テスト手法：should trigger / should not trigger¶

公式はdescriptionを 反復調整してテストせよ と明記しています。テスト入力をテキストで固定しておくと、変更後の回帰テストが楽になります。

最小テストセット例（仕様書Skill）¶

should triggershould NOT trigger

「仕様書を作成して」
"Create a spec for X"
「要件定義をお願い」
（STT想定）「使用書を作成して」

「仕様書って何？」（定義質問）
「文章をいい感じに直して」（一般校正）
「このコードを説明して」（コード解説）

テスト観察のポイント¶

公式ベストプラクティスは、Skillの使われ方を観察して改善せよと推奨しています。観察すべきポイント：

予期しない発火パス - 意図しない入力で発火していないか
見逃し - 発火すべき入力で発火しなかったケース
過剰依存 - 特定のセクションばかり読まれていないか

アンチパターン：発火しないdescriptionの特徴¶

曖昧な動詞・名詞¶

# ❌ 悪い例
description: Helps with documents

# ✅ 良い例
description: Creates software specification documents in Markdown with scope,
  requirements, and acceptance criteria

「Helps with」「Processes」「Handles」などの曖昧動詞は、Claudeがいつ使うべきか判断できません。

トリガー語の不足¶

# ❌ 悪い例
description: Generates meeting notes

# ✅ 良い例
description: Produces meeting minutes in Markdown. Use when user requests
  "議事録", "minutes", "meeting summary", or uploads a transcript

ユーザーが実際に使う言葉（日本語含む）を入れないと、発火しません。

do-notの欠如¶

# ❌ 悪い例
description: Analyzes data and creates reports

# ✅ 良い例
description: Analyzes CSV/Excel files for statistics and trends.
  Do NOT use for document writing or general explanations

「何をしないか」を明記しないと、誤発火の原因になります。

よくあるトラブルと対処法¶

症状	原因	解決策
発火しない	what+whenが曖昧	具体的な成果物とトリガー語を明記
誤発火する	do-notがない	「Do NOT use for...」で境界を明示
日本語で発火しない	日本語トリガー語がない	JP/EN両方のキーワードを入れる
複数Skillで競合	境界が曖昧	各Skillのdo-notで棲み分けを明確化

まとめ¶

descriptionは索引。what + when + trigger + do-notを1024文字内で最適配分する
第三人称で書く。I/youを避け、システムプロンプトとの視点不整合を防ぐ
日本語運用なら日本語トリガーを入れる。照合アルゴリズムは非公開なのでテストで担保
should trigger / should not trigger でテストする。公式が推奨する反復調整を実践

参考リンク（公式一次情報）¶

付録：UI（Custom Skills）とClaude Codeの差分¶

ClaudeアプリUI（Custom Skills）¶

ClaudeアプリのUIからアップロードするCustom Skillsでは、descriptionの上限が 200文字 です。

# 200文字版（Custom Skills UI向け）
description: Draft specs in Markdown (scope, requirements, acceptance).
  Use for 仕様書/要件/spec. Not for Q&A.

200文字では詳細を書けないため、トリガー語は最小限にし、詳細は本文に逃がします。

Claude Codeの文字予算¶

Claude Codeでは、スキルのdescriptionがコンテキストに載せられますが、文字予算（デフォルト15,000文字） を超えると除外されます。

診断手順：

/context を実行して除外警告が出ていないか確認
多いなら SLASH_COMMAND_TOOL_CHAR_BUDGET 環境変数を調整
それでもダメなら、descriptionを短くする or スキルを分割する

スキル数	推奨description長
60+	130文字以下
40-60	150文字以下
40未満	200文字でも余裕あり