SKILL.md の description を書き間違えると、スキルは永遠に呼ばれない

• URL: https://zenn.dev/playpark/articles/skill-md-guide
• 日付: 2026-06-11
• Tier: Tier 3
• 要旨: Claude Code Skillsでスキルが呼ばれない原因のほとんどがdescriptionフィールドの書き方にあることを自身の失敗事例から解説。descriptionは「機能説明」ではなく「ユーザーがどう頼むかの自然文」として書くべきという実践知。

詳細

descriptionの役割：Claude Codeはセッション起動時に全SKILL.mdのdescriptionだけをメモリに読み込み、ユーザー発話と意味的に近いものを選ぶ。つまりdescriptionは「検索クエリ」として機能する。

失敗例と成功例：

# Bad（機能説明のみ）
description: 'Improve SEO of blog articles'

# Good（ユーザー発話が自然文で入っている）
description: 'GSC/GAデータに基づいてtitle/description/冒頭セクションを改善する。ユーザーが「SEO改善」「CTR改善」と依頼したとき'

description3点チェックリスト：

1. 動詞で始める（抽出して、分析する）
2. 対象オブジェクトを明示する
3. ユーザーがどう頼むかを自然文で書く（「〜と言ったとき」）

競合対策：否定条件を書き添える（「2記事の交換には使わない」等）が有効。競合が顕在化してから追記するでよい。

アンチパターン：Claudeが「メモリに保存しておきました」と返したら対症療法。スキル本体のdescriptionを修正するのが根本解決。メモリに救済ルールが溜まるのはスキル設計のバグが蓄積しているサイン。