Anthropic公式Skill実践ガイド：いかに書き、改善し、有用性を検証するか

Anthropic公式から、Claudeがスムーズに検出し、効率的に呼び出せるSkillを作成するための「Agent Skill作成ベストプラクティスガイド」が公開されています。多くの開発者はSkillを作成し始めた当初、詳細を極めた「業務運用マニュアル」にしてしまいがちです。

あなたも似たような経験があるかもしれません。Claudeがあるタスクの実行で細部を見落としたら、ファイルにすぐルールを1行追加する。次に別の例外ケースを考慮し忘れたら、背景説明をもう1段落追記する。これを繰り返すうちに、メインの説明ファイルは1000行を超え、様々なライブラリの解説、パラメータ一覧、一般的な注意事項で溢れ返ってしまいます。メインファイルが長くなりすぎたからといって、モデルの能力が必然的に低下するわけではありませんが、コンテキストウィンドウは常に限られた共有リソースです。冗長な指示や一般常識をすべて一度に読み込んでしまうと、対話履歴や現在のタスクとアテンションを奪い合うだけでなく、モデルが重要な情報を特定する難易度を上げ、不必要な推論コストを生じさせやすくなります。

公式のベストプラクティスにおける核心的な認識は、「効果的なSkillとは、モデルを常識のない初心者のように手取り足取り教え込むものではなく、特定のシナリオにおいて的を絞った操作ガイドを提供するものである」という点です。

Skillが真に有用かどうかを評価する際、ルールの多さは有用性を直接証明するものではありません。見るべきなのは、「そのSkillがない場合、モデルはどの具体的なタスクで不足や見落としを生じやすいか？」「それらの指示を補足したことで、問題は効果的に解決されたか？」「そして、目標を達成するために十分に簡潔な表現と明確なワークフローを用いているか？」という点です。

ClaudeはいつSkillを読み、いつ資料を調べるのか？

優れたSkillを書くには、まずモデルがファイルを読み込む仕組みを理解する必要があります。

Claudeとのやり取りにおいて、コンテキストウィンドウ（Context Window）は共有リソースです。毎回の対話で、システムプロンプト、チャット履歴、ユーザーの現在の質問、利用可能なすべてのSkillの基本情報が、この限られたアテンション空間を取り合っています。大量の背景情報や実装の詳細を一度にコンテキストへ詰め込むと、往々にして無駄な空間圧迫を招いてしまいます。

公式によるSkill設計では、段階的開示（Progressive Disclosure）に基づく3層ロード機構が採用されています：

1. 第1層：メタデータの事前ロード（Metadata）
   セッション開始時、ClaudeはSkill本文を読み込まず、インストールされているすべてのSkillの先頭にある名前（name）と説明（description）のみをシステムプロンプトにあらかじめ注入します。この時点でモデルが把握しているのは、スキルのグローバルなインデックス一覧です。
   
2. 第2層：メインファイルのオンデマンドトリガー（SKILL.md）
   ユーザーの質問がいずれかのSkillの説明に合致したときのみ、Claudeはファイル読み込み指示を通じてメインファイル SKILL.md をロードします。タスクが基本的な操作にとどまる場合、モデルは本文のみを参照して実行します。
   
3. 第3層：必要に応じた参考資料の読み込み（Reference Files & Scripts）
   タスクがさらに深い業務ルール、完全なAPI仕様、または特定のワークフローを処理する必要がある場合、Claudeはメインファイル内のリンクをたどってサブドキュメントを読み込むか、同梱されたスクリプトを直接呼び出します。

これがSkillファイルの核心構造を決定づけています。「メインファイルは簡潔な要約にとどめ、主にクイックリファレンスと目次ジャンプの役割を果たし、必要になったタイミングでモデルを必要な詳しい知識へと誘導する」べきなのです。

ヘッダーのメタデータを書く際、実践上重要な2つの詳細があります：

