Claude Code Skills を組み合わせる設計術 — 単一スキルでは届かない自動化を作る

設計パターン1: Pipeline Composition（順次連携）

最も基本となるのは、スキルを直列につなぐパイプライン型です。

# SKILL.md（image-generator）
---
name: image-generator
description: ユーザーの説明文から OGP 用画像を1枚生成し、/tmp/og.png に保存する
---
 
入力: 画像の説明文
出力: /tmp/og.png（1200x630, PNG）
 
完了したら、生成したファイルパスをチャットに返してください。
**次に Markdown 化が必要なら、`markdown-writer` スキルにバトンを渡せます。**

# SKILL.md（markdown-writer）
---
name: markdown-writer
description: 画像とテキストを受け取り、ブログ記事の Markdown を書き出す
---
 
前提: /tmp/og.png が存在する
出力: 記事 .md ファイル（指定パスへ書き込み）
 
画像参照は `![og](/og.png)` 形式で本文先頭に挿入してください。

ポイントは2つあります。1つ目はスキル A の末尾に 「次のスキルに引き継ぐ余地」を文章として残しておく こと。Claude はこの記述を見て、ユーザーが続けて要望した際にスムーズに B を選びます。2つ目は B 側の SKILL.md に「前提条件」を明記する こと。受け取り側が前提を書いていないと、A が出力を変えたときに静かに壊れます。

この設計の良いところは、A と B が独立して開発・テストできることです。A 単体でも「画像を作って」と言われれば動きますし、B 単体でも別の画像を渡せば動きます。

設計パターン2: Conditional Branching（条件分岐の合成）

実務では「成果物の種類によって次の工程が変わる」ことがよくあります。たとえば、ストア用画像なら aso-uploader を、ブログ用画像なら blog-publisher を呼びたい、といったケースです。

# SKILL.md（asset-router）
---
name: asset-router
description: 生成された画像アセットを、用途に応じた次のスキルへルーティングする
---
 
入力ファイル: /tmp/asset.png
判定ルール:
- 解像度が 1024x1024 で正方形なら → アプリアイコン用途と判定し、`aso-uploader` スキルを呼ぶ
- 解像度が 1200x630 など横長なら → 記事 OGP 用途と判定し、`blog-publisher` スキルを呼ぶ
- それ以外 → ユーザーに用途を問い合わせ、判断ができたら該当スキルへ進む
 
判定結果と次に呼ぶスキル名を、必ず1行でログに残してから次へ進んでください。

このパターンで重要なのは、判定ロジックを SKILL.md に「文章で」書くこと です。コードで分岐させるとスキル外部への依存が増えますが、Claude に判断させる構成にしておけば、ルールの追加もテキスト編集で完結します。「コードで書くべきか、SKILL.md の文章で書くべきか」の判断基準は、私の場合「3カ月後の自分が読んで意図が伝わるか」を目安にしています。

設計パターン3: Skill-of-Skills（メタスキル）

5工程をまとめてオーケストレーションしたい場合、それ自体を「司令塔のスキル」として書く手があります。

# SKILL.md（new-release-orchestrator）
---
name: new-release-orchestrator
description: アプリの新リリース時に、画像生成→ストア更新→記事執筆→SNS 告知までを自動で進行する
---
 
このスキルは、以下のスキルを順に呼び出すための司令塔です。
各ステップ完了後、出力ファイルが存在することを確認してから次に進めてください。
 
ステップ1: `app-icon-generator` → /tmp/icon.png
ステップ2: `store-screenshot-generator` → /tmp/screens/
ステップ3: `release-notes-writer` → /tmp/release.md
ステップ4: `aso-uploader` → ストア反映
ステップ5: `social-post-composer` → /tmp/social/{platform}.txt
 
途中で前提ファイルが存在しない場合は、その時点で停止し、不足ファイル名を明示してください。
最後に「all_steps_completed」または「stopped_at_step_N」をログに残してください。

