Skills実践編（作る・測る・直す）

スキルを作るだけなら、15分から30分あれば終わります。

前回、Skillsは「呼ばれたときだけ読まれる手順書」だと学びました。作ること自体は、そこまで難しくありません。フォルダを1つ作り、SKILL.md に手順を書けば、それでスキルは動き出します。

難しいのはそこから先です。狙った場面で確実に発火し、狙わない場面では黙って引っ込んでいる。この2つを両立させるのに、多くの人がつまずきます。作ったのに使われない、あるいは作ったのに関係ない場面まで顔を出す。原因の多くは、作り方ではなく設計の詰め方にあります。

この回では、公式ガイド（The Complete Guide to Building Skills for Claude）と公式ドキュメントに書かれている、設計の数字・実装パターン・診断の手順をまとめて渡します。前回が「概念」だとすれば、今回は「実務」です。

3段階とフォルダ構造を対応づける

前回の「待機・発火・実行」は、実は具体的なフォルダ構造と1対1で対応しています。

Skillsのフォルダには4種類の中身があります。SKILL.md は必須で、それ以外の3つは任意です。

前回の3段階に当てはめると、第1レベル（待機中の名前と説明文）はフロントマター、第2レベル（発火後に読む本文）は SKILL.md の中身、そして第3レベル（実行時にClaudeが必要に応じて選んで開く追加ファイル）が、この scripts/ references/ assets/ の3フォルダです。

段階的開示という設計の正体は、この3フォルダの使い分けそのものです。詳細なAPI仕様を SKILL.md に直接書き込まず references/api-patterns.md に逃がしておけば、その仕様が必要ない場面ではトークンを一切消費しません。同じ理由で、検証ロジックは scripts/validate.py に切り出しておくほうが、SKILL.md を軽く保てます。

数字で見る、コンテキストコスト

「軽い」という前回の説明は、具体的な数字の積み上げでできています。

最後の2つは、地味ですが実害が出やすい数字です。スキル一覧のコンテキスト予算がモデルのコンテキストウィンドウの1パーセントしかないため、スキルをたくさん持っているほど、あまり使わないスキルから順にdescriptionが削られていきます。会話が長くなって要約(auto-compaction)が起きたときも同じで、各スキルの先頭5000トークンだけが残り、それも全スキル合計で25000トークンという共有予算の中でのやりくりです。

つまり、スキルを増やすこと自体はほぼ無料ですが、使わないスキルを増やすと、よく使うスキルの説明文の解像度が下がっていくという副作用があります。「軽い」は無条件の軽さではなく、この予算の中で成立している軽さです。

descriptionの構造式

発火の良し悪しは、ほぼdescription1文で決まります。

公式ガイドは、descriptionの書き方を1つの式にまとめています。

良い例と悪い例を並べると、この式の効き目がよく分かります。

3つの悪い例に共通するのは、どれも「作り手の視点」で書かれていることです。曖昧すぎる、トリガーがない、専門的すぎる。いずれも、使う側が実際にどう言うかを想像せずに書かれています。良い例は逆に、.figファイルという具体物と、使う側が打ちそうな3つの言い回しをそのまま埋め込んでいます。

作る前の設計問診

コードを書く前に、具体的なユースケースを2つか3つ特定します。

公式ガイドは、実装に入る前に次の4点を自問するよう勧めています。

• ユーザーは何を達成したいか
• どんなマルチステップワークフローが要るか
• どのツールが要るか（組み込みか、MCP経由か）
• どんなドメイン知識やベストプラクティスを埋め込むべきか

この4点を先に言葉にしておくと、SKILL.md の本文を書く段階で迷いが減ります。逆に、この4点を飛ばしていきなり書き始めると、本文が「あれもこれも」で膨らみがちです。

成功基準も、実装の前に決めておきます。定量と定性、2つの軸で測ります。

公式ガイドは、ここで正直な留保も書き添えています。厳密な計測を目指しつつも、最終的には vibes-based assessment(感覚に基づく判断)の要素が残ることは受け入れよ、というものです。数字だけで白黒つく世界ではない、という前提を持っておくと、テストの結果に振り回されすぎません。

5つの実装パターン

SKILL.md の本文をどう組み立てるか。公式ガイドは、繰り返し現れる5つの型を挙げています。

Sequential workflow orchestration(逐次ワークフロー)

順序が決まったマルチステップ処理に使います。明示的なステップ順序、ステップ間の依存関係、各段階での検証、失敗時のロールバック手順を書きます。たとえば経理担当者が毎月の請求書処理を「受領確認→仕訳入力→承認依頼→支払い実行」の順で固定するようなケースです。

Multi-MCP coordination(複数サービス連携)

ワークフローが複数のサービスをまたぐときに使います。フェーズを明確に分離し、あるフェーズの出力を次のフェーズに渡し、次に進む前に検証を挟みます。営業担当者が「見積作成(スプレッドシート)→契約書生成(文書ツール)→承認通知(チャットツール)」のように複数の道具を順に渡り歩く場面が典型です。

Iterative refinement(反復改善)

反復するほど品質が上がる作業に使います。明示的な品質基準、検証スクリプト、そして「いつ止めるか」を決めておくことが要点です。編集者が原稿を「初稿→校正チェック→修正→再チェック」と品質の閾値を満たすまで回すような作業に対応します。

Context-aware tool selection(文脈依存のツール選択)

同じ結果を得るのに、状況によって使う道具を変えるときに使います。明確な判断基準、うまくいかなかったときのフォールバック、なぜその道具を選んだかの透明性が要点です。ファイルの保存先を、容量やファイル形式によって自動で振り分けるような場面です。

Domain-specific intelligence(ドメイン特化の知性)