• 名前（name）の仕様要件：長さは64文字以内で、小文字・数字・ハイフンのみ使用可能（例: pdf-processing）であり、XMLタグや予約語（anthropic、claudeなど）を含めることはできません。公式の模式図に大文字や空白が見られる場合があっても、それは単なる構造の概念図であり、実際の実装では純粋な小文字とハイフンによる標準的な命名規則に従う必要があります。
• 説明（description）は客観的な三人称でトリガー条件を明確に記述することを推奨：説明の上限は1024文字で、空にしてはならず、XMLタグを含めないこと。Claudeは起動時、主にこの説明を頼りに多数の候補Skillの中から選別とルーティングを行います。「このツールを使ってExcelを処理できます」や「私がドキュメント整理を手伝います」のように記述すると、システムプロンプトに注入された後に人称視点の不一致が生じやすくなります。より手堅い方法は、客観的な三人称を採用し、トリガーとなるシナリオとキーワードを明確に列挙することです。例えば、「PDFのテキストと表を抽出し、フォームに入力してドキュメントを結合します。PDFファイルを処理する場合、またはユーザーがPDF、フォーム、ドキュメント抽出に言及した場合に使用します。」のように記述します。

財務データを調べるときは、財務資料のみを読む

良好な実行パフォーマンスを維持するために、公式は SKILL.md メインドキュメントの本文を500行以内に抑えることを推奨しています。これは保守性と集中度を高めるためのベストプラクティスとしての推奨であり、プラットフォームによる技術的な強制上限ではありません。内容がこの規模に近づく、あるいは超える場合は、独立した参照ファイルへと分割する方が適しています。

ファイルの分割方法として、公式は「1階層のみの参照（One level deep）」を推奨しています。すべての第2階層の参照ドキュメントは、できる限りメインファイル SKILL.md から直接リンクし、何重もの深いネストを避けるという考え方です。

なぜ深いネストを避けることが推奨されるのでしょうか？ もしドキュメント構造が SKILL.md から advanced.md を参照し、さらに advanced.md の内部から details.md を指している場合、Claudeは深くネストされたファイルに対して、ファイル全体を完全に読み込まず head -100 のようなコマンドで部分的なプレビューのみを行う可能性があり、その結果得られる情報が不完全になる恐れがあります。1階層の直接参照は、必要なときに対象コンテンツをより完全に読み込むようモデルを誘導するのに役立ちます。ただし、1階層の参照自体も組織化のための推奨事項にすぎず、モデルが毎回必ず全文を読むことを絶対的に保証するものではありません。そのため、公式はさらに次のことを推奨しています。100行を超える参照ドキュメントについては、先頭に目次（Table of Contents）を付与し、モデルが部分的な簡易プレビューを行った場合でもファイル全体の全容を把握し、該当セクションへ正確にジャンプできるようにしておくのが望ましいとされています。

適切なアプローチは、領域ごとに分割し、メインファイルから1階層でリンクすることです。例えば、公式が提示しているBigQueryデータ分析の構想例です：

• bigquery-skill/
  • SKILL.md（概要とクイック検索のエントリポイント）
  • reference/finance.md（売上、請求指標）
  • reference/sales.md（商談、顧客ファネル）
  • reference/product.md（API呼び出し量、機能利用統計）

ユーザーが「売上指標はどのように計算するか」と質問した場合、Claudeはまずメインファイルを参照し、財務指標の理解だけで十分だと判断すると、reference/finance.md のみを読み込みます。このとき、実際に読み込まれた財務ドキュメントの内容のみがコンテキストに加算され、まだ読まれていない営業や製品のドキュメントはファイルシステム上に残ったままで、コンテキストコストを発生させません。この方法により、必要に応じて詳細な専門知識を提供しつつ、無駄なコンテキストの消費を抑えることができます。

複数のファイル構成を整えた後は、実際の対話におけるモデルのアクセスパスを観察し、構造の分割が妥当であるかを検証する必要があります：

• 重要なリンクを見落としていないか：モデルがメインドキュメントから関連する参照ファイルをたどっていない場合、通常はエントリポイントの位置が目立たないか、誘導の記述が不明瞭であることを示唆しています。
• 同一の資料を繰り返し読み込んでいないか：特定の参照ドキュメントが複数の対話で頻繁に再読されている場合、その部分が高頻度で使われる共通知識である可能性があり、メインファイルへ移して統合することを検討する価値があります。
• 特定のファイルをまったく開いていないか：ある付属ドキュメントが一度も読み込まれない場合、その資料が現在の業務シナリオには不要であるか、メインドキュメントに十分明確なトリガーの手がかりが欠けている可能性があります。 調整を行ったうえで同種のタスクを再実行し、モデルが必要な資料を見つけられたか、タスクの結果が改善したかを観察します。

