Claude Code Skillsの使い方 - カスタムスキルで開発ワークフローを自動化

はじめに

AIコーディングツールの活用が進む中、開発現場では「毎回同じ指示を書くのが面倒」「チーム全員が同じ品質でAIを使えるようにしたい」という課題が出てきています。Anthropicが提供するCLIツールClaude Codeには、この課題を解決する**Skills（スキル）**という機能があります。

Skillsは、よく使うプロンプトや作業手順を再利用可能なスラッシュコマンドとしてパッケージ化する仕組みです。たとえば /review と入力するだけでコードレビューが始まり、/new-post でブログ記事のテンプレートが生成されるといった具合に、チーム固有のワークフローをコマンド1つで呼び出せます。

この記事では、Claude Code Skillsの基本概念から作成方法、実践的な活用事例まで詳しく解説します。Claude Code Agent Teamと組み合わせることで、さらに高度な開発自動化も実現できます。

Claude Code Skillsとは

スキルの基本概念

Claude Code Skillsは、カスタムのスラッシュコマンドを定義してClaude Codeの機能を拡張する仕組みです。各スキルはSKILL.mdというMarkdownファイルを中心に構成され、Claudeに対する指示（プロンプト）、使用するツールの制限、実行モードなどを設定できます。

スキルの核となるのは**プログレッシブ・ディスクロージャー（段階的情報開示）**という設計思想です。情報は3段階で読み込まれます。

メタデータ（約100トークン）: スキル名と説明文だけが起動時に読み込まれる
コア命令（5,000トークン以下推奨）: スキルが呼び出されたときにSKILL.mdの本文が読み込まれる
補助ファイル（必要時のみ）: テンプレートやリファレンスなどが必要に応じて追加で読み込まれる

この設計により、多数のスキルを登録してもClaude Codeのコンテキストウィンドウを圧迫しません。スキルが実際に使われるまで、最小限の情報しかメモリに載らないのです。

スラッシュコマンドとしての呼び出し

スキルの呼び出し方法は2種類あります。

ユーザーによる直接呼び出しでは、Claude Codeのプロンプトで /スキル名 と入力します。引数を渡すこともでき、たとえば /fix-issue 123 のように使います。タブ補完にも対応しており、/ を入力すると利用可能なスキル一覧が表示されます。

Claudeによる自動呼び出しでは、会話の文脈からClaudeが適切なスキルを判断して自動的に読み込みます。たとえば「このコードの仕組みを教えて」と質問すると、コード説明用のスキルが自動で有効化されるといった動作です。

呼び出し方法はフロントマターで制御できます。

設定	ユーザー呼び出し	Claude自動呼び出し
デフォルト	可	可
`disable-model-invocation: true`	可	不可
`user-invocable: false`	不可	可

デプロイやコミットのような副作用を伴うスキルには disable-model-invocation: true を設定し、意図しない自動実行を防ぐのが安全です。

Skillsの仕組み

スキルファイルの構造

スキルはディレクトリ単位で管理されます。最小構成はSKILL.mdファイル1つですが、補助ファイルを追加してより高機能なスキルを構築できます。

skill-name/
├── SKILL.md           # メイン命令ファイル（必須）
├── template.md        # テンプレート（任意）
├── examples/
│   └── sample.md      # 出力例（任意）
├── scripts/
│   └── validate.sh    # 実行スクリプト（任意）
├── references/
│   └── REFERENCE.md   # 詳細ドキュメント（任意）
└── assets/
    └── schema.json    # 静的リソース（任意）

SKILL.mdはYAMLフロントマターとMarkdown本文の2部構成です。

---
name: explain-code
description: コードの仕組みを図解と例え話で分かりやすく説明する
---

コードを説明する際は、以下の手順に従ってください。

1. **例え話から始める**: コードの動作を日常のものに例える
2. **図を描く**: ASCII アートでデータの流れを示す
3. **ステップごとに解説**: 処理を順番に説明する
4. **よくある落とし穴**: 誤解しやすいポイントを指摘する

