Claude Code Skillsで開発ワークフローを自動化する実践ガイド
この記事でわかること
- Claude Code Skillsの仕組みと3層プログレッシブディスクロージャの設計思想
- SKILL.mdファイルの構造・frontmatterフィールドの完全リファレンス
- 実務で使える5つのスキルパターン（ワークフロー自動化・MCP連携・反復改善など）
- スキルのテスト戦略とイテレーション手法
- Agent Skillsオープンスタンダードによるクロスプラットフォーム互換の活用方法
対象読者
- 想定読者: Claude CodeまたはAIコーディングツールを日常的に使う開発者
-
必要な前提知識:
- Claude Codeの基本操作（CLIでの対話、ファイル編集）
- Markdownの基本記法
- YAMLフロントマターの概念
- ターミナル操作の基礎
MLEの方へ: Skillsの仕組みはMLパイプラインの「設定ファイル駆動」に近い概念です。Pythonの
__init__.pyがパッケージの構造を定義するように、SKILL.mdがスキルの振る舞いを定義します。
結論・成果
Anthropicが2026年1月に公開した「The Complete Guide to Building Skills for Claude」と公式ドキュメントによると、Skillsを導入することで以下の効果が報告されています。
- トークン消費量: スキルなしの場合と比較して約50%削減（12,000トークン→6,000トークン）
- ワークフロー完了速度: 15回のやり取り→2回の確認のみ
- API呼び出し失敗率: 3回のリトライ→0回
- 開発者の学習コスト: 15〜30分で初めてのスキルを構築・テスト可能
これらの効果は、スキルの「プログレッシブディスクロージャ」設計によるものです。必要な情報だけをコンテキストウィンドウにロードすることで、トークン効率とタスク精度の両方を改善しています。
Skillsの基本を理解する
Claude Code Skillsとは、Claudeに特定のタスクやワークフローを教えるための命令セットです。SKILL.mdファイルを含むフォルダとして構成され、Claudeが自動的に認識・実行します。
Pythonの世界に例えると、スキルは「設定可能なデコレータ」のようなものです。関数そのもの（= Claudeの基本能力）は変わりませんが、デコレータ（= スキル）が振る舞いを拡張します。
スキルの構成要素
スキルは以下の構成を持ちます。
your-skill-name/
├── SKILL.md # メインの命令ファイル（必須）
├── scripts/ # 実行可能スクリプト（任意）
│ ├── process_data.py
│ └── validate.sh
├── references/ # 追加ドキュメント（任意）
│ ├── api-guide.md
│ └── examples/
└── assets/ # テンプレート等（任意）
└── report-template.md
ファイル名は必ず SKILL.md（大文字・小文字を厳密に区別）です。skill.md や SKILL.MD は認識されません。
配置場所と適用範囲
スキルの配置場所によって適用範囲が変わります。
| 配置場所 | パス | 適用範囲 |
|---|---|---|
| Enterprise | マネージド設定で配布 | 組織全体のユーザー |
| Personal | ~/.claude/skills/<skill-name>/SKILL.md |
自分の全プロジェクト |
| Project | .claude/skills/<skill-name>/SKILL.md |
そのプロジェクトのみ |
| Plugin | <plugin>/skills/<skill-name>/SKILL.md |
プラグイン有効化先 |
同名のスキルが複数の階層に存在する場合、Enterprise > Personal > Project の優先順位で上位が優先されます。Plugin スキルは plugin-name:skill-name のネームスペースを使うため、他の階層と衝突しません。
注意点: モノレポでは、サブディレクトリ内の .claude/skills/ も自動検出されます。たとえば packages/frontend/ のファイルを編集中であれば、packages/frontend/.claude/skills/ のスキルも認識されます。
3層プログレッシブディスクロージャ
Skillsの設計で最も重要な概念がプログレッシブディスクロージャ（段階的な情報開示）です。これにより、コンテキストウィンドウの消費を抑えつつ、必要な情報にアクセスできます。
| 層 | 内容 | ロードタイミング | トークンコスト |
|---|---|---|---|
| 第1層 | YAMLフロントマター（name, description） | セッション開始時に常時 | 約100トークン/スキル |
| 第2層 | SKILL.md本文 | Claudeが関連性ありと判断した時 | 最大約5,000トークン |
| 第3層 | 参照ファイル（references/, scripts/） | 明示的に参照された時のみ | 制限なし |
公式ドキュメントによると、スキルのdescriptionバジェットはコンテキストウィンドウの2%（フォールバック16,000文字）で動的にスケーリングされます。/context コマンドで、除外されたスキルがないか確認できます。
よくある間違い: SKILL.mdに全情報を詰め込むと、呼び出すたびに大量のトークンを消費します。公式ガイドラインでは SKILL.md本文は500行以下 を推奨しています。詳細なAPI仕様やサンプル集は references/ に分離しましょう。
SKILL.mdのフロントマターを設定する
SKILL.mdの冒頭にYAMLフロントマターを記述します。これがスキルの「メタデータ」であり、Claudeがスキルを発見・選択するための重要な情報源です。
最小構成
---
name: my-skill
description: What it does. Use when user asks to [specific phrases].
---
# スキルの命令をここに記述
name と description 以外のフィールドはすべてオプションです。
フロントマターフィールド一覧
| フィールド | 必須 | 説明 |
|---|---|---|
name |
いいえ | スキルの表示名。省略時はディレクトリ名を使用。小文字・数字・ハイフンのみ（最大64文字） |
description |
推奨 | スキルの用途とトリガー条件。Claudeはこれを見てスキルを選択する（最大1024文字） |
argument-hint |
いいえ | オートコンプリート時のヒント。例: [issue-number]
|
disable-model-invocation |
いいえ |
true でClaude自動呼び出しを禁止。手動 /name のみ |
user-invocable |
いいえ |
false で / メニューから非表示。バックグラウンド知識用 |
allowed-tools |
いいえ | スキル実行中にClaude が許可なく使えるツール |
model |
いいえ | スキル実行時に使用するモデル |
context |
いいえ |
fork でサブエージェントとして分離実行 |
agent |
いいえ |
context: fork 時のサブエージェントタイプ |
hooks |
いいえ | スキルライフサイクルにスコープされたフック |
descriptionの書き方（スキル成功の鍵）
descriptionフィールドはスキルの発見率を決定する最重要項目です。公式ベストプラクティスガイドでは、以下の構造を推奨しています。
[何をするか] + [いつ使うか] + [主要な機能]
良い例: 具体的でトリガーフレーズを含む
# 具体的かつアクション指向
description: Analyzes Figma design files and generates developer handoff documentation. Use when user uploads .fig files, asks for "design specs", "component documentation", or "design-to-code handoff".
# Linear連携のワークフロー
description: Manages Linear project workflows including sprint planning, task creation, and status tracking. Use when user mentions "sprint", "Linear tasks", "project planning", or asks to "create tickets".
悪い例: 曖昧、トリガー条件なし
# 曖昧すぎる
description: Helps with projects.
# トリガー条件がない
description: Creates sophisticated multi-page documentation systems.
# 技術用語のみでユーザーのフレーズがない
description: Implements the Project entity model with hierarchical relationships.
ポイント: descriptionは三人称で書きます。「I can help you...」や「You can use this to...」ではなく、「Processes Excel files and generates reports」のように記述してください。descriptionはシステムプロンプトに注入されるため、一人称や二人称は発見に悪影響を与えます。
呼び出し制御の設計
スキルの呼び出し元（ユーザーかClaudeか）を制御する2つのフィールドがあります。
| 設定 | ユーザーが呼び出し | Claudeが呼び出し | 用途 |
|---|---|---|---|
| デフォルト | 可能 | 可能 | 汎用スキル |
disable-model-invocation: true |
可能 | 不可 | デプロイ、コミットなど副作用のある操作 |
user-invocable: false |
不可 | 可能 | レガシーシステムの背景知識など |
なぜこの設計を選んだか: デプロイや本番環境への変更など、副作用のある操作はClaudeが自動実行すべきではありません。disable-model-invocation: true を設定することで、必ずユーザーの明示的な /deploy コマンドでのみ実行されます。
---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---
Deploy $ARGUMENTS to production:
1. Run the test suite
2. Build the application
3. Push to the deployment target
4. Verify the deployment succeeded
変数置換を活用する
スキル本文では動的な値を参照できます。
| 変数 | 説明 |
|---|---|
$ARGUMENTS |
スキル呼び出し時の全引数 |
$ARGUMENTS[N] / $N
|
N番目の引数（0始まり） |
${CLAUDE_SESSION_ID} |
現在のセッションID |
${CLAUDE_SKILL_DIR} |
スキルのディレクトリパス |
---
name: migrate-component
description: Migrate a component from one framework to another
---
Migrate the $0 component from $1 to $2.
Preserve all existing behavior and tests.
/migrate-component SearchBar React Vue と実行すると、$0 が SearchBar、$1 が React、$2 が Vue に置換されます。
高度なパターンを実装する
基本を押さえたら、より高度なパターンを見ていきましょう。公式ガイドでは5つの主要パターンが紹介されています。
パターン1: 動的コンテキスト注入
!`command` 構文を使うと、スキル本文がClaudeに送信される前にシェルコマンドを実行し、その出力を埋め込めます。
---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---
## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`
## Your task
Summarize this pull request...
この仕組みは前処理です。Claudeが受け取るのはコマンドの出力結果のみで、コマンド自体ではありません。
パターン2: サブエージェント実行（context: fork）
context: fork を設定すると、スキルが独立したサブエージェントとして実行されます。メインの会話コンテキストは共有されません。
---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---
Research $ARGUMENTS thoroughly:
1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references
agent フィールドには組み込みエージェント（Explore、Plan、general-purpose）または .claude/agents/ のカスタムエージェントを指定できます。
注意:
context: forkは明示的なタスク指示を持つスキルでのみ意味があります。「このAPIの規約に従って」のようなガイドラインだけのスキルでは、サブエージェントがアクション不能で空の結果を返します。
パターン3: マルチMCP連携ワークフロー
複数のMCPサーバーをまたぐ複雑なワークフローをスキルで自動化できます。
## Workflow: Design-to-Development Handoff
### Phase 1: Design Export (Figma MCP)
1. Export design assets from Figma
2. Generate design specifications
3. Create asset manifest
### Phase 2: Asset Storage (Drive MCP)
1. Create project folder in Drive
2. Upload all assets
3. Generate shareable links
### Phase 3: Task Creation (Linear MCP)
1. Create development tasks
2. Attach asset links to tasks
3. Assign to engineering team
### Phase 4: Notification (Slack MCP)
1. Post handoff summary to #engineering
2. Include asset links and task references
MCPツールを参照する際は、必ず完全修飾名（ServerName:tool_name）を使用してください。例: BigQuery:bigquery_schema、GitHub:create_issue。サーバープレフィックスなしでは、ツールが見つからないエラーが発生します。
パターン4: 反復改善ループ
出力品質をフィードバックループで向上させるパターンです。
## Iterative Report Creation
### Initial Draft
1. Fetch data via MCP
2. Generate first draft report
3. Save to temporary file
### Quality Check
1. Run validation script: `scripts/check_report.py`
2. Identify issues:
- Missing sections
- Inconsistent formatting
- Data validation errors
### Refinement Loop
1. Address each identified issue
2. Regenerate affected sections
3. Re-validate
4. Repeat until quality threshold met
### Finalization
1. Apply final formatting
2. Generate summary
3. Save final version
ハマりポイント: バリデーションスクリプトのエラーメッセージは具体的にしてください。「Validation failed」ではなく「Field 'signature_date' not found. Available fields: customer_name, order_total, signature_date_signed」のように、Claudeが修正方法を特定できる情報を含めます。
パターン5: ドメイン知識の埋め込み
スキルにドメイン固有の判断ロジックを組み込み、ツールアクセスを超えた専門知識を提供します。
## Payment Processing with Compliance
### Before Processing (Compliance Check)
1. Fetch transaction details via MCP
2. Apply compliance rules:
- Check sanctions lists
- Verify jurisdiction allowances
- Assess risk level
3. Document compliance decision
### Processing
IF compliance passed:
- Call payment processing MCP tool
- Apply appropriate fraud checks
- Process transaction
ELSE:
- Flag for review
- Create compliance case
スキルをテストしてイテレーションする
スキルを書いたら、実際のタスクでテストすることが重要です。公式ガイドでは3つのテスト領域をカバーすることを推奨しています。
テスト戦略の全体像
1. トリガーテスト
スキルが適切なタイミングでロードされるかを確認します。
Should trigger:
- "Help me set up a new ProjectHub workspace"
- "I need to create a project in ProjectHub"
- "Initialize a ProjectHub project for Q4 planning"
Should NOT trigger:
- "What's the weather in San Francisco?"
- "Help me write Python code"
- "Create a spreadsheet"
2. 機能テスト
出力が期待通りかを検証します。
Test: Create project with 5 tasks
Given: Project name "Q4 Planning", 5 task descriptions
When: Skill executes workflow
Then:
- Project created in ProjectHub
- 5 tasks created with correct properties
- All tasks linked to project
- No API errors
3. パフォーマンス比較
スキルの有無で効果を比較します。
| 指標 | スキルなし | スキルあり |
|---|---|---|
| ユーザーの指示回数 | 毎回詳細に指定 | 2回の確認のみ |
| やり取り回数 | 15往復 | 2往復 |
| API呼び出し失敗 | 3回のリトライ | 0回 |
| トークン消費 | 12,000 | 6,000 |
Claude A/B開発手法
公式ガイドが推奨する最も効果的な開発方法は、2つのClaudeインスタンスを使い分けることです。
- Claude A（設計者）: スキルの設計・改善を担当
- Claude B（テスター）: スキルを使って実際のタスクを実行
手順:
- Claude Aと一緒にタスクを完了し、繰り返し提供した情報を特定する
- Claude Aにスキル化を依頼する（「このパターンをスキルにして」）
- Claude B（スキルをロードした新しいセッション）で類似タスクをテストする
- Claude Bの失敗をClaude Aにフィードバックし、スキルを改善する
ポイント: Claudeモデルはスキルフォーマットをネイティブに理解しています。スキル作成用の特別なプロンプトは不要で、「Create a Skill that...」と依頼するだけで適切な構造のSKILL.mdが生成されます。
イテレーション時の判断基準
| シグナル | 問題 | 対策 |
|---|---|---|
| スキルがロードされない | description不足 | キーワードやトリガーフレーズを追加 |
| 無関係なクエリでトリガー | description過剰 | ネガティブトリガーを追加（「Do NOT use for...」） |
| 指示通りに動かない | 指示が冗長 | 箇条書きにする、詳細はreferences/に移動 |
| レスポンスが遅い | SKILL.mdが巨大 | 500行以下に抑え、references/に分離 |
スキルを配布・共有する
Agent Skillsオープンスタンダード
2025年12月、AnthropicはSkillsの仕様をAgent Skillsオープンスタンダードとして公開しました。これにより、同じSKILL.mdファイルが以下のツールで動作します。
- Claude Code
- Claude.ai
- Cursor
- Gemini CLI
- Codex CLI
ただし、一部のスキルは特定プラットフォームの機能に依存するため、compatibility フィールドで動作環境を明示できます。
配布方法
| 方法 | 対象 | 手順 |
|---|---|---|
| GitHubリポジトリ | オープンソース | 公開リポ + READMEでインストール手順を記載 |
| MCPドキュメント内 | MCP提供者 | MCPリポにスキルをバンドル |
| 組織マネージド | エンタープライズ | マネージド設定で全ユーザーに配布 |
Skills API（プログラマティック管理）
API経由でスキルを管理する場合、/v1/skills エンドポイントが利用できます。
| ユースケース | 推奨サーフェス |
|---|---|
| エンドユーザーが直接スキルを使う | Claude.ai / Claude Code |
| 手動テスト・イテレーション | Claude.ai / Claude Code |
| アプリケーションにスキルを組み込む | API |
| 大規模デプロイ | API |
| 自動パイプライン・エージェントシステム | API |
Messages APIのリクエストに container.skills パラメータを追加することで、プログラム的にスキルを適用できます。
よくある問題と解決方法
| 問題 | 原因 | 解決方法 |
|---|---|---|
| "Could not find SKILL.md" | ファイル名が不正（skill.md等） |
SKILL.md に正確にリネーム |
| "Invalid frontmatter" | YAML構文エラー |
--- デリミタを確認、引用符の閉じ忘れチェック |
| "Invalid skill name" | 名前にスペースや大文字 | kebab-caseに変更（例: my-cool-skill） |
| スキルが自動トリガーされない | descriptionが曖昧 | トリガーフレーズを具体的に追加 |
| スキルがトリガーされすぎる | descriptionが広すぎる | ネガティブトリガーを追加、スコープを明記 |
| 指示が無視される | 指示が冗長・埋もれている | 重要指示を先頭に、箇条書きにする |
| レスポンスが遅い | スキル内容が巨大 | 500行以下に抑制、references/に詳細を分離 |
| MCP呼び出し失敗 | ツール名にサーバープレフィックスなし |
ServerName:tool_name 形式に修正 |
制約として知っておくべきこと: 20〜50個以上のスキルを同時有効化すると、descriptionバジェットを超過してスキルが除外される場合があります。/context コマンドで確認し、必要に応じて SLASH_COMMAND_TOOL_CHAR_BUDGET 環境変数で上限を調整してください。
まとめと次のステップ
まとめ:
- Claude Code Skillsは SKILL.md + フォルダ構造 で構成され、3層プログレッシブディスクロージャによりトークン効率を最適化する
- descriptionフィールドが発見率を決定するため、「何をするか + いつ使うか + 具体的トリガー」を三人称で記述する
-
context: forkでサブエージェント実行、disable-model-invocationで手動限定呼び出し、allowed-toolsでツール制限など、制御機構が充実している - Agent Skillsオープンスタンダードにより、同じSKILL.mdがClaude Code・Cursor・Gemini CLI等で動作する
- テストは3段階（トリガー・機能・パフォーマンス）で行い、Claude A/B手法でイテレーションする
次にやるべきこと:
-
~/.claude/skills/に最初のスキルを作成し、/skill-nameで動作確認する - 日常の反復タスク（コミットメッセージ生成、PRレビュー、デプロイ等）をスキル化する
- awesome-claude-skills でコミュニティのスキルを参考にする
参考
- Extend Claude with skills - Claude Code Docs
- Skill authoring best practices - Claude API Docs
- The Complete Guide to Building Skills for Claude (PDF)
- Agent Skills - Claude API Docs
- GitHub - anthropics/skills
- GitHub - travisvn/awesome-claude-skills
- Skills explained - Claude Blog
注意: この記事はAI（Claude Code）により自動生成されました。内容の正確性については複数の情報源で検証していますが、実際の利用時は公式ドキュメントもご確認ください。