Claude Agent Skillsが発火しない時の直し方：description設計とテスト¶
対象 / ポイント
対象: SKILL.mdは存在するのにClaudeがSkillを選ばない、または関係ない依頼で誤発火する問題を直したい開発者
ポイント:
descriptionはSkillの内容が読み込まれる前に、何ができて、いつ使うかをClaudeへ伝える発見用メタデータ- 必須仕様は非空・1024文字以下・XMLタグ禁止で、本文は500行未満が推奨
- 文面を感覚で調整せず、発火すべき依頼と発火すべきでない依頼を評価ケースとして固定する
最初に切り分ける¶
Skillが使われない原因はdescriptionだけではない。次の順で確認する。
- クライアントがSkillディレクトリを発見しているか
SKILL.mdのYAML frontmatterが仕様に合うかdescriptionが依頼の意図を区別できるか- 似たSkillと責任範囲が重なっていないか
- Skillが選ばれた後、本文の手順が成功するか
「Skillを一覧へ出せない」と「一覧には出るが選ばれない」は別の障害だ。前者は配置やfrontmatter、後者はdescriptionや競合を主に調べる。
descriptionが発火を左右する理由¶
Agent Skillsは段階的開示でコンテキストを使う1。
flowchart LR
A[name + description] -->|関連ありと判断| B[SKILL.md本文]
B -->|必要な時だけ| C[references / scripts / assets]セッション開始時に読み込まれるのは、主にSkillのnameとdescriptionだ。本文に「請求書の依頼で必ず使う」と書いても、Skillが選ばれる前はその本文を判断材料にできない。
だからdescriptionには次の2点が必要になる。
- what: Skillが何を作る、調べる、変換するのか
- when: どの依頼、ファイル、状況で使うのか
公式ベストプラクティスは、descriptionを具体的にし、whatとwhenを含め、第三人称で書くよう案内している2。
現在の仕様¶
最小のSKILL.mdは次の形になる。
---
name: invoice-review
description: Reviews invoice PDFs for totals, dates, vendor details, and missing fields. Use when the user asks to validate, compare, or summarize an invoice before approval.
---
# Invoice Review
## Workflow
1. Confirm the target file.
2. Extract required fields.
3. Recalculate totals.
4. Report discrepancies with page references.
frontmatterの必須条件は次の通りだ1。
| フィールド | 必須条件 |
|---|---|
name | 64文字以下、小文字英数字とハイフンだけ、XMLタグ禁止、予約語anthropicとclaudeを含めない |
description | 非空、1024文字以下、XMLタグ禁止、whatとwhenを含める |
本文は500行未満が推奨される。長くなる場合は詳細をreferences/へ分け、必要な時だけ読む2。
whatとwhenを具体化する¶
悪い例：能力だけを書く¶
description: Helps with documents.
何をするSkillか、どの文書か、いつ選ぶかを区別できない。
改善例：成果物と利用場面を書く¶
description: Creates and revises product requirement documents with goals, scope, acceptance criteria, risks, and open questions. Use when the user asks to draft, review, or update a PRD or feature specification.
この例は次を含む。
- 動作: creates / revises
- 対象: product requirement documents
- 出力の特徴: goals、scope、acceptance criteriaなど
- 発火場面: draft、review、update、PRD、feature specification
単にキーワードを並べるのではなく、依頼の意図と成果物の形を説明する。
境界が重なるSkillを分ける¶
発火率を上げようとしてdescriptionを広げすぎると、誤発火が増える。
# 広すぎる
description: Analyzes data and creates reports. Use for files, metrics, business questions, or analysis.
データ品質検査、統計分析、KPIレポートの3つのSkillがあるなら、責任を分ける。
# data-quality
description: Profiles tabular datasets for missing values, duplicate keys, schema drift, and invalid ranges. Use before analysis when the user asks to assess whether CSV, Excel, or database extracts are trustworthy.
# statistical-analysis
description: Performs statistical tests, estimates uncertainty, and explains model assumptions. Use when the user asks whether an observed difference or relationship is statistically supported.
# kpi-reporting
description: Produces recurring KPI reports from validated metric tables, including target variance and period-over-period change. Use when the user asks for a weekly, monthly, or quarterly performance report.
3つとも「data」を扱うが、入力状態、問い、成果物が違う。発火しない時だけでなく、別Skillが選ばれる時もdescription同士を比較する。
否定条件は補助として使う¶
旧来のパターンではdo-notを常に入れる方法が紹介されることがある。しかしAnthropicの必須仕様はwhatとwhenであり、否定条件は必須ではない。
境界が明確なら、肯定条件だけの方が短く保てる。誤発火が評価で確認された場合だけ、境界を1文加える。
description: Reviews completed pull-request diffs for correctness, regressions, and missing tests. Use after code changes exist and the user asks for review. Do not use for implementing the change itself.
否定語を大量に並べると、本来使う依頼まで除外しやすい。実際の誤発火ケースを根拠に追加する。
日本語の依頼へ対応する¶
descriptionを英語で書いても、日本語の意味をモデルが対応付ける場合はある。ただし特定の言い換えや音声入力の誤変換まで保証される仕様ではない。
日本語利用が中心なら、評価ケースに実際の表現を入れる。
発火すべき:
- このPDF請求書の合計を確認して
- 請求元と支払期限を一覧にして
- インボイスの税額が合うか見て
発火すべきでない:
- 新しい請求書テンプレートをデザインして
- 取引先へ支払い延期のメールを書いて
- PDFを画像へ変換して
音声入力で「仕様書」が「使用書」になるような誤変換は、descriptionへ無制限に列挙しない。頻出する実データだけを評価へ追加し、必要なら自然な同義語を1つ加える。
評価ケースで直す¶
最低限、次の3群を用意する。
| 種類 | 目的 |
|---|---|
| should trigger | 明示的な典型依頼で選ばれるか |
| paraphrase | キーワードがなくても同じ意図を拾えるか |
| should not trigger | 似ているが別責任の依頼を避けるか |
例をJSONLなどで固定する。
{"input":"この請求書の合計と税額を確認して","expected":true,"case":"direct"}
{"input":"支払前に金額のつじつまを見て","expected":true,"case":"paraphrase"}
{"input":"請求書テンプレートを新しく作って","expected":false,"case":"neighbor"}
{"input":"PDFをPNGへ変換して","expected":false,"case":"unrelated"}
公式チェックリストは、少なくとも3つの評価を作り、利用予定のモデルで試すことを勧めている2。モデル変更でルーティングも変わり得るため、1回通った文面を永久に正解としない。
改善の順番¶
- frontmatterの構文と必須条件を検証する
- whatを具体的な動詞・対象・成果物で書く
- whenへ実際の依頼とファイル種別を入れる
- 競合Skillのdescriptionを並べ、責任の重なりを削る
- should / paraphrase / should-notを実行する
- 確認できた失敗だけを1回に1点修正する
- Skill本文が500行を超えるなら詳細を分離する
複数の変更を一度に入れると、何が効いたか分からない。descriptionの変更履歴と評価結果を一緒に残す。
発火後の失敗も分けて考える¶
Skillが選ばれたのに結果が悪い場合、descriptionを直しても解決しない。
- 手順の順序が曖昧なら本文を直す
- 入力ファイルが必要なら先に存在確認を入れる
- 再利用するコードは
scripts/へ移す - 詳細資料は
references/へ置き、本文から読む条件を書く - 外部コマンドの失敗時に、停止条件と代替経路を書く
descriptionは入口、本文は実行契約だ。別々に評価する。
セキュリティ¶
Skillsは説明文だけでなく、スクリプトやツール実行を含められる。Anthropicは、信頼できる作成者または公式提供元のSkillだけを使うよう注意している1。
第三者Skillでは次を確認する。
SKILL.mdが追加で読むファイルscripts/が実行するコマンドと外部通信- 認証情報、ホームディレクトリ、Git設定へのアクセス
- 自動承認や破壊的操作の有無
発火精度を上げることと、実行権限を広げることは別の判断だ。
まとめ¶
Skillが発火しない時は、descriptionだけを疑う前に、発見、YAML、ルーティング、実行のどこで止まるかを切り分ける。
descriptionで守る核は3つだ。
- 何をするかを具体的に書く
- いつ使うかを実際の依頼で書く
- 競合Skillとの境界を評価で確認する
必須仕様を満たし、should triggerとshould not triggerを固定すれば、文面を勘で調整する状態から抜けられる。