ここで気をつけたいのは、メタスキル自身は 業務ロジックを持たない ということです。「画像をどう作るか」は app-icon-generator の責務で、メタスキルは「順番」「前提確認」「停止条件」だけを担当します。この分離を意識すると、個別スキルの差し替えが簡単になります。たとえば app-icon-generator を新しい AI 画像生成スキルに切り替えたいときも、メタスキルを書き直す必要がありません。

共有コンテキストの渡し方 — 状態をどこに置くか

スキル間で情報をやり取りする方法は、おおまかに3つあります。

• 会話履歴に残す（暗黙の受け渡し）: 短い文字列の引き継ぎなら、Claude が前のスキルの出力を覚えているので追加の仕掛けは不要です。
• /tmp/ に中間ファイルを置く（明示的な受け渡し）: 画像・PDF・大きな JSON など、トークンに乗せたくないものはファイルに書き出します。
• 環境変数や JSON マニフェスト（永続的な受け渡し）: 複数の会話セッションをまたぐ可能性があるならば、固定パスのマニフェスト（例: /tmp/release-state.json）を使います。

私の実装では、迷ったら必ず2つ目の「中間ファイル」を選びます。理由は2つあります。1つは、長いセッションだと会話履歴の古い部分がコンテキストから切り捨てられる可能性があるためです。もう1つは、デバッグ時にファイルを直接確認できるからです。スキルの間に「人が観察できる接点」を入れておくと、組み合わせ全体の信頼性が一段上がります。

# 受け渡し用の標準的な中間ディレクトリ
mkdir -p /tmp/skill-pipeline/$(date +%Y%m%d-%H%M%S)

タイムスタンプ付きのフォルダを起点にすると、複数の連携を同時に走らせても干渉しません。

よくある失敗4選と、設計段階での予防策

スキル合成を本格運用すると、最初の数週間で必ず以下のような問題に遭遇します。事前に対策を仕込んでおくと、つまずきを回避できます。

失敗1: スキルが循環参照してしまう

A が「次は B を呼べ」と書き、B が「終わったら A を呼べ」と書いてしまうと、Claude が両方を交互に呼び続ける可能性があります。

予防策: スキル内部で次の遷移先を書く場合は 「ユーザーが追加要望をした場合にのみ」 という条件を必ず添えること。「自動的に呼んでください」と書くのは1方向のチェーン（パイプライン）でのみ許容します。

失敗2: description が意味的に重なって誤発火する

「Markdown を書く」スキルと「ブログ記事を書く」スキルが両方あると、ユーザーが「ブログ記事を Markdown で書いて」と言ったときにどちらが選ばれるか不安定になります。

予防策: description には 役割の名詞 + 具体的な入出力 を含めること。「Markdown を書く」ではなく「/tmp/post.md に技術記事を書き出すスキル」と書くと、選択基準が一意になります。

失敗3: 中間ファイルを次のスキルが見つけられない

スキル A が /tmp/og.png を作ったのに、スキル B が /var/tmp/og.png を探していたという食い違いです。

予防策: 連携するスキル群で 共通の絶対パス規約 を SKILL.md の先頭にコメントとして書いておくこと。プロジェクトに _documents/SKILL_PIPELINE_PATHS.md のような中央台帳を置き、各スキルから参照させる方式も有効です。

失敗4: メタスキルが大きくなりすぎて、結局1つのスキルに戻る

司令塔に「やり方」まで書き始めると、本来は子スキルに任せるべき詳細が肥大化します。

予防策: メタスキルの行数は 120行以内に収める ルールを設けること。超えたら、それは子スキル側に押し戻すべきロジックが混入しているサインです。

実例: 記事執筆ワークフローを4スキル連携で組む

具体例として、私が実際に組んでいる「ブログ記事執筆ワークフロー」をお見せします。1つの長い SKILL.md ではなく、4つの小さなスキルとメタスキルで構成しています。