繰り返される確定的操作は、スクリプトを用意して呼び出す

多くのタスクにおいて、Claudeにその場でコードを書かせて実行させるテキスト指示を書くこともできれば、Skillディレクトリに作成済みのスクリプトを同梱しておくこともできます。両者をどのように使い分けるべきでしょうか？

公式が提示するアドバイスは、「手順が確定しており、エラーが発生しやすい操作については、モデルに毎回コードをその場で書かせるのではなく、事前作成された実用スクリプトを優先して提供し、モデルから直接呼び出して実行させる」というものです。

事前作成された実用スクリプトの活用には、多くの利点があります：

1. コンテキストと生成時間の節約：モデルがターミナルでコマンドを実行する場合（例: フォームフィールドの抽出: python scripts/analyze_form.py input.pdf > fields.json）、通常はスクリプトが出力した結果を受け取るだけで済み、毎回コードを再生成する必要も、スクリプトのソースコード全文をコンテキストに読み込む必要もありません。ただし、これはモデルにソースコードを絶対に読ませないという意味ではありません。公式はドキュメント内で指示の意図を区別すべきであると指摘しています。大半の定型ツールは「実行」を主目的としますが、スクリプトに重要なアルゴリズムのロジックが含まれている場合は、モデルに対して「参考として読む」よう明確に指示することも可能です。
2. モデルに丸投げせず、能動的に問題を解決する（Solve, don't defer）：スクリプトを作成する際は、エラーを明示的に処理し、明瞭なエラー情報を提供する必要があります。公式ドキュメントでは「ファイルが存在しない場合にデフォルトの空ファイルを作成するか、代替案を提供する」というコード例が挙げられていましたが、これは防御的処理の考え方を示す具体的なユースケースにすぎず、すべての業務シナリオでデフォルトファイルの自動作成が適しているわけではありません。核心となる要件は、スクリプト自体が明確なエラー処理とトラブルシューティング情報を備え、理解しにくいネイティブの例外をそのままスローしてモデルに推測させる事態を避けることにあります。
3. 根拠のない定数（Voodoo Constants）の排除：スクリプトに設定する重要なパラメータには、明確なコメントと根拠を付与すべきです。例えばタイムアウトを30秒、リトライ回数を3回に設定する場合、「通常のHTTPリクエストは通常30秒以内に返り、3回のリトライは応答効率と偶発的なネットワークの揺らぎの両方を考慮したものである」と注記し、根拠のないマジックナンバーを安易に設定することを避けます。
4. 実行環境と依存関係の要件を明記する：一般的な常識（例: PDFフォーマットとは何かという解説）は確かに簡素化すべきですが、実行に必要な具体的な依存パッケージや環境の制限事項は明示的に宣言しなければなりません。使用するプラットフォームがネットワークに接続できるか、実行時に依存関係をインストールできるかは、実際のコード実行環境に応じて確認する必要があります。そのため、必要な依存関係（例: pypdf 依存関係や適切なインストール方法の記載）をドキュメント内に明記し、対応する環境で事前準備できるようにしておくことが不可欠です。
5. デフォルトの経路と明確な例外を示し、選択肢を羅列しすぎない：公式は、モデルに対して選択可能なライブラリをずらりと羅列すべきではないと指摘しています（例: pypdf、pdfplumber、PyMuPDF、pdf2image を同時に並べてモデル自身に判断させるなど）。より明快な方法は、デフォルトのルートを提供し、例外が発生するトリガー条件を明記することです。通常のテキスト抽出にはデフォルトで pdfplumber の使用を推奨し、スキャンされたPDFでOCR処理が必要な場合には、例外として pdf2image と pytesseract の組み合わせを指定します。デフォルトルートによってモデルは何を最初に使うべきかを把握し、例外条件によっていつ手法を切り替えるべきかを理解できます。

コードレビューには判断の余地を残し、DBマイグレーションには厳密な手順を書く

あるSkillをどの程度細かく規定すべきでしょうか？肝心なのは、タスク自体の脆弱性と変動性に応じて、適切な自由度（Degrees of Freedom）を適合させることです。

公式は、モデルの探索をロボットの進行経路に例えてわかりやすく説明しています：

