【Claude Skills】公式ガイドで分かったdescription設計のコツ

お疲れ様です。みんみんです。

先日、AnthropicがClaude用の「Skills」に関する公式ガイド『The Complete Guide to Building Skills for Claude』を公開していたので読んでみました。
自分でも普段の業務用にSkillをいくつか作って運用しているんですが、その多くは感覚と経験だけで組んでいた部分もあったので、公式の設計思想と自分のやり方がどれくらい合っているか、答え合わせのつもりで読み込んでみた次第です。

読んでみると、特にdescriptionのトリガー設計とProgressive Disclosureの考え方は、自分が感覚でやっていた部分にちゃんと理屈がついた感じがして、思っていたより収穫が多かったです。
今回はガイドの内容と、自分で追加で調べた実例を合わせて整理します。

Skillとは何か

ガイドの冒頭では、Skillは「フォルダとしてパッケージされた、Claudeに特定のタスクやワークフローの扱い方を教える指示のセット」と定義されています。
毎回の会話で好みやプロセス、専門知識を説明し直す代わりに、一度教えれば毎回それを活かせる、という発想です。

Skillの基本構造

技術的な構造はシンプルです。Skillは以下のファイルを含むフォルダです。

• SKILL.md（必須）：YAMLフロントマター付きのMarkdown指示
• scripts/（任意）：実行可能なコード（Python、Bashなど）
• references/（任意）：必要に応じて読み込まれるドキュメント
• assets/（任意）：出力に使うテンプレート、フォント、アイコンなど

Progressive Disclosure（段階的開示）という考え方

Skillの設計で核となるのが、この3段階のロード方式です。

• 第1レベル（YAMLフロントマター）：常にシステムプロンプトにロードされる。どのSkillをいつ使うべきか、Claudeが判断するための最小限の情報
• 第2レベル（SKILL.mdの本文）：Claudeがそのタスクに関連すると判断したときにロードされる。完全な指示とガイダンス
• 第3レベル（リンクされたファイル）：Claudeが必要に応じて自分でナビゲートして参照する追加ファイル

これによってトークン消費を抑えながら、必要な専門知識を維持できる仕組みになっています。
「全部を一気に読み込ませない」という、地味だけど効いてくる設計です。

もう1つ、Anthropicのエンジニアリングブログ「Equipping agents for the real world with Agent Skills」で技術的に面白かったのが、scripts/内のコードが実行されたとき、コードそのものはトークンストリームに一切入らず、実行結果だけがClaudeに渡されるという点です。
判定ロジックを自然言語の指示で書くかスクリプトで書くかは、トークン消費だけでなく確実性にも直結します。「Code is deterministic; language interpretation isn’t」とガイドでも念押しされていて、クリティカルな検証はスクリプト側に持たせるのが定石のようです。

設計のはじめ方：ユースケースを先に決める

コードを書く前に、そのSkillが実現すべき具体的なユースケースを2〜3個特定する。
ガイドで繰り返し強調されていたのがこの点です。

良いユースケース定義には以下が含まれます。

• ユーザーが何を達成したいか
• そのために必要なマルチステップのワークフロー
• 必要なツール（組み込み機能かMCPか）
• 組み込むべきドメイン知識やベストプラクティス

Anthropicが観測した、Skillのユースケースは大きく3カテゴリに分かれるようです。

YAMLフロントマターの書き方が命

ここが一番「なるほど」と思った部分でした。
YAMLフロントマターは、Claudeがそのスキルをロードするかどうかを判断する唯一の材料になります。ここを適当に書くと、そもそもSkillが起動しません。

最小構成はこれだけです。

---
name: your-skill-name
description: What it does. Use when user asks to [specific phrases].
---

• ※nameはkebab-case限定。スペースや大文字は不可
• ※descriptionは「何をするか」と「いつ使うか（トリガー条件）」の両方を必ず含める
• ※1024文字以内、XMLタグ（< >）は使用不可

良い例・悪い例が対比されていたのでそのまま紹介します。