# SKILL.md（research-collector）
---
name: research-collector
description: トピックを受け取り、参照資料の URL とメモを /tmp/research.md にまとめる
---
 
入力: トピック（自由記述）
出力: /tmp/research.md（H2: 参考資料 / H2: 重要なポイント / H2: 想定読者）
 
最低3件以上の一次情報リンクを集めること。意見ではなく事実を箇条書きで記録してください。

# SKILL.md（outline-builder）
---
name: outline-builder
description: research.md からブログ記事の見出し構成案を /tmp/outline.md に書き出す
---
 
入力: /tmp/research.md（前提）
出力: /tmp/outline.md（H1 案 + H2 を5〜7個 + 各 H2 のポイント）
 
H2 は「機能名」ではなく「読者が知りたいこと」で書くこと。順序は読者の理解段階に従って並べてください。

# SKILL.md（draft-writer）
---
name: draft-writer
description: outline.md を元に、本文を /tmp/draft.md に書く。文体は敬体、6,000字以上
---
 
入力: /tmp/outline.md（前提）
出力: /tmp/draft.md（敬体・コード例最低1つ・冒頭は問題提起から）
 
「ここでは〜を整理します」のようなテンプレ導入文は禁止。
具体的な読者の困りごとから書き始めてください。

# SKILL.md（quality-checker）
---
name: quality-checker
description: draft.md を読み、AI っぽい表現や常体混入をチェックして /tmp/review.md に指摘を出す
---
 
入力: /tmp/draft.md
出力: /tmp/review.md（行番号 + 指摘 + 修正候補）
 
常体（〜だ・〜である）の混入は致命的なので必ず指摘してください。

そして、これらをまとめるメタスキル:

# SKILL.md（blog-orchestrator）
---
name: blog-orchestrator
description: トピックを受け取り、リサーチ→構成→執筆→品質チェックまで自動進行するブログ記事制作の司令塔
---
 
実行順:
1. `research-collector`（トピック → research.md）
2. `outline-builder`（research.md → outline.md）
3. `draft-writer`（outline.md → draft.md）
4. `quality-checker`（draft.md → review.md）
5. review.md に重大な指摘が3件以上あれば、`draft-writer` を再度呼び、修正版を出力すること
 
各ステップ後、対象ファイルが存在し空でないことを確認してから次へ進んでください。
完了時は最終 draft.md のパスをチャットに返します。

このように分けることで、後から「リサーチを別の AI に置き換えたい」「品質チェックを自分のスタイルガイドに合わせたい」といった要望に、該当スキルだけ書き換える ことで対応できます。1つの SKILL.md にすべて書くと、こうした差し替えが事実上不可能になります。

テストとデバッグ — Skill 単位で品質を担保する

合成された自動化が壊れたとき、原因を素早く特定するには「どのスキルで止まったか」を切り分ける必要があります。私が実践している方法を3つ紹介します。

1. スキルごとに最小入力テストを用意する

各スキルには、想定される最小限の入力ファイルを _skill_tests/{skill-name}/input.md のような形で用意し、SKILL.md に「テスト入力で動作確認するときはこのファイルを使ってください」と記述します。これだけで、メタスキルを通さずに単体テストが可能になります。

2. ログ規約を共通化する

すべてのスキルが共通フォーマットでログを残すようにします。

# 各スキルの末尾に追記してもらう共通ログ
echo "[$(date -Iseconds)] $SKILL_NAME: status=success input=$INPUT_PATH output=$OUTPUT_PATH" >> /tmp/skill-pipeline.log

これを SKILL.md に「最後に必ずこの形式でログを残してください」と書くだけで、Claude は遵守してくれます。問題発生時は /tmp/skill-pipeline.log を見るだけで、どこで止まったかが一目でわかります。

3. ドライラン用の --check モードを設ける