• 両側が崖の狭い橋（低自由度）：安全に通行できるルートが1つしかなく、操作が脆弱で極めてエラーを起こしやすいため、厳格で具体的な指示と確定的なスクリプトを提供する必要があります。例えばデータベースのマイグレーション操作では、ドキュメントで固定のコマンド（python scripts/migrate.py --verify --backup）を明確に指定し、コマンドを勝手に変更したり不要なパラメータを追加したりしないよう指示することで、明確な境界を通じてクリティカルなプロセスの整合性を担保します。
• パラメータ化されたパターン（中自由度）：推奨される実装パラダイムは存在するものの、具体的な入力に応じた構成の調整が許容されるケースです。例えば分析レポートの生成では、パラメータ付きの関数テンプレート（例: generate_report(data, format="markdown", include_charts=True)）やレポート構成のサンプルを提供し、実際のデータ形状に応じてモデルが表示の詳細を決定できるようにします。
• 障害物のない開けた草原（高自由度）：目標を達成するための実現可能なアプローチが複数存在し、具体的なコンテキストに応じた判断に依存するケースです。例えばコードレビュー（Code Review）では、テキストリストを用いてレビューの観点（コードアーキテクチャと構造の分析、潜在的なバグとエッジケースの検証、可読性向上の提案、プロジェクトのコーディング規約の確認）を明確にし、モデルがコードの実際の状況に即して総合的に評価できるようにします。

ワークフローの設計において、このような自由度の区分は条件分岐と組み合わせて使用されることがよくあります。例えば公式が提示しているDOCXドキュメント処理の事例では、「新規作成」と「既存ドキュメントの修正」という2つのパスが明確に区別されています。ドキュメントをゼロから新規作成する場合は専用ライブラリ（docx-jsなど）を用いて完全に構築しますが、既存ドキュメントの単純な修正では、わざわざ全面的な再構築プロセスを踏むのではなく、直接解凍して下層の word/document.xml を修正し、修正直後にバリデーションスクリプトを実行して変更後のドキュメント構造をチェックし、整合性を確認したうえで再パッケージングしてテストします。この2つのパスを分けることで、単純な修正シナリオにおいて非効率的で既存フォーマットを壊しやすい全面再構築に陥るのを防ぐことができます。

出力形式についても、用途に応じてどの程度厳格に規定するかを決める必要があります。出力がプログラムによって処理される場合（例: 固定構造のAPIレスポンス）、下流側がどこからデータを取得すべきか把握できるようテンプレートを明確にすべきです。一方、分析レポートの章立てが発見事項に応じて変化する必要がある場合は、デフォルトの構成を示したうえで、どの部分が調整可能であるかを説明します。フォーマットを固定するかどうかは、後続でそれがどのように利用されるかによって決まります。

文体や詳細の度合いを伝えるには、入力と出力のペアの例も非常に有用です。公式のGitコミットメッセージの事例では、次のように示されています：

入力：Added user authentication with JWT tokens

出力：

feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware

この例は、タイトルに type(scope): brief description を採用し、本文に具体的な変更内容を補足する書き方を同時に提示しています。単に「コミットメッセージは簡潔かつ標準的に記述すること」と伝えるよりも、どのような出力が要件を満たすのかをモデルが理解しやすくなります。

50箇所のPDFフィールド入力：まず計画を検証し、書き込み後に完成品を検査する

大量の一括変更や不可逆な修正を伴うシナリオにおいて、モデルに対象ファイルを直接修正させると、フィールドの取り違え、フォーマットの上書き、実行の中断といった問題が発生しやすくなります。公式はここで1つの想定シナリオを提示しています。表データに基づいてPDFフォーム内の50箇所のフィールドを更新する必要がある場合、モデルに検証ステップがないと、存在しないフィールドを参照したり、矛盾する値を入力したり、必須項目を見落としたりしがちです。

こうしたタスクに対し、公式は「計画 — 検証 — 実行」（Plan → Validate → Execute）のワークフローパターンを採用し、プロセス全体を明確な閉ループに分解することを推奨しています：