単なる道具へのアクセス以上の、専門知識を足すときに使います。行動する前の確認、判断の記録、監査証跡が要点です。人事担当者が採用候補者の書類を、社内規程に照らして確認してから次の担当者に回すような、コンプライアンス性の高い作業に向いています。

テストは3種類ある

発火するかどうかは、感覚ではなく測れます。

公式ガイドは、テストを3つの領域に分けています。

「発火テスト」の目的は、スキルが適切なタイミングでロードされることの確認です。明白なタスクで発火するか、言い換えたリクエストでも発火するか、そして無関係な話題では発火しないか。最後の「発火しない」ことを確かめる否定側のテストが、意外と見落とされがちです。

「機能テスト」の目的は、スキルが正しい出力を生成することの確認です。有効な出力が生成されるか、道具の呼び出しが成功するか、エラーハンドリングが機能するか、想定外のケースまで網羅できているか。

「性能比較」の目的は、スキルがベースラインより結果を改善することを証明することです。公式ガイドが挙げている例では、スキルなしだと往復15メッセージ、リトライを要する失敗が3件、12000トークン消費だったものが、スキルありだと確認質問2回だけ、失敗0件、6000トークン消費まで縮んだとされています。これは公式ガイドが挙げた例示であり、公式の実測値として一般化されたものではない点に注意してください。ただし、スキルの効果を数字で語るとこういう形になる、というイメージは掴めます。

この3種類のテストを実際に回してくれるのが、公式マーケットプレイスの skill-creator です。評価パイプラインは次の順で動きます。

「動いているように見えるスキル」と「動くと分かっているスキル」の差は、このパイプラインを1回でも回したかどうかです。

症状別の診断表

不具合には、たいてい決まった原因と決まった対処があります。

言語ではなくコードに委ねる

「指示に従わない」への対処は、もう一段深掘りする価値があります。

公式ガイドの上級テクニックはこう書いています。「重要な検証については、言語による指示に頼るより、プログラム的にチェックを行うスクリプトを同梱することを検討する。コードは決定論的だが、言語の解釈はそうではない」。

つまり「ちゃんと検証してください」と SKILL.md に書くより、scripts/validate.py を同梱して「これを実行して確認する」と書くほうが確実だということです。言葉での指示は、そのときのモデルの解釈次第で揺れます。スクリプトの実行結果は揺れません。

これは、Hooksの思想と地続きです。CLAUDE.mdに書いた運用ルールは「お願い」であり、Claudeが読み飛ばす余地が残ります。hookで強制すれば、そこは揺れない仕組みになります。SkillsとHooksは別の機構ですが、「言語による説得」と「コードによる強制」を使い分けるという発想の根っこは同じです。

もう1つ、逆説的な運用知見も紹介します。品質を求める励まし、たとえば「じっくり時間をかけて」「速度より品質を優先して」といった一文は、SKILL.md に書くより、ユーザープロンプト側に書くほうが効果的だと公式ガイドは述べています。スキルの本文は毎回同じように読まれますが、その場のプロンプトに書いた励ましのほうが、その場の実行に強く効くということです。

置き場所と優先順位

スキルは4つの階層のどこかに置かれます。

同名のスキルが複数階層にある場合は、enterpriseがpersonalを、personalがprojectを上書きする優先順位です。SKILL.md の中身を編集した場合、セッションを再起動しなくても変更はすぐ反映されます。ただし新しくトップレベルのディレクトリを作った場合(新しいスキルフォルダを作る場合)は、再起動が必要です。

もう1つ、見落としやすい罠があります。Coworkセッションやクラウドセッション(routinesを含む)は、ローカルマシンの ~/.claude/skills/ を読みません。理由は単純で、routineの実行は毎回新しいリモートセッションとして始まるからです。個人のローカルにしか置いていないスキルをroutineから呼ぼうとすると、「スキルが見つからない」という結果になります。自動化に組み込む予定のスキルは、置き場所をあらかじめ意識しておく必要があります。

隠れ機能3点

スキルは、静的なテキストファイルではありません。

「引数」は、呼び出し時に渡した値を SKILL.md の中で使えるしくみです。$ARGUMENTS は渡した全引数、$1 のような表記は位置指定の引数、フロントマターで宣言した名前で受け取る名前付き引数もあります。同梱したスクリプトのディレクトリを指すには CLAUDE_SKILL_DIR という変数を使います。

「動的コンテキスト注入」(!command構文)は、SKILL.md の本文がClaudeに送られる前に、シェルコマンドを実行するしくみです。コマンドの出力がプレースホルダーを置き換えるので、Claudeが受け取るのはコマンドそのものではなく、実際のデータです。たとえば git diff HEAD の出力を先に埋め込んでおけば、Claudeは「変更点を推測する」のではなく「変更点をそのまま読む」ことになります。

「context: fork」は、フロントマターにこの指定を足すと、スキル自体がサブエージェントとして走るしくみです。ただし公式ガイドの注意点として、タスクを伴わない、ガイドラインだけのスキルにforkを付けても意味がありません。「このAPI規約を使うこと」のような方針だけを渡されたサブエージェントは、実行可能な指示がないまま、意味のある出力を返せずに終わります。forkが効くのは、明確な作業手順を持つスキルだけです。

今日のまとめ

• フォルダ構造(SKILL.md・scripts/・references/・assets/)は、前回学んだ3段階(待機・発火・実行)とそのまま対応する
• descriptionは「何をするか」＋「いつ使うか」＋「主要な能力」の式で書く。使う側が実際に打つ言葉を入れる
• 発火・機能・性能比較の3種類のテストがあり、skill-creatorで数字にできる
• 重要な検証は言葉でなくスクリプトに委ねる。コードは決定論的、言語の解釈はそうではない
• 同時に有効化するスキルが20から50個を超えたら、選択的な有効化を検討する