Claude Codeスキル設計パターン実践ガイド — 5つの実例で学ぶ設計思考

SKILL.mdの構文はわかった。保存場所も知っている。YAMLフロントマターの書き方も覚えた。でも、いざ自分のワークフロー用にスキルを作ろうとすると、手が止まってしまう。

「全部1ファイルに書けばいいの？」「リファレンスって分けた方がいいの？」「200行のスキルと2000行のスキル、どっちが正しいの？」

この記事では、実際に稼働している5つのスキルを解剖して、スキル設計の思考プロセスを体系化します。「書き方」ではなく「設計の考え方」を身につけるのがゴールです。

スキルを作るべき瞬間を見極める

スキルは便利ですが、なんでもスキルにすればいいわけではありません。まずは「いつスキルを作るべきか」を判断する3つの基準を紹介します。

3つの判断基準

1. 頻度 ― 3回ルール
   同じプロンプトや手順を3回以上書いたら、スキル化の候補です。1回しか使わないものをスキルにするのはオーバーエンジニアリングです。
2. 複雑さ ― 3ステップ以上
   「ファイルを読む → 分析する → 出力する → 品質チェックする」のように3ステップ以上の手順がある場合、毎回書くのは非効率です。
3. 外部知識 ― Claudeが知らないこと
   社内ツールの使い方、独自フレームワークのルール、APIの非公開仕様など、Claudeの学習データにない知識はスキルに書くしかありません。

CLAUDE.md に書くか、スキルにするか

よくある悩みが「CLAUDE.mdに書くのとスキルにするの、何が違うの？」という問題です。判断基準はシンプルです。

4つの設計パターン ― 実稼働スキルから抽出

ここからが本題です。当プロジェクトで実際に使っている5つのスキルを分析し、4つの設計パターンに分類しました。それぞれのパターンがどういう場面で適切かを、実際のコードとともに解説します。

パターン1: 手順集約型（Procedure-First）

特徴: SKILL.md 1ファイルに全手順を書ききる。サブファイルなし。

適用条件: 手順が200行以内に収まり、毎回の実行で全体を把握する必要がある場合。

最もシンプルなパターンです。記事用の挿絵を生成するarticle-slidesスキルがこれに該当します。

# 記事用挿絵スライド生成スキル（article-slides SKILL.md 抜粋）

## ワークフロー
記事HTML/トピック
      |
[Step 1] スライド設計（Claude が記事を分析）
  -> 必要枚数・テーマ・テキスト・構図・キャラ使用を決定
      |
[Step 2] 一発生成（Gemini API）
  -> キャラ参照画像 + テキスト込みプロンプト -> 完成スライド
      |
[Step 3] 品質チェック（Opus + Gemini 二重検証）
  -> パスのみ最終出力、NGは OLD/ に退避
      |
[Step 4] 出力（WebP/PNG 16:9）

## 重要ルール（絶対遵守）
1. リアのビジュアルをプロンプトに記述しない（参照画像に委ねる）
2. テキストがキャラの顔に被る配置は絶対NG
3. NG画像は上書き・削除しない（OLD/ に退避）

ワークフロー、ルール、コード例がすべて1ファイルに収まっています。分割する理由がないからです。

パターン2: カテゴリ分割型（Lazy-Loaded Category）

特徴: SKILL.mdに共通ルールを書き、categories/フォルダに出力タイプ別の定義を分離。

適用条件: 同じエンジンやフレームワークで、複数の出力パターンを扱う場合。

AI画像生成のプロンプトを設計するnanobanana-promptスキルがこのパターンです。「衣装カタログ」「1枚絵」「スプライトシート」など出力タイプごとにプロンプトの構造が異なりますが、基本ルールは共通です。

# SKILL.md（共通ルール部分 — 抜粋）

## プロンプト設計の基本ルール

### 1. 参照画像の扱い
- 参照画像1枚で十分
- キャラの外見をプロンプトに書かない（参照画像に委ねる）

### 2. プロンプトの基本構造
this [subject] wearing/with [描写], [ディテール], [スタイル]