1. 原本の分析と視覚補助（Analyze & Visual analysis）：分析ツールを実行してフォームフィールドと対応する位置を抽出し、構造化された記述ファイルを出力します（例: python scripts/analyze_form.py input.pdf で fields.json を生成）。レイアウトが複雑な場合、公式は視覚的な分析の導入も推奨しています。python scripts/pdf_to_images.py form.pdf を記述・実行してPDFページを画像としてレンダリングし、各ページ画像におけるフィールドの実際の位置、タイプ、ページ全体のレイアウトをモデルに直接観察させます。変換スクリプトは自前で用意する必要があります。ページ画像を見ることは「フィールドがどこにあり、ページがどのような見た目か」を理解するのに役立ち、構造化された検証は明確なルールに従ってフィールドマッピングや衝突をチェックするため、両者を組み合わせて活用します。
2. 計画の生成（Create plan）：入力データに基づいてモデルにマッピングを行わせ、独立した計画ファイルを生成させます（例: fields.json の編集や changes.json の生成）。元ファイルに実際に手を加える前に、すべてのマッピングと修正は計画ファイル内で行われるため、低いコストで繰り返し調整と修正が可能です。
3. 計画の検証（Validate plan）：専用の検証スクリプトを実行して計画ファイルを検査します（例: python scripts/validate_fields.py fields.json）。ここでの計画検証は、書き込もうとしているフィールドマッピングと変更ロジックが正当であるかの検証に焦点を当てます。例えば、存在しないフィールドの参照、値の衝突、必須項目の欠落がないかを確認します（公式の別の例では、validate_boxes.py がバウンディングボックスの重複検出に使用されています）。問題が検出された場合、スクリプトは具体的なエラーメッセージを出力すべきです（例: 「signature_date フィールドが見つかりません。現在利用可能なフィールド: customer_name, order_total, signature_date_signed」）。
4. エラー修正とリトライ（Fix errors）：モデルは具体的な検証フィードバックに基づいて計画ファイルを直接修正し、再度検証を実行して修正の閉ループを形成します。
5. 正式な実行（Execute）：計画の検証が完全にパスした後にのみ、実行スクリプトを呼び出して対象ドキュメントへ実際に修正を書き込みます（例: python scripts/fill_form.py input.pdf fields.json output.pdf）。
6. 最終生成物の検証（Verify output）：実行後に結果が必ず正しいと思い込んではならず、完成品検証スクリプト（例: python scripts/verify_output.py output.pdf）を実行して、実際に書き込まれた最終ドキュメントを検証する必要があります。完成品の検証に失敗した場合は、計画段階へとフォールバックして原因究明と修正を行います。

これらのスクリプト名は各ステップの責務を説明するためのものです。実際に運用する際は、自身のフォームに合わせたスクリプトを用意または実装する必要があります。ドキュメント内の異なるサンプルをそのまま繋ぎ合わせても、完全なインストールパッケージになるわけではありません。

中間の計画ファイルを導入する価値は、揺らぎやすい生成プロセスを、プログラムによって機械的に照合可能な中間状態へと変換できる点にあります。計画検証は書き込もうとしているフィールドマッピングと変更内容をチェックし、完成品検証は実際に書き込まれた後の最終結果をチェックします。元ファイルに手が加えられていない状態であれば、計画は何度でも修正可能です。

この「検証 → 修正 → 繰り返し」というフィードバックループは、スクリプトを作成するコードタスクにとどまらず、プレーンテキストや非コードのタスクにおいてもアウトプットの品質を高める中核的な設計となります：

• リサーチまとめのワークフロー：公式が提示するノーコードの分析事例では、リサーチプロセスを「全ソースドキュメントの精読」「コアテーマの特定」「論拠のクロスチェック」「構造化サマリーの生成」「引用元の照合」という明確な5ステップに分解しています。最後のステップで引用の不備が見つかった場合、論拠をクロスチェックするステップに戻り、引用元を補ってから再検査します。
• ライティング規約のチェック：コンテンツ執筆シナリオでは、参照ドキュメント（例: STYLE_GUIDE.md）を「バリデータ」として位置づけ、モデルにドラフト作成後のチェックリストに基づくセルフチェックを義務付けます。専門用語の統一性、サンプルの標準フォーマット準拠、必須セクションの網羅性を確認させます。不適合な箇所が見つかった場合は該当セクションを特定して1つずつ修正し、修正後に再度チェックリストと照合して、すべてを満たした段階で完成とします。 スクリプトがない場合でも、検査基準を明確に記述し、項目ごとの修正と再チェックを義務付けることは可能です。モデルが規約に照らしてチェックする場合はテキストの意味判断を必要としますが、プログラムによる検証は事前設定されたルールに従ってフィールドや構造を機械的に照合するため、両者が検知できるエラーの種類は異なります。