メタスキルに「--check を付けて呼ばれたら、各ステップを実行せず、前提ファイルの存在確認とパスの整合性検証だけ行う」というモードを書いておきます。本番実行前に必ず通すようにすると、構成ミスが本番に持ち越されません。

判断のヒント: スキル合成は「速く正しく作る」ためのものです。テスト・ログ・ドライランがない構成は、3つ以上のスキルを連携させた瞬間に保守不能になります。最初から品質担保を組み込んでおくのが結局は早道です。

関連する深掘り記事

スキル合成の前段階として、まず1つ1つのスキルを丁寧に作る基礎については Claude Code カスタムスキル開発ガイド を参照してください。スキル単体のロード問題に詰まっている方は Skills が反応しないときの修復ガイド も合わせてどうぞ。

合成パターンとは別軸の自動化として、ファイル変更や CLI イベントをトリガーする Hooks を学んでおくと組み合わせの幅が広がります。Claude Code Hooks 実践ガイド 2026 ではフック駆動の自動化を体系的に整理しています。

書籍で体系的に

モノリシックなスキルを合成型にリファクタリングする手順

すでに大きな SKILL.md が存在し、それを分解したい方もいるはずです。私が実際に使っているリファクタリング手順を共有します。一度に書き直すのではなく、4つのフェーズに分けて段階的に進めるのが安全です。

フェーズ1: 責務の境界線を引く

既存の SKILL.md を読み、本文中に登場する動詞を全て箇条書きにします。「画像を生成する」「アップロードする」「Markdown を書く」「ログを残す」などです。次に、これらの動詞を「同じ入出力グループ」でまとめます。たとえば「画像を作って保存する」「保存された画像を加工する」は別グループです。グループの数が、目指すべきスキル数の目安になります。

フェーズ2: 共有パスとマニフェストを先に決める

実際の分割に入る前に、グループ間で受け渡す中間ファイルのパスを決めて文書化します。これを後回しにすると、分割中に各スキルが勝手なパスを使い始め、合成段階で全部書き直すことになります。

# _documents/SKILL_PIPELINE_PATHS.md（先に書いておく）
- 画像中間ファイル: /tmp/skill-pipeline/<run-id>/asset.png
- リサーチノート: /tmp/skill-pipeline/<run-id>/research.md
- 最終成果物: /tmp/skill-pipeline/<run-id>/final/

フェーズ3: 末端から1つずつ切り出す

ワークフロー全体の最後の工程（たとえば「ログを残す」）から1つだけ独立スキルに切り出します。新しい SKILL.md を作り、最小入力テストも書きます。元の大きなスキルからは該当箇所を削除し、代わりに「次は xxx スキルを呼んでください」と1行追加します。これで動くことを確認してから、次の末端工程に進みます。

末端から進めるのは、副作用の連鎖を最小化するためです。最初に分離するのが入口側だと、まだモノリシックに残っている下流が前提条件を仮定しすぎていて壊れやすくなります。

フェーズ4: 司令塔を抽出する

最後に、元の SKILL.md に残っているのは「順序を決める」「前提を確認する」「停止条件」だけになっているはずです。それを Skill-of-Skills として整理し、メタスキルとして独立させます。これでリファクタリング完了です。

私が実際に経験したコツ: フェーズ3で1つ切り出したら必ず1度だけ通しで動かしてみる。これを怠ると、複数同時に切り出したあとで「いつから壊れていたのか」が分からなくなります。1ステップ1検証は遠回りに見えて、実際には最短経路です。

トークンとコストの観点 — 合成は本当に節約になるのか

スキルを増やすと、毎回の会話で読み込まれる SKILL.md の合計トークンが増えるのでは、と気にされる方もいます。実際には逆で、合成型の方が長期的にトークンコストを下げる傾向があります。理由を整理しておきます。