スキルの配置場所とスコープ

スキルは配置場所によってスコープが変わります。

スコープ	パス	適用範囲
個人	`~/.claude/skills/スキル名/SKILL.md`	自分の全プロジェクト
プロジェクト	`.claude/skills/スキル名/SKILL.md`	そのプロジェクトのみ
プラグイン	`プラグイン名/skills/スキル名/SKILL.md`	プラグイン有効時
エンタープライズ	管理設定から配布	組織全体

プロジェクトスコープが最も一般的な使い方です。.claude/skills/ ディレクトリをGitリポジトリにコミットすれば、チーム全員が同じスキルを使えます。個人スコープはエディタ設定やコードフォーマットの好みなど、個人的な作業スタイルに関わるスキルに向いています。

名前が衝突した場合の優先順位は、エンタープライズ > 個人 > プロジェクトの順です。プラグインのスキルは プラグイン名:スキル名 という名前空間を持つため衝突しません。

プロンプトの設計

効果的なスキルを作るには、SKILL.mdの本文（プロンプト）の設計が重要です。

説明文（description）は具体的に書くことが最も大切なポイントです。Claudeはこの説明文をもとに自動呼び出しの判断をします。

# 悪い例
description: PDFを扱う

# 良い例
description: PDFファイルからテキストと表を抽出し、PDFフォームに入力する。PDF関連の作業で使用。

本文は500行以内に収めるのが推奨です。詳細なリファレンスは references/ ディレクトリに分離し、必要なときだけ参照させます。

コンテキストの受け渡し

スキルでは、外部データを動的に注入する仕組みがあります。

引数の受け渡しには変数置換を使います。

---
name: fix-issue
description: GitHubのIssueを修正する
argument-hint: "[issue番号]"
---

Issue #$ARGUMENTS を修正してください。

1. まずIssueの内容を確認する
2. 関連するコードを特定する
3. 修正を実装する
4. テストを追加する

$ARGUMENTS はスキル呼び出し時の引数全体に置換されます。$0、$1 で個別の引数にもアクセスできます。

動的コンテキスト注入では、!`コマンド` 構文でシェルコマンドの出力をスキルに埋め込めます。

---
name: pr-summary
description: PRの変更内容を要約する
---

## PRの情報
- 差分: !`gh pr diff`
- 変更ファイル: !`gh pr diff --name-only`

上記のPR情報をもとに、変更内容を要約してください。

この構文はスキル読み込み時にシェルコマンドが実行され、その出力で置換されます。Claudeには実行結果だけが渡されるため、最新のデータに基づいた処理が可能です。

スキルの作成方法

基本的なスキルの作り方

実際にスキルを作成する手順を見ていきましょう。ここでは、コードレビュースキルを例に解説します。

ステップ1: ディレクトリを作成する

mkdir -p .claude/skills/review

ステップ2: SKILL.mdを作成する

---
name: review
description: コードの品質、セキュリティ、パフォーマンスを観点にレビューする
argument-hint: "[ファイルパス]"
---

指定されたコードをレビューしてください。以下の観点で確認します。

## レビュー観点

### 1. コード品質
- 命名規則は適切か
- 関数の責務は単一か
- 重複コードはないか

### 2. セキュリティ
- 入力バリデーションは適切か
- SQLインジェクションのリスクはないか
- 機密情報がハードコードされていないか

### 3. パフォーマンス
- N+1クエリはないか
- 不要なループや計算はないか
- メモリリークのリスクはないか

## 出力形式

各観点について以下の形式で報告してください。

- **問題の深刻度**: Critical / Warning / Info
- **該当箇所**: ファイル名と行番号
- **問題の説明**: 何が問題か
- **修正案**: どう修正すべきか

ステップ3: 動作確認する