## カテゴリ一覧
| カテゴリ     | ファイル                        | 説明                |
|-------------|--------------------------------|-------------------|
| catalog     | categories/catalog.md          | 衣装パーツカタログ    |
| illustration| categories/illustration.md     | CG1枚絵            |
| spritesheet | categories/spritesheet.md      | スプライトシート      |
| manga       | categories/manga.md            | 漫画パネル          |

スキルが呼ばれたら:
1. 指定カテゴリの categories/{category}.md を読む
2. ユーザーの要件に基づいて構造化JSONを生成

ポイントは「共通ルールはSKILL.md、カテゴリ固有の知識は別ファイル」という分離です。新しい出力タイプが追加されたとき、SKILL.mdは1行テーブルに追記するだけ。カテゴリファイルを1つ追加すれば拡張完了です。

パターン3: ルール索引型（Modular Rule Index）

特徴: SKILL.mdはインデックス（目次）のみ。rules/フォルダに独立したルールファイルを大量に配置。

適用条件: 大量の独立したルールがあり、タスクに応じて必要なものだけ読みたい場合。

Remotion（Reactベースの動画生成フレームワーク）のベストプラクティス集であるremotion-best-practicesスキルがこのパターンです。SKILL.mdはわずか46行で、本体は30以上の個別ルールファイルです。

# remotion-best-practices SKILL.md（全文）

---
name: remotion-best-practices
description: Best practices for Remotion - Video creation in React
---

## When to use
Use this skills whenever you are dealing with Remotion code.

## How to use
Read individual rule files for detailed explanations:

- rules/animations.md - Fundamental animation skills
- rules/audio.md - Using audio and sound
- rules/compositions.md - Defining compositions
- rules/transitions.md - Scene transition patterns
- rules/timing.md - Interpolation curves
- rules/videos.md - Embedding videos
... （30ファイル以上）

このスキルでは、Claudeは「アニメーション」の質問を受けたらrules/animations.mdだけを読みます。「フォント」の質問ならrules/fonts.mdだけ。全ルールを一度に読み込む必要がありません。

パターン4: 戦略参照型（Strategy-Referenced Decision）

特徴: SKILL.mdに手順とルールを書き、references/フォルダに意思決定の根拠となる戦略資料を分離。

適用条件: 通常の実行では不要だが、特定のコマンド（レビュー、分析、ネタ出し等）で深い知識が必要な場合。

X（Twitter）投稿スキルx-postがこのパターンです。通常の投稿ではSKILL.mdの手順とルールだけで十分ですが、投稿文のレビューやネタ出しをする場合は、アルゴリズム分析やHook設計の戦略知識が必要になります。

# x-post SKILL.md（抜粋）

## コマンド
| コマンド                  | 用途                |
|--------------------------|-------------------|
| /x-post <内容>          | テキストのみ投稿      |
| /x-post image <内容>    | 画像付き投稿         |
| /x-post review <投稿文> | 投稿文をレビューし改善 |
| /x-post ideas <テーマ>  | ネタ出し             |

## リファレンス
| ファイル                 | 内容              | 読み込みタイミング    |
|-------------------------|-------------------|-------------------|
| references/x-strategy.md | アルゴリズム権重・Hook公式 | review / ideas 時 |
| prompts/article-announce.md | 記事告知テンプレート | announce 時       |

読み込み原則: 必要なリファレンスだけを都度読み込む。

このパターンの核心は「読み込みタイミング」列です。どのコマンドでどのリファレンスを読むかを明示することで、Claudeは無駄なファイル読み込みをせず、必要な場面でだけ戦略知識を参照できます。

リファレンスファイルの設計原則

パターン2〜4ではリファレンスファイルに分離する設計を紹介しました。では「何をいつ分離するか」の判断基準はどうなっているのでしょうか。

Progressive Disclosure（段階的開示）

スキル設計の最重要原則はProgressive Disclosureです。Anthropic Academy公式コースでも強調されているこの原則は、「必要な情報を、必要なタイミングで、必要な分だけ読み込む」という考え方です。