新しいセッションに切り替え、Skillが単独でタスクを完遂できるか確認する

Skillの作成と最適化にあたり、公式は評価駆動（Build evaluations first）を特に重視しており、実際の課題に根ざしていない説明を根拠なく大量に書き連ねることを避けるよう求めています。

作成直後の現在の対話内でモデルにテストさせると、それまでのやり取りで注入された背景コンテキストの影響を受けやすく、Skill自体の独立した誘導効果を正確に測定することが困難になります。そのため公式は、2つの異なる役割を通じてイテレーションを構成することを推奨しています。作成と設計を支援する「Claude A」と、独立した新しいセッションでテストを実行する「Claude B」です。テストにあたってアカウントを切り替えたり物理的な環境を再起動したりする必要はなく、前回の対話の影響を受けないクリーンな新規セッションウィンドウ（Fresh instance）を立ち上げるだけで十分です。

コアとなるフローは、シンプルなプロセスとしてまとめることができます：
実タスクの欠落の発見とベースライン構築 → Claude A の支援による Skill の起草とスリム化 → 新規セッションにおける Claude B による実測 → 実行の乖離を収集し Claude A にフィードバックして改善・調整

反復プロセス全体は、以下の主要なステップに分けることができます：

1. タスクのギャップを発見し、評価ベースラインを構築する

長文のドキュメントを書き始める前に、代表的なタスクを実行し、Skillがない状態でのモデルの具体的な挙動を観察します。どのステップでギャップが生じるかを記録します。例えば、特定のデータベーステーブル名を知らない、フィルタ条件を落としている、不適切な処理ツールを使用しているといった点です。これらの具体的なギャップに基づき、初期評価ベースラインとして少なくとも3つのテストシナリオを構築します。

期待値を明確にするため、公式は構造化された評価データのサンプル（入力と期待される振る舞いをJSON形式で定義したもの）を提示しています：

{
  "skills": ["pdf-processing"],
  "query": "Extract all text from this PDF file and save it to output.txt",
  "files": ["test-files/document.pdf"],
  "expected_behavior": [
    "Successfully reads the PDF file using an appropriate PDF processing library or command-line tool",
    "Extracts text content from all pages in the document without missing any pages",
    "Saves the extracted text to a file named output.txt in a clear, readable format"
  ]
}

この評価の完了基準は具体的です。全ページを読み込み、抽出結果を output.txt として保存することです。これらの基準は実際のファイルを通じて照合する必要があります。ドキュメントが提供しているのはテストケースの記述方法であり、組み込みのテストランナーが付属しているわけではないため、実行と検証は自前で設定する必要があります。

2. Claude Aに初稿を作成させ、内容をスリム化する

実際の対話で典型的なタスクを完了させた後、再利用価値のある背景知識（特定のテーブル名、フィールドの定義やルールなど）を整理します。その後、Claude Aの支援を得て規範的な SKILL.md へとまとめ上げます。Claudeモデル自身がSkillのフォーマット要件を十分に理解できるため、追加のメタプロンプトは不要です。

スリム化の作業は評価と密接に結びつける必要があります。指示を記述する際は、以前に発見された実際のギャップを埋めることにフォーカスし、真のギャップを解決するために必要最小限の指示のみを記述します（Write minimal instructions）。初稿を作成し、モデルが既知の一般的な解説や冗長な説明を削除した後は、以前に構築した既存のテストケースを必ず再実行し、スリム化されたSkillが依然として安定して期待を満たせるかを観察します。例えば「勝率とは何か」といった一般的解説を削除した後、モデルが正しいテーブルとフィルタ条件を用いてレポートを完成できるかを再確認します。重要な挙動に影響がなければ、その解説をメインファイルに残しておく必要はありません。

3. 新規セッションでClaude Bを用いてテストする

新しい空白のセッションに該当のSkillをマウントし、Claude Bに実際の業務タスクを実行させます。Skillの独立した有効性を測定する評価段階にある場合は、モデルがドキュメントのみを頼りに独自に的確な情報を見つけ、ルールに従えるかを観察するため、場外からの人手によるリアルタイムの追加プロンプトは極力控えることが推奨されます。もっとも、日常の実プロダクトにおける協働作業において、必要な人間の介入を行うことは当然ながら正常な運用です。

公式が言及しているBigQueryの分析例を挙げると、A/Bのイテレーションプロセスは非常に具体的です：

