Claude Skills設計パターン：発火・手順・検証を壊れにくくする¶

対象 / ポイント

対象: Claude向けのカスタムSkillを作成・保守する利用者、開発者

ポイント:

良いSkillは、発火条件、実行手順、検証可能な完了条件を分離する
Claudeへ任せる自由度は、作業の壊れやすさとリスクに合わせて変える
長い仕様は参照ファイル、反復処理はスクリプトへ移し、本文を経路案内にする

Skillは長いプロンプトを保存する箱ではない。 Claudeが必要なときに見つけ、迷わず作業し、結果を検査できるように構成された実行パッケージである。¹

ここでは公式のauthoring best practicesを、実装時に使える6つのパターンへ整理する。²

パターン1：発火条件と手順を分ける¶

Skillの description は発火判定、SKILL.md 本文は発火後の実行を担う。

弱いdescriptionは「月次レポートを作る」のように機能だけを書く。強いdescriptionは、対象データ、利用場面、成果物まで含める。

月次のSaaS利用CSVから、部門別コスト、前月差、異常値を含む
管理者向けレポートを作る。利用量、請求、部門別集計の依頼で使う。

本文に「このSkillを使う場面」を書いても、発火前には本文が読まれない。発火に必要な情報はdescriptionへ置く。¹

パターン2：順序と分岐を明示する¶

複数ステップの作業は、番号付きの順序と停止条件で書く。

1. 入力ファイルの列名と文字コードを確認する
2. 必須列がなければ処理せず、不足列を報告する
3. 部門別に集計する
4. 元行数と集計対象行数を照合する
5. 差分が0の場合だけ成果物を保存する

条件分岐は「適切に処理する」ではなく、入力と行動の対応を書く。

条件	行動
必須列がない	停止して不足列を列挙する
通貨が複数ある	換算せず通貨別に分ける
部門名が空	`Unassigned` として要確認へ出す

パターン3：リスクに合わせて自由度を変える¶

Anthropicは、タスクの壊れやすさに応じて指示の具体性を調整する考え方を示している。²

自由度	書き方	向く作業
高い	目的と判断基準だけを示す	調査、構成案、表現改善
中間	推奨手順と変更可能なパラメーターを示す	分析、レポート生成
低い	固定コマンド、順序、停止条件を示す	移行、変換、公開前検査

壊れやすい作業で「自由に最善を選ぶ」と書くと再現性が落ちる。逆に文章の推敲まで固定手順にすると、状況に応じた判断を阻害する。

パターン4：本文を短いルーターにする¶

すべてを SKILL.md へ詰め込まず、用途別の参照ファイルへ分ける。

security-review/
├── SKILL.md
├── references/
│   ├── web-app.md
│   ├── cloud-infra.md
│   └── severity-rubric.md
└── scripts/
    └── validate-report.py

本文には「Webアプリなら references/web-app.md を読む」のように経路を書く。 Claudeは必要なファイルだけを読むため、無関係な資料をコンテキストへ入れずに済む。¹

参照ファイルが長い場合は目次を置き、同じ情報を複数ファイルへ重複させない。

パターン5：決定的な処理をスクリプトへ移す¶

件数照合、形式変換、ファイル名生成、スキーマ検証は、毎回Claudeに書かせるより同梱スクリプトへ固定する。

python scripts/validate-report.py output/report.json

本文には次を明記する。

いつ実行するか
必要な入力は何か
終了コードと出力をどう判断するか
失敗時に成果物を公開しないこと

スクリプトはコード全文をコンテキストへ入れずに実行でき、出力だけをClaudeへ返せる。¹

パターン6：例ではなく評価ケースを持つ¶

例を1つ置くだけでは、発火と品質を評価できない。最低限、次のケースを分けて保存する。

種類	確認すること
should-trigger	名前を呼ばなくても目的が一致すれば発火する
should-not-trigger	キーワードが似ても別用途なら発火しない
normal output	典型入力で必須項目を満たす
boundary	空、欠損、重複、巨大入力で安全に扱う
regression	過去に壊れた入力を再現しない

発火失敗はdescription、作業失敗は本文やスクリプト、品質不足は完了条件を優先して直す。すべてをプロンプトの言い換えで解決しない。

よくある失敗¶

本文に発火条件を書く¶

本文は発火後にしか読まれない。発火語と利用場面をdescriptionへ移す。

READMEを入口にする¶

Claudeが最初に読むのは SKILL.md である。利用者向け説明も、実行に必要なら本文か参照ファイルへ置く。

外部URLへ重要手順を依存させる¶

取得失敗と内容変更が再現性を壊す。必要な仕様はレビュー可能な形で同梱し、更新元URLと確認日ではなく更新手順を管理する。

万能Skillへ統合する¶

発火範囲が広がり、無関係なタスクでも選ばれやすくなる。入力、成果物、責任範囲が違うならSkillを分ける。

まとめ¶

descriptionに「何をするか」と「いつ使うか」を置く
本文には順序、分岐、停止条件、完了条件を書く
自由度をリスクへ合わせる
詳細資料と決定的処理をreferencesとscriptsへ分離する
発火、出力、境界、回帰を別々にテストする

Skillの品質は文章量では決まらない。Claudeが正しく見つけ、必要な資料だけを読み、失敗を検知できる構造が再利用性を作る。