Claude Code Skills 実践ガイド：再利用可能な AI ワークフローをゼロから構築する

Claude Code を毎日使ってコードを書いたりファイルを編集したりしているけれど、新しいセッションのたびに同じルールや手順を説明し直していませんか？Skills は Claude Code の「再利用可能な指示セット」で、繰り返し実行するワークフローをワンクリックで起動できる自動化システムとして固定できます。この記事では、実際に運用中のシステムを例に、Skills の理解から完全なワークフロー設計までを解説します。

TL;DR

• Skills は Markdown で書く再利用可能な指示セットで、Claude Code を「チャットアシスタント」から「ワークフロー自動化エンジン」に変える
• CLAUDE.md（常時読み込みのルール）vs Skills（オンデマンドのワークフロー）vs Hooks（自動トリガーのスクリプト）の役割分担を理解することが、良いワークフロー設計の前提
• SKILL.md は frontmatter（description）と markdown 指示だけで構成され、500行以内が理想的
• 実践事例：Shareuhack は13個の Skills でトピック選定から公開までの完全なコンテンツパイプラインを運用
• context 予算の制限（context window の2%）に注意。Skills は多ければ良いというものではない

なぜ Skills が必要か：「指示のコピペ」から「ワンクリック実行」へ

次のような経験があるなら、Skills が必要です：

• 新しいセッションのたびに同じ「以下のフォーマットに従って...」という指示を貼り付けている
• 同じワークフロー（記事執筆、コードレビュー、レポート整理）を毎回ゼロから説明している
• チームメンバーごとに Claude への指示の質がバラバラで、出力が安定しない

Skills が解決する核心的な問題はシンプルです：繰り返し実行する指示セットを再利用可能なモジュールとしてパッケージ化すること。一度書けば、あとは /skill-name でワンクリック起動。毎回 Claude にやり方を教え直す必要はありません。

Skills は Claude 用の SOP マニュアルだと考えてください。新入社員の初日にプロセスを口頭で一度説明しただけで覚えてもらうことは期待しません。ドキュメントを渡しますよね。Skills がそのドキュメントです。

Skills 化に向いている作業タイプ：

• 固定ステップのあるプロセス：コードレビューのチェックリスト、記事執筆フロー、PR テンプレート
• 特定のフォーマット出力が必要なタスク：コミットメッセージのフォーマット、レポートテンプレート、changelog 生成
• 多段階のワークフロー：調査 → アウトライン → 執筆 → レビュー。各段階に異なるルールと成果物がある

Skills vs CLAUDE.md vs Hooks：3層構造の役割分担フレームワーク

Claude Code には3つのカスタマイズメカニズムがあり、これらを混同するのが最もよくある間違いです。公式ドキュメントの設計によると、3つの役割分担は以下の通りです：

定義するもの	配置場所	読み込み方式	適した場面
全会話に適用するルール	CLAUDE.md	セッション開始時に自動読み込み	ブランドトーン、禁止事項、プロジェクト規約
特定タスクの完全なフロー	Skills（SKILL.md）	Claude が関連性を判断して読み込み、またはユーザーが手動トリガー	記事執筆、コードレビュー、調査レポート
毎回自動実行すべきチェック	Hooks（.claude/hooks/）	イベントベースの自動実行	lint、format、コミットメッセージ検証

CLAUDE.md は「常に有効な社内規則」です。毎回のセッション開始時に自動的に読み込まれ、常に context を占有します。「すべての回答は日本語で」「特定の API パターンは使用禁止」といった簡潔でグローバルに適用するルールに適しています。

Skills は「業務マニュアル」です。起動時は description（一文の要約）だけが context に入り、Claude が現在のタスクと関連性があると判断した場合のみ、完全な内容が読み込まれます。/skill-name で手動トリガーも可能です。この設計により、トークンを無駄にしません。

Hooks は「自動化されたセキュリティゲート」です。イベント（ツール呼び出し、通知など）と matcher 条件に基づいてシェルコマンドや HTTP リクエストを自動実行します。Claude の判断は不要です。例：コミットのたびに自動で linter を実行。

よくある間違い：

• すべてを CLAUDE.md に詰め込む：コードレビューフローが200行あるのに、90%の会話では使わない。CLAUDE.md に置くと毎回の会話でそのトークンを浪費することになります。Skill にしましょう。
• グローバルルールを Skill として書く：「すべてのコードは TypeScript を使う」というルールを Skill にすると、毎回読み込まれる保証がありません。CLAUDE.md に置くべきです。