Claude Codeで /review src/main.ts と入力し、期待通りの動作をするか確認します。

プロジェクト固有スキルの設定

プロジェクトの技術スタックや開発規約に合わせたスキルを作ることで、チーム全体のAI活用品質を均一化できます。

たとえば、特定のフレームワークに合わせたコンポーネント生成スキルは以下のようになります。

---
name: new-component
description: プロジェクトの規約に沿ったReactコンポーネントを作成する
argument-hint: "[コンポーネント名]"
---

## コンポーネント作成ルール

以下のプロジェクト規約に従ってReactコンポーネントを作成してください。

- ディレクトリ: `src/components/$0/`
- ファイル構成: `index.tsx`（本体）、`styles.module.css`（スタイル）、`$0.test.tsx`（テスト）
- スタイル: CSS Modules を使用
- テスト: Vitest + Testing Library
- 命名: PascalCase

## テンプレート

references/component-template.tsx のテンプレートに従って生成してください。

このスキルをリポジトリにコミットしておけば、新しいメンバーもすぐにプロジェクトの規約に沿ったコンポーネントを生成できます。

高度なスキル設計のポイント

サブエージェントでの実行（context: fork）

context: fork を設定すると、スキルは独立したサブエージェントとして実行されます。メインの会話コンテキストから分離されるため、大量の情報を処理するスキルや、メインの会話を汚したくない場合に有効です。

---
name: deep-research
description: コードベースを徹底調査する
context: fork
agent: Explore
---

$ARGUMENTS について徹底的に調査してください。

1. Glob と Grep で関連ファイルを検索
2. コードを読み込んで分析
3. ファイルパスを明記した調査結果を報告

agent フィールドで実行環境を指定できます。Explore は読み取り専用の探索に、Plan は設計に、general-purpose は汎用的な処理に適しています。

ツール制限（allowed-tools）

スキルが使用できるツールを制限して安全性を高められます。

---
name: audit
description: コードベースのセキュリティ監査（読み取り専用）
allowed-tools: Read, Grep, Glob
---

この設定により、スキルの実行中はファイルの読み取りと検索のみが許可され、編集や書き込みはブロックされます。

実践的な活用事例

コード生成の自動化

プロジェクトの定型的なコード生成を自動化するスキルは、最も効果が実感しやすい活用例です。

APIエンドポイント生成スキルの例:

---
name: new-api
description: REST APIエンドポイントのCRUDコードを生成する
argument-hint: "[リソース名]"
---

$0 リソースのREST APIエンドポイントを作成してください。

## 生成するファイル
- `src/routes/$0.ts` - ルーティング
- `src/controllers/$0Controller.ts` - コントローラー
- `src/services/$0Service.ts` - ビジネスロジック
- `src/tests/$0.test.ts` - テスト

## 規約
- フレームワーク: Express
- バリデーション: Zod
- ORM: Prisma
- テスト: Vitest
- エラーハンドリング: 共通エラーハンドラを使用

このスキルにより、/new-api users と入力するだけで、プロジェクトの規約に沿った4ファイルが一括生成されます。

レビュー・監査ワークフロー

品質管理のスキルは、チーム開発での価値が特に高い活用例です。

SEO監査スキルの実例: 当サイト（Harmonic Society Tech）では、/seo-check スキルを使って記事の品質を自動監査しています。タイトルの文字数、メタディスクリプションの長さ、見出し構造、内部リンクの有無など20項目をチェックし、ERROR / WARNING / INFO のレベル別にレポートを出力します。

このようなスキルをプロジェクトに組み込むことで、人手によるチェックリストの確認作業を自動化し、見落としを防げます。

PRレビュースキルの例: 動的コンテキスト注入を活用し、PRの差分を自動取得してレビューするスキルも効果的です。

---
name: pr-review
description: PRの差分をレビューし、問題点と改善案を報告する
disable-model-invocation: true
---