• 最初のデータ探索において、作成者はClaude Aに対話を重ねながら分析を進めさせ、コア資産を抽出しました。データセットのテーブル名、フィールド定義、クエリパターン、そして「テストアカウントを必ず除外する」という業務ルールです。
• Claude Aはこれに基づいてSkillを起草し、詳細なテーブル定義を reference/ 配下のファイルへと分割しました。
• 続いて新規セッションにおいて、Claude BにそのSkillを使用させて「地域別売上レポート」を生成させました。このチュートリアル用の教育サンプルにおいて、Claude Bはクエリコードを書くことはできたものの、特定のシナリオでテストアカウントを除外するルールを依然として見落としてしまいました。
• 作成者はこの具体的な挙動の乖離を記録し、Claude Aへと持ち帰って改善策を議論しました。「Claude Bが地域別レポートを生成する際、テストアカウントの除外を見落としました。このルールが目立っていないからでしょうか？表現をより明確なトーンの『MUST filter』に変更すべきでしょうか、それとも配置場所を調整すべきでしょうか？」
• 観察結果に基づいてSkillを修正した後、別の新しいセッションで同様のタスクを実行させ、フィルタ条件が確実に適用されているかを確認します。

テストアカウントの除外が見落とされた場合、まずモデルがどのステップで逸脱したかを確認し、その上でどこを修正するかを決定します。トリガー、ナビゲーション、イテレーションに関する公式のアドバイスを整理・統合すると、本稿の解説として以下のような切り分け手順を組み立てることができます：

• Skillがまったくトリガーされない場合：メタデータ内の description を優先して見直します。キーワードがタスクの表現をカバーしているか、トリガー条件が明確か、三人称視点に従っているかを確認します。
• トリガーされたが重要資料の読み込みを見落としている場合：メインドキュメント SKILL.md のナビゲーションとファイル構造を見直します。重要な参照ドキュメントが1階層の直接リンクになっているか、リンクの説明や誘導が十分に目立っているかを確認します。
• 資料は読み込まれたがルールが見落とされている場合：重要ルールがドキュメントの前方に配置されているか、言い回しが明確か、あるいは暗黙のルールをより明示的な順序立てられたワークフローやチェックリスト（Checklist）へと再構成する必要がないかを見直します。
• 実行はスムーズだが最終成果物に誤りがある場合：事前に入力されたデータ、ツール自身のエラー処理機構、中間計画の検証や成果物の検査ステップが欠落していないかを見直します。

4. 異なるモデルに応じた個別テストの実施

注意すべき点として、初期の3つのベースラインシナリオでテストに合格したからといって、あらゆるオープンなシナリオで汎用的にエラーがないことが絶対的に保証されるわけではなく、実際の業務シナリオに照らし合わせた継続的な観察が必要です。また、Skillの実際の効果は基盤となるモデルに大きく依存するため、利用を想定しているすべての対象モデルで個別にテストを実施する必要があります：

• Claude Haiku（軽量・経済的）：Skillが提供する操作ガイドが十分に詳細かつ明確であるかを検証する必要があります。
• Claude Sonnet（バランス型）：指示が十分に明瞭であり、効率的に動作するかを検証します。
• Claude Opus（ディープな推論）：プロンプトの冗長化を避けるため、ドキュメントが過度な説明を排して簡潔にまとまっているかを検証します。

指示の詳細度に対する感度はモデルによって異なるため、単一モデルでのテスト合格のみをもって、すべてのモデルで同様の効果が得られると判断することはできません。

実装への提言：いつでも使えるSkillセルフチェックリスト

公式ガイドのチェックリストに基づき、Skillを納品または最適化する際は、以下の各ポイントと照らし合わせて迅速なセルフチェックを行うことができます：