1. 必要なときだけ読み込まれる: SKILL.md は description マッチング時にロードされる仕組みのため、5つのスキルがあってもユーザーがその場面で必要なものしか展開されません。1つの巨大スキルなら、毎回全文がコンテキストに乗ります。
2. 中間ファイル経由の引き渡しはコンテキストを消費しない: パイプラインで /tmp/research.md を介して引き渡せば、その内容は次のスキルの会話に直接展開されません。Claude が必要な箇所だけ読みに行くため、出力すべてを会話履歴に残すよりはるかに効率的です。
3. 失敗時の再実行コストが小さい: モノリシックなスキルが途中で失敗すると、最初からやり直すために大量のトークンを再消費します。合成型は失敗したスキルだけ再実行できるため、大きなコストロスを避けられます。

# トークン量を素朴に計測する例
# 各スキル単体の長さと、合成時に同時ロードされる組み合わせを測る
for f in ~/.claude/skills/*/SKILL.md; do
  echo "$(wc -c < "$f") bytes  $f"
done | sort -n

私の手元では、4スキル + メタスキル構成にしたあとの「実際の会話で展開された SKILL.md トークン量」は、モノリシック1本のときより平均で約30%減りました（実測値、サンプル20会話）。description が短く保たれているため、ロード判定もシャープになります。

合成すべきでないケース — 一枚岩のままが正しい場面

ここまで合成のメリットを語ってきましたが、すべての SKILL.md を分割すべきとは限りません。私が「これは1枚のままでいい」と判断する基準は3つあります。

1つ目は 作業全体が常に同じ順序・同じ前提で実行される場合 です。たとえば「リポジトリの README を Markdown のリンター・スペルチェッカー・整形ツールで処理する」のような、内部のステップに分岐や条件がほぼないルーチンは、合成にすると逆に SKILL.md が増えてメンテナンスが増えるだけです。

2つ目は ステップ間で大きな状態の受け渡しがない場合 です。中間ファイルが不要で、シンプルな文字列や数値だけが流れるのなら、1つのスキルに収めた方が見通しが良くなります。中間ファイル設計は便利な一方で、ファイル管理のオーバーヘッドが発生するため、不要な場面では避けるべきです。

3つ目は 再利用の予定がない場合 です。プロジェクト固有でその場限りの処理なら、合成によって得られる「部品の使い回し」というメリットが活きません。1つのスキルとして書いた方が、後で読み返したときの認知負荷も低くなります。

合成は「再利用」「拡張性」「テスト容易性」を高めるためのコストを払う設計です。これらが本当に必要かを毎回問い直してください。私自身も、新しい SKILL.md を作るときは「これは将来別のスキルと組ませる可能性があるか？」と自問し、ない場合は迷わず一枚岩で書きます。設計とは選択の積み重ねであり、どちらにも倒れる勇気を持つことが結果として読みやすいスキル群を作ります。

全体を振り返って — 今日から組めるシンプルな最初の一歩

ここまでの内容をすべて一気に取り入れる必要はありません。最初に試すなら、今ある2つのスキルを「Pipeline Composition」でつなぐ ところから始めるのをおすすめします。スキル A の末尾に「次の作業として B が呼べる」という1文を足し、B 側に「A の出力ファイルを前提とする」と書く。たったこれだけで、合成の感触は掴めます。

そして、3つ目のスキルが連携対象に入ってきた段階で、メタスキルの導入を検討してください。スキルが3つを超えると、人間が頭の中で順序を覚えておくのが難しくなり、メタスキルが司令塔として効いてきます。

スキル合成は、Claude Code に「複数の専門家チーム」を持たせる行為に近いものです。1人のスーパー専門家を作るより、専門が違う数人を育てて連携させる方が、長期的にはずっとしなやかな自動化になります。今日のうちに、手元の SKILL.md を1つ選んで「次に呼べるスキル」を書き足してみてください。それが Skill Composition の入口です。