良い例：「Figmaデザインファイルを解析し、開発者向けハンドオフドキュメントを生成する。ユーザーが.figファイルをアップロードしたとき、または『design handoff』『component documentation』と言ったときに使用」

悪い例：「プロジェクトを手伝います」（trigger条件がなく、汎用的すぎる）

「何をするか」だけ書いて「いつ使うか」を省略すると、Claudeがそのスキルの存在に気づけない。
逆に条件を書きすぎると誤起動する。この匙加減がSkill設計の肝だと感じました。

テストと改善のサイクル

Skillを作って終わりではなく、ガイドでは3つの観点でのテストが推奨されています。

• トリガーテスト：想定通りの場面で起動するか。言い換えた質問でも起動するか、無関係な話題では起動しないか
• 機能テスト：正しい出力が生成されるか。API呼び出しが成功するか、エラー処理・エッジケースが機能するか
• 性能比較：Skillあり／なしでの差を比較。往復メッセージ数、失敗したAPI呼び出し数、消費トークン数など

ここで面白かったのが「1つの難しいタスクにひたすら向き合う」というアプローチです。
広く浅くテストケースを増やすより、Claudeが成功するまで1つのタスクで反復し、その成功パターンをSkillとして抽出する方が、速く確実な結果につながるとのことでした。
土台ができてから、テストケースを横に広げていく流れです。

また、Anthropicはskill-creatorというSkillを公式で提供していて、自然言語の説明からSKILL.mdを生成したり、既存Skillのレビューをしてくれるそうです。
自分でSkillを作るなら、まずこれを使ってみるのが早そうです。

配布方法

個人利用の場合、Skillフォルダをダウンロード → 必要ならzip化 → Claude.aiの「設定 > Capabilities > Skills」からアップロード、という流れです。
組織単位でのワークスペース全体へのデプロイも2025年12月にリリースされていて、管理者が一括で配布・自動更新できるようになっています。

もう一点、Anthropicは「Agent Skills」というオープン標準も公開しています。
MCPと同じ発想で、Skillも特定のツールに縛られず、プラットフォームをまたいで動くべきという考え方です。

よくあるパターンとトラブルシューティング

ガイドの後半では、実際に作られたSkillから見えてきた5つの設計パターンが紹介されていました。

• ①逐次ワークフロー：決まった順序のマルチステップ処理
• ②複数MCPの連携：複数サービスをまたぐワークフロー
• ③反復的な改善：品質チェック→修正を繰り返して出力を改善
• ④文脈に応じたツール選択：状況によって使うツールを切り替える
• ⑤ドメイン特化の知能：専門知識やコンプライアンスをロジックに埋め込む

実例として、Sentryが公開しているsentry-pr-code-reviewは「⑤ドメイン特化の知能」パターンそのものでした。
GitHubのPull Requestで変更された関数のdownstream caller数を調べて影響範囲を測り、1〜10のスコアを本文の先頭に1つだけ出す設計になっています。判断基準を数値に落とし込んで一言で見せる、という割り切り方が実務的でした。

Anthropic公式のSkillサンプル集はanthropics/skillsで公開されていて、Claude Codeなら/plugin install example-skills@anthropic-agent-skillsでそのままマーケットプレイスとして追加できます。自作する前に近い実例を覗いておくと、description設計の勘所が掴みやすいです。

トラブルシューティングも実用的でした。特に「Skillが起動しない」「起動しすぎる」の対処法が、上のdescriptionの書き方と直結しているのが分かりやすかったです。

起動しない → descriptionが汎用的すぎる。具体的なトリガーフレーズを追加する

起動しすぎる → 「Do NOT use for〜」のようなネガティブトリガーを追加する

まとめ

読んでみて分かったのは、Skillは「プロンプトの保存」ではなく、「Claudeにいつ・どう動くべきかを教える設計物」だということです。
特にYAMLフロントマターのdescriptionの書き方だけで、起動精度がまるで変わってくるのが印象的でした。

まずは自分の業務で繰り返している作業を1つ選んで、小さいSkillを作ってみようと思います。
参考になれば嬉しいです。