• メタデータ仕様：name は64文字以内に抑え、小文字、数字、ハイフンのみを使用しているか。description は客観的な三人称を採用し、Skillの機能を明記した上で、具体的なトリガー条件とキーワードを含めているか。
• メインファイルのサイズとコンテンツ階層：SKILL.md 本文は500行以内を目安とし、冗長な一般的概念の解説を避けているか。付属ファイル名は具体的に識別可能か（曖昧な doc2.md を避け、form_validation_rules.md などとする）。必要な依存ライブラリのインストール手順と環境制限を宣言しているか（具体的な対応可否は実際のコード実行環境に基づいて確認する）。100行を超える参照ファイルには先頭に目次を付与しているか。
• ファイルパスと参照階層：すべての参照ファイルは、極力メインファイルから1階層で直接リンク（One level deep）しているか。パスの区切りには一貫してスラッシュ / を使用しているか（Windows環境であってもバックスラッシュ \ を避ける）。
• 用語の統一と日付による分岐の回避：ドキュメント全体で用語を統一しているか（例: 「API endpoint」または「field」のいずれかで一貫させ、混用を避ける）。「何年何月以前は旧版、以降は新版を使用」といった陳腐化しやすい日付による分岐ルールを避け、過去の手法を保持する必要がある場合は独立した「過去のパターン」（Old patterns）セクションに切り出して個別に管理しているか。
• ツール呼び出しとMCP仕様：SkillがMCP（Model Context Protocol）ツールの呼び出しを伴う場合、ServerName:tool_name という完全な命名形式（例: 公式サンプルにおける BigQuery:bigquery_schema）を使用しているか。サービス名のプレフィックス欠落によりツールが認識できなくなる事態を防いでいるか。
• スクリプト設計とエラー処理：確実性の高い操作やエラーが発生しやすい操作には事前作成された実用スクリプトを提供し、モデルによる実行を優先させているか。スクリプトはエラーを明示的に処理し、原因究明が容易なフィードバックを返しているか。パラメータ設定には明確で妥当な根拠があり、コメントのないマジックナンバーを残していないか。
• 高リスク・一括操作の防御策：一括修正や構造変更を伴うタスクには、「計画ファイル（JSONなど）＋機械的バリデーション」という中間フィードバックフローを導入し、正式な書き込み後に成果物の検証ステップを設けているか。
• 実測とクロスモデル検証：まずSkillがない状態でのベースライン比較タスクを構築したか。独立した新しいセッションで実際の実行効果をテストしたか。サポート予定のすべての対象モデル（Haiku、Sonnet、Opusなど）でそれぞれ挙動を検証したか。

付録：Skill 改善イテレーション記録テンプレート

以下に、プレーンテキスト形式の「Skill改善記録」テンプレートを提供します。このテンプレートは、公式ベストプラクティスにおける反復テスト手法に基づいて整理されたものであり、読者が日々のSkill開発およびメンテナンスにおいて実際の挙動を記録・再利用するためのものです（使用時はそのままコピーし、実際のテストケースに応じて記入してください）：

              Skill 改善イテレーション記録表
   (注：本テンプレートは公式の評価・改善アプローチに基づき整理された再利用用フォーマットです)


【テストタスク】：
（例：前四半期の地域別売上レポートを生成し、各地域の契約総額を集計する）

【Skill なしのベースライン結果】：
（例：モデルは Skill がない状態でも SQL を記述できるが、社内のコアデータテーブル名を知らない）

【期待される合格条件】：
（例：正しい売上テーブル名を参照し、期間フィルタを含め、社内テストアカウントを明示的に除外していること）

【Skill はトリガーされたか】：
（例：はい。実行ログにおいてモデルが当 Skill の SKILL.md を読み込んだことを確認）

【実際に読み込んだファイル / 呼び出したツール】：
（例：SKILL.md と reference/sales.md を読み込み、外部スクリプトの呼び出しはなし）

【実際の失敗/乖離の挙動】：
（例：新規セッションで初版の Skill を使用したところ、モデルはテーブルを特定できたが、社内テストアカウントを除外するフィルタ条件を依然として見落とした）

【どのルールまたはファイルを修正するか】：
（例：SKILL.md を修正し、「テストアカウントの除外」を末尾の注記からコアなクエリ仕様へ移動し、表現を「除外を推奨」から「MUST filter test accounts」へと変更）

【修正前後の照合根拠】：
（例：修正前後に生成された SQL クエリの WHERE 句を比較し、account_type != 'test' のフィルタ条件が含まれているかを確認）

【新規セッションでの実行結果】：
（例：クリーンな新規セッションを立ち上げて同種タスクを再実行したところ、モデルが生成した SQL に WHERE account_type != 'test' が正しく追加された）

【次の最適化ステップ】：
（例：Claude Haiku および Opus でそれぞれ当テストケースを実行し、Haiku においてより詳細なフィールドマッピングの説明が必要かどうかを確認する）