判断の原則：「このルールは毎回の会話で必要か？」と自問してください。はいなら CLAUDE.md。特定のタスクでのみ必要なら Skill。無条件で自動実行が必要なら Hooks です。

SKILL.md の書き方：構造の分解と設計原則

公式ドキュメントによると、SKILL.md は2つの部分で構成されます：

---
description: "コードレビューを実行し、品質・セキュリティ・パフォーマンスをチェック"
---

# Code Review Skill

## ステップ1：変更内容の確認
git diff を読み、今回の変更の範囲と目的を理解する。

## ステップ2：品質チェック
以下の項目を一つずつ確認...

YAML Frontmatter（--- で囲まれた部分）は、この Skill が何をするかを Claude に伝えます。すべてのフィールドは任意ですが、description の記入を強く推奨します。Claude がこの Skill を読み込むかどうかを判断する根拠になるためです。

Markdown Body は、Skill を読み込んだ後に Claude が従う完全な指示内容です。

重要な上級 Frontmatter フィールド

フィールド	用途	例
description	Claude が読み込み判断に使う根拠（推奨）	"トピックを調査して Research Brief を作成"
user-invocable	ユーザーが /command で手動トリガー可能か	true
allowed-tools	Skill が使用できるツールを制限	["Read", "Grep", "WebSearch"]
model	実行モデルを指定	"claude-sonnet-4-6"
agent	context: fork と組み合わせてサブエージェント種別を指定	"research"

Progressive Disclosure デザインパターン

公式のベストプラクティスでは、SKILL.md を500行以内に収めることを推奨しています。それを超える場合は、詳細な参考資料を別ファイルに分割しましょう：

.claude/skills/
  my-skill/
    SKILL.md          ← メイン指示（500行以内）
    templates/         ← テンプレートファイル
    reference.md       ← 詳細な参考資料

SKILL.md 内で Read 指示を使い、必要な時だけ別ファイルを読み込むよう Claude を誘導します。一度に全部読み込むのではなく、必要に応じて展開する。これが Progressive Disclosure です：まずコア指示を提供し、必要なときに詳細を展開します。

実例：obra/superpowers の brainstorming Skill

実際に広く使われている Skill を見てみましょう。obra/superpowers はオープンソースの Claude Code Skills コレクションです。その中の brainstorming Skill の設計は参考になります：

---
name: brainstorming
description: "You MUST use this before any creative work - creating features,
  building components, adding functionality, or modifying behavior. Explores
  user intent, requirements and design before implementation."
---

# Brainstorming Ideas Into Designs

## Overview
Help turn ideas into fully formed designs and specs through natural
collaborative dialogue. Start by understanding the current project context,
then ask questions one at a time to refine the idea.

## Checklist
1. **Explore project context** — check files, docs, recent commits
2. **Ask clarifying questions** — one at a time, understand purpose/constraints
3. **Propose 2-3 approaches** — with trade-offs and your recommendation
4. **Present design** — get user approval after each section
5. **Write design doc** — save to docs/plans/
6. **Transition to implementation** — invoke writing-plans skill

この Skill は優れた設計原則を示しています：

• 明確で強い description：「You MUST use this before any creative work」で、関連する場面で確実に Claude が読み込むようにしている
• Hard Gate がある：設計が承認される前にコードを書くことを明確に禁止
• チェックリスト駆動：ステップごとに実行し、各ステップに明確な成果物がある
• 次の Skill への接続：完了後に自動的に writing-plans Skill に遷移し、パイプラインを形成

このリポジトリを ~/.claude/skills/ に直接クローンして使うことも、その構造を参考に独自の Skill を設計することもできます。

実践事例：Shareuhack の13個の Skills コンテンツパイプライン

理論よりも実際に動いているシステムを見ましょう。Shareuhack（今あなたが読んでいるこのサイト）は、Claude Code Skills を使って完全なコンテンツパイプラインを構築しています。トピック選定から公開まで、AI エージェントが協力して完了させます。

アーキテクチャ概要

グローバルルールは CLAUDE.md に：ブランドトーン（実践的な権威性、実務的な対話）、frontmatter フォーマット仕様、絶対禁止事項（捏造禁止、GitHub alerts 禁止）。これらは毎回の会話で必要なので、常時読み込みの CLAUDE.md に配置しています。

各ステージに1つの Skill：

/ideate → /research → /setup-notebook → /architect → /write → /content-review → /translate

各 Skill が1つのステージを担当します：/ideate で素早いスクリーニング（3分以内でやる価値があるか判断）、/research でサブエージェントを起動して深い市場調査、/architect で記事のアウトライン設計、/write でアウトラインに基づく原稿作成、/content-review で40点満点の二重視点レビュー、/translate で多言語対応を処理します。