具体的な判断基準は以下の通りです。

• SKILL.mdに直接書く場合: 200行以内に収まる AND 毎回の実行で必要な情報
• 別ファイルに分離する場合:
  • 条件分岐で読む（コマンドAでは必要だがBでは不要）
  • 200行を超える
  • 将来カテゴリやルールが追加される可能性がある

読み込みタイミングを明記する

リファレンスを分離したら、SKILL.md内にいつ読むかを明記するのが重要です。x-postスキルでは「リファレンス」セクションにテーブルで読み込みタイミングを書いています。

Claudeは賢いですが、「このファイルはreviewコマンドのときだけ読んでね」と明示的に書いた方が確実です。暗黙の期待は禁物です。

フォルダ命名規則

リファレンスファイルのフォルダ名は、内容の性質に合わせて使い分けます。

• categories/ ― 出力タイプ別（catalog.md, illustration.md）
• rules/ ― 独立したルール群（animations.md, fonts.md）
• references/ ― 判断材料・戦略資料（x-strategy.md）
• prompts/ ― プロンプトテンプレート（article-announce.md）

よくある失敗パターン（アンチパターン）

スキル設計でよくある5つの失敗パターンを紹介します。どれも「やりがち」なものばかりです。

1. 巨大SKILL.md

全情報を1つのSKILL.mdに詰め込んで1000行を超えてしまうパターンです。スキルが呼ばれるたびに全文がコンテキストに読み込まれるため、トークンを大量消費し、関係ない情報がノイズになります。200行を超えたら分割を検討してください。

2. リファレンスなき分割

ファイルを分割したものの、SKILL.mdから参照リンクや説明を書いていないパターンです。Claudeはファイルの存在を自動で認識しません。SKILL.md内にファイル一覧と説明を必ず書きましょう。

3. descriptionの手抜き

YAMLフロントマターのdescriptionが「便利なスキル」「ツール操作」のような曖昧な記述だと、Claudeの自動マッチングが効きません。「いつ」「何のために」使うかを具体的に書きましょう。

# 悪い例
---
name: my-tool
description: "便利なツール操作スキル"
---

# 良い例
---
name: nanobanana-prompt
description: "Nanobanana2/NanobananaPRO モデル向け構造化JSONプロンプト設計。
  衣装カタログ・1枚絵・スプライトシート等、出力タイプに応じた
  構造化JSONを生成する。
  用途: /nanobanana-prompt catalog, /nanobanana-prompt illustration"
---

4. 手順とルールの混在

「何をするか（手順）」と「守るべきこと（ルール）」が入り混じっていると、Claudeが手順を飛ばしたりルールを見落としたりします。セクションを分けて、手順は「ワークフロー」、ルールは「重要ルール」のように明確に区分しましょう。

5. 環境依存の暗黙知

「/home/user/my-project/にあるファイルを...」のように、特定環境のパスやAPIキーの場所をハードコードしてしまうパターンです。パスは変数化するか、.envからの読み込みを指示しましょう。チームで共有するスキルでは特に重要です。

スキル設計チェックリスト

スキルを作る前に、以下の7項目を確認してください。これを通過すれば、設計品質は十分です。

まとめ

この記事では、実稼働スキルから抽出した4つの設計パターンと、スキル設計の思考プロセスを解説しました。

• スキルを作るタイミング: 頻度（3回ルール）、複雑さ（3ステップ以上）、外部知識で判断
• 4つの設計パターン: 手順集約 → カテゴリ分割 → ルール索引 → 戦略参照
• リファレンス設計: Progressive Disclosure原則で、必要な情報を必要なときだけ
• アンチパターン回避: 巨大SKILL.md、リファレンスなき分割、description手抜き等に注意

最も大切なのは、まずパターン1で小さく始めること。200行を超えたら分割を考え、使いながら最適なパターンに進化させていく。スキルはコードと同じで、リファクタリングしながら育てるものです。