## PR情報
- 差分: !`gh pr diff`
- 説明: !`gh pr view --json title,body`

上記のPR情報をもとに、以下の観点でレビューしてください。
1. バグの可能性がある箇所
2. セキュリティ上の懸念
3. パフォーマンスへの影響
4. テストカバレッジの不足

ドキュメント生成

コードからドキュメントを自動生成するスキルも、実用性の高い活用例です。

---
name: gen-docs
description: ソースコードからAPIドキュメントを生成する
argument-hint: "[ファイルパス]"
context: fork
agent: Explore
---

$ARGUMENTS のソースコードを読み、APIドキュメントを生成してください。

## 出力形式
- 各関数/メソッドの説明
- パラメータの型と説明
- 戻り値の型と説明
- 使用例（コードブロック）
- エッジケースの注意点

context: fork と agent: Explore を使うことで、メインの会話を中断せずにバックグラウンドで大規模なコード解析を実行できます。

Agent Skills オープンスタンダードとの関係

Claude Code Skillsの基盤となっているのが、Anthropicが2025年12月に公開したAgent Skillsオープンスタンダードです。このスタンダードはagentskills.ioで仕様が公開されており、Claude Code以外のAIツールでも動作するスキルを作成できます。

OpenAI、Cursor、GitHub Copilotなど複数のプラットフォームがこのスタンダードを採用しています。つまり、スタンダード準拠のスキルを作成すれば、ツールを乗り換えてもスキル資産を再利用できるのです。

ただし、Claude Code独自の拡張機能（context: fork、hooks、動的コンテキスト注入など）はスタンダードには含まれていないため、クロスプラットフォームで使いたい場合はベースとなる仕様のみを使うように注意が必要です。

導入時の注意点とベストプラクティス

スキル設計のポイント

説明文は具体的に: Claudeが自動呼び出しを判断する手がかりになるため、何をするスキルなのか明確に記述する
本文は簡潔に: SKILL.mdは500行以内を目安にし、詳細はreferences/に分離する
1スキル1責務: 複数の機能を1つのスキルに詰め込まず、単機能のスキルを組み合わせる設計にする

安全性の確保

副作用のあるスキルにはdisable-model-invocation: trueを設定: デプロイ、コミット、メッセージ送信など、意図しない自動実行を防ぐ
allowed-toolsでツールを制限: 読み取り専用のスキルにはRead, Grep, Globのみを許可するなど、最小権限の原則を適用する
重要な操作の前にユーザー確認を組み込む: スキルのプロンプト内で「実行前に必ずユーザーに確認を取ること」と明記する

チーム運用

プロジェクトスキルはGitにコミット: .claude/skills/ をバージョン管理することで、チーム全員が同じスキルを使える
命名規約を決める: verb-noun 形式（例: review-code、gen-docs）など、チームで統一する
コンテキスト予算に注意: スキルの説明文はコンテキストウィンドウの約2%を占めるため、大量のスキルを登録する場合は /context コマンドで使用量を確認する

まとめ

Claude Code Skillsは、繰り返しのプロンプト入力をなくし、チーム全体でAI活用の品質を均一化できる機能です。Markdownファイル1つから始められる手軽さがありながら、サブエージェント実行やツール制限、動的コンテキスト注入といった高度な機能も備えています。

導入の第一歩としては、チームで頻繁に行う作業（コードレビュー、テンプレート生成、品質チェックなど）を1つ選び、シンプルなスキルとして定義することをお勧めします。効果を実感できたら、徐々にスキルの数と高度さを増やしていけばよいでしょう。

Agent Skillsオープンスタンダードの採用により、スキルは特定のツールに縛られない汎用的な資産になりつつあります。今のうちからスキル作成のノウハウを蓄積しておくことは、AI時代の開発者キャリアにおいても価値ある投資といえるでしょう。

Claude Codeの他の機能については、Agent Teamによるマルチエージェント開発の記事もあわせてご覧ください。