3つの重要な設計判断

1. すべての Skill に HITL（Human-in-the-Loop）チェックポイント

各 Skill は実行完了後に強制的に一時停止し、ユーザーの確認を待ってから次のステージに進みます。これは技術的な制約ではなく、意図的な設計です。実際の使用経験から、AI がパイプライン全体を自動で実行した場合、最終的な出力品質は人間が各ステージで介入・調整した場合と比べて明らかに低くなります。

## HITL ルール
完了後は必ず停止し、要約を表示してユーザーの応答を待つ：
- `yes` と入力 → 次のステージへ
- `revise: [説明]` と入力 → 調整後に再確認
- `no` と入力 → 一時停止

2. サブエージェントで WebSearch のノイズを隔離

/research や /write のように外部情報が必要な Skill は、メインの会話で直接検索しません。代わりに独立したサブエージェントを起動して WebSearch を実行し、構造化された要約だけをメインの会話に返します。これにより、メインの context が検索結果のノイズで汚染されません。

3. Skills 間はパイプラインファイルでデータを受け渡し

各記事には content/pipeline/[slug].md ファイルがあります。各 Skill は実行完了後にこのファイルに出力を追記します。次の Skill が同じファイルを読むことで、前のステージの出力を引き継げます。context 経由でのデータ受け渡しよりも信頼性が高い方法です。context はセッション終了時に消えますが、パイプラインファイルは永続的に保存されるためです。

Context 予算管理

13個の Skills の description を合計しても context 予算を超えてはいけません。公式ドキュメントによると、Skills の context 予算は context window の2%で、フォールバック上限は16,000文字です。実務上の対策：

• 各 Skill の description は1〜2文（約50〜100文字）に収める
• /context で定期的に除外された Skill がないか確認
• 使用頻度の低い Skill は削除または統合を検討

効果

このシステムにより、「1記事あたり3時間かけて AI を手動でガイド」から「パイプラインを実行して約1時間で公開品質の原稿を産出」に変わりました。さらに重要なのは、品質が安定したことです。誰がパイプラインを起動しても、同じ品質ゲートを通過します。

リスク開示と注意事項

Skills は万能ではありません。知っておくべき制限事項があります：

Skill の読み込みは非決定的。 Claude は現在のタスクとの関連性に基づいて、Skill を読み込むかどうかを判断します。description が曖昧だったり、会話内容が Skill の説明と十分にマッチしなかったりすると、Claude がスキップする可能性があります。対策：明確で具体的な description を書き、user-invocable: true を設定して /command で手動トリガーできるようにしましょう。

Context 予算には上限がある。 Skills が多すぎると、一部の Skill が context から除外されます。/context コマンドでどの Skill が除外されたか確認できます。予算上限を調整するには、環境変数 SLASH_COMMAND_TOOL_CHAR_BUDGET を設定します。

メンテナンスコストは現実に存在する。 Skills は一度書いたら終わりではありません。プロジェクトの進化、ツールの更新、プロセスの変更に伴い、Skills は陳腐化します。私たちのアプローチ：月に一度 Skills レビューを行い、現状と合わなくなったものをチェックしています。

セキュリティへの配慮が必要。 allowed-tools フィールドで、Skill 実行時に Claude が使用できるツールを制限できます。デプロイやファイル削除など機密性の高い操作を含む Skill では、使用可能なツールの範囲を明示的に制限することを推奨します。

すべてを Skill にする必要はない。 一度だけ行うタスクなら、会話で直接説明すれば十分です。Skills の投資対効果は繰り返しの使用から生まれます。大まかな判断基準：同じワークフローを3回以上実行する見込みがあるなら、Skill にする価値があります。

まとめ

Skills は Claude Code を「毎回手動でガイドが必要なチャットツール」から「ワンクリックで起動できるワークフローエンジン」に変えます。核心的なコンセプトはシンプルです：Markdown でワークフローを書き、Claude にそれに従って実行させる。

おすすめの第一歩：最も頻繁に繰り返しているワークフロー（コードレビュー、週報作成、議事録の整理）を1つ特定し、10分かけて SKILL.md を書いてみてください。最初から完璧を目指す必要はありません。最もシンプルなバージョンから始めて、数回使った後に徐々に改善していきましょう。

より複雑な自動化システムを構築したい場合は、Hooks と組み合わせてイベント駆動のチェックを追加したり、サブエージェントを使って Skills 間の連携を構築したりできます。それらの上級トピックはぜひご自身で探索してみてください。