はじめに
Claude Codeを使っていて、こんな経験ありませんか？
- 「毎回同じプロンプトを打つのが面倒…」
- 「チームで統一した作業手順をClaude Codeに守らせたい」
- 「
/commitみたいな便利コマンドを自分でも作りたい」
これらの悩みを解決するのが Skills（スキル） です。
Skillsは、Claude Codeに自作のスラッシュコマンドを追加できる機能です。/deploy や /review のように、よく使う指示をコマンド化して、チームで共有することもできます。
この記事では、Skillsの基本から実践的な活用方法まで、網羅的に解説します。
Skillsとは
| 項目 | 内容 |
|---|---|
| 何か | Claude Codeに追加できるカスタムスラッシュコマンド |
| 形式 |
SKILL.md ファイル（Markdown + YAMLフロントマター） |
| 呼び出し |
/スキル名 で実行 |
| 共有 | gitにコミットしてチームで共有可能 |
| 仕様 | Agent Skills 標準に準拠 |
イメージとしては、「よく使うプロンプトを名前を付けて保存して、いつでも呼び出せるようにしたもの」です。
CLAUDE.mdが「プロジェクト全体のルール」だとすれば、Skillsは「特定のタスクに対する実行手順書」です。
Skillsの配置場所
Skillsはディレクトリの場所によってスコープが決まります。
| スコープ | パス | 適用範囲 |
|---|---|---|
| パーソナル | ~/.claude/skills/スキル名/SKILL.md |
自分の全プロジェクト |
| プロジェクト | .claude/skills/スキル名/SKILL.md |
現在のプロジェクトのみ |
パーソナルスキルは自分だけの便利コマンド、プロジェクトスキルはチームで共有するコマンドとして使い分けます。
Skillの作り方
ディレクトリ構成
.claude/skills/
└── スキル名/
├── SKILL.md # 必須：メインの指示ファイル
├── reference.md # 任意：参考資料
└── examples.md # 任意：使用例
1スキル = 1ディレクトリ です。SKILL.md が必須で、補足資料は任意で追加できます。
SKILL.md の書き方
---
name: review
description: コードレビューを実行する。PRの変更内容を分析して改善点を指摘する。
---
以下の手順でコードレビューを行ってください。
1. 変更されたファイルを確認する
2. コーディング規約に違反していないかチェックする
3. バグの可能性がある箇所を指摘する
4. 改善案を具体的に提示する
## レビュー観点
- 命名規則の一貫性
- エラーハンドリングの適切さ
- テストの有無
- パフォーマンスへの影響
ファイルの構造は以下の通りです。
| 部分 | 説明 |
|---|---|
--- で囲まれたYAMLフロントマター |
スキルのメタデータ（名前・説明など） |
| フロントマター以降のMarkdown | Claude Codeへの具体的な指示 |
フロントマターの設定項目
| フィールド | 型 | 説明 |
|---|---|---|
name |
string | スラッシュコマンドの名前。省略時はディレクトリ名が使われる。小文字・数字・ハイフンのみ（最大64文字） |
description |
string | スキルの説明。Claude Codeが自動的に呼び出すかどうかの判定にも使われる |
argument-hint |
string | 引数のヒント。補完時に [issue-number] のように表示される |
disable-model-invocation |
boolean |
true にすると、Claudeによる自動呼び出しを無効化する（ユーザーが手動で /スキル名 した時のみ実行） |
user-invocable |
boolean |
false にすると / メニューに表示されなくなる（Claudeの判断でのみ使われるバックグラウンド知識用） |
allowed-tools |
string[] | スキル実行時に許可なしで使えるツール。例: ["Read", "Grep", "Glob"]
|
context |
string |
"fork" を指定するとサブエージェントで実行される（メインのコンテキストに影響しない） |
agent |
string |
context: fork 時のサブエージェントタイプ。"Explore", "Plan", "general-purpose"
|
すべてのフィールドは任意です。最低限 description だけ書けば動きます。
引数の使い方
Skillsでは引数を受け取って、指示の中で使うことができます。
$ARGUMENTS：全引数
---
name: fix-issue
description: GitHub Issueを修正する
argument-hint: "[issue番号]"
---
GitHub Issue #$ARGUMENTS を修正してください。
1. Issueの内容を確認する
2. 原因を特定する
3. 修正を実装する
4. テストを書く
5. コミットする
実行例：
/fix-issue 42
→ Claude Codeは「GitHub Issue #42 を修正してください。」という指示を受け取ります。
$0, $1, $2...：個別引数
---
name: migrate
description: コンポーネントを別フレームワークに移行する
argument-hint: "[コンポーネント名] [移行元] [移行先]"
---
$0 コンポーネントを $1 から $2 に移行してください。
既存のテストも移行先のフレームワークに合わせて書き直してください。
実行例：
/migrate SearchBar React Vue
→ 「SearchBar コンポーネントを React から Vue に移行してください。」
呼び出し方法の制御
Skillsは「誰が呼び出せるか」を制御できます。
| 設定 | ユーザーが /スキル名 で実行 |
Claudeが自動判断で実行 | 用途 |
|---|---|---|---|
| デフォルト | ○ | ○ | 汎用スキル |
disable-model-invocation: true |
○ | × | デプロイなど副作用のある操作 |
user-invocable: false |
× | ○ | バックグラウンド知識 |
デフォルト（両方OK）
---
name: explain-code
description: コードをわかりやすく説明する
---
ユーザーが /explain-code と打っても、Claudeが「このコードの説明が必要だ」と判断しても、どちらでも実行されます。
手動のみ（disable-model-invocation）
---
name: deploy
description: 本番環境にデプロイする
disable-model-invocation: true
---
/deploy と明示的に打った場合のみ実行されます。Claudeが勝手にデプロイすることはありません。
副作用のある操作（デプロイ、メッセージ送信、データ削除など）にはこの設定を使いましょう。
Claude専用（user-invocable: false）
---
name: legacy-system
description: レガシーシステムのAPI仕様。古いAPIを扱う時に参照する。
user-invocable: false
---
ユーザーからは呼び出せませんが、Claudeがレガシーシステムに関する質問を受けた時に自動的にこのスキルの内容を参照します。
プロジェクト固有の知識（API仕様、アーキテクチャの経緯、ドメイン知識など）をClaude Codeに教えるのに便利です。
動的コンテキスト注入
SKILL.md内で、シェルコマンドの実行結果をClaude Codeへの指示に埋め込むことができます。
!`コマンド` の形式で書くと、コマンドの出力結果に置き換えられます。
---
name: pr-review
description: 現在のPRをレビューする
---
## PRの変更内容
変更されたファイル:
!`git diff --name-only HEAD~1`
差分:
!`git diff HEAD~1`
## レビュー指示
上記の変更内容をレビューしてください。
- バグの可能性
- 設計上の問題点
- テストの不足
/pr-review を実行すると、git diff の出力結果が自動的に埋め込まれた状態でClaude Codeに渡されます。
サブエージェント実行
context: fork を指定すると、スキルが独立したサブエージェントで実行されます。
---
name: deep-research
description: コードベースを徹底的に調査する
context: fork
agent: Explore
---
$ARGUMENTS について、以下の観点でコードベースを調査してください。
1. 関連するファイルをすべて特定する
2. データフローを追跡する
3. 依存関係を整理する
4. 調査結果をまとめる
サブエージェントの種類
| agent | 用途 | 使えるツール |
|---|---|---|
Explore |
読み取り専用の調査 | Read, Grep, Glob など |
Plan |
設計・計画の策定 | Read, Grep, Glob など |
general-purpose |
汎用（デフォルト） | すべてのツール |
サブエージェントの利点は、メインの会話コンテキストを消費しないことです。大量のファイルを読み込む調査タスクでも、メインの会話には結果だけが返ります。
実践：便利なSkill例
1. コミットスキル（日本語コミットメッセージ）
.claude/skills/jp-commit/SKILL.md
---
name: jp-commit
description: 日本語でgitコミットを作成する
disable-model-invocation: true
---
以下の手順でコミットしてください。
1. `git status` と `git diff` で変更内容を確認
2. 変更内容を日本語で要約し、以下の形式でコミットメッセージを作成:
形式: `[種別] 概要`
種別:
- 機能追加 → `[feat]`
- バグ修正 → `[fix]`
- リファクタ → `[refactor]`
- テスト → `[test]`
- ドキュメント → `[docs]`
- その他 → `[chore]`
例: `[feat] ユーザー登録画面にバリデーションを追加`
3. 関連するファイルのみステージング（`git add -A` は使わない）
4. コミットを実行
使い方：
/jp-commit
2. コンポーネント生成スキル（React）
.claude/skills/new-component/SKILL.md
---
name: new-component
description: Reactコンポーネントを規約に沿って生成する
argument-hint: "[コンポーネント名]"
---
$ARGUMENTS という名前のReactコンポーネントを作成してください。
## ファイル構成
src/components/$ARGUMENTS/
├── $ARGUMENTS.tsx # コンポーネント本体
├── $ARGUMENTS.test.tsx # テスト
└── index.ts # エクスポート
## コンポーネントテンプレート
- 関数コンポーネント（named export）
- Props は interface で定義
- Tailwind CSS でスタイリング
- JSDoc コメントを付与
## テストテンプレート
- React Testing Library を使用
- レンダリングテストを最低1つ
- Props のテストを最低1つ
使い方：
/new-component UserProfile
3. API仕様の参照スキル（バックグラウンド知識）
.claude/skills/api-conventions/SKILL.md
---
name: api-conventions
description: APIエンドポイントの設計規約。API関連のコードを書く時に参照する。
user-invocable: false
---
## API設計規約
### URLパス
- リソース名は複数形: `/api/users`, `/api/posts`
- ネストは2階層まで: `/api/users/:id/posts`
- ケバブケース: `/api/user-profiles`
### レスポンス形式
```json
{
"success": true,
"data": { ... },
"meta": {
"page": 1,
"totalPages": 10,
"totalCount": 100
}
}
エラーレスポンス
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "入力値が不正です",
"details": [ ... ]
}
}
ステータスコード
- 200: 成功
- 201: 作成成功
- 400: バリデーションエラー
- 401: 認証エラー
- 403: 権限エラー
- 404: リソースなし
- 500: サーバーエラー
このスキルは `user-invocable: false` なので、ユーザーが明示的に呼び出すことはできません。しかし、Claude CodeがAPI関連のコードを書く時に、自動的にこの規約を参照して従います。
### 4. 調査スキル（サブエージェント）
~/.claude/skills/investigate/SKILL.md
```markdown
---
name: investigate
description: 特定のキーワードに関連するコードを徹底的に調査する
argument-hint: "[調査キーワード]"
context: fork
agent: Explore
---
「$ARGUMENTS」に関連するコードを調査してください。
## 調査手順
1. Grepで関連ファイルを検索
2. 各ファイルの該当箇所を読み取り
3. データフロー・呼び出し関係を整理
## レポート形式
### 関連ファイル一覧
| ファイル | 役割 | 関連度 |
|---------|------|-------|
| ... | ... | 高/中/低 |
### データフロー
入力 → 処理A → 処理B → 出力
### まとめ
- 概要（3行以内）
- 注意点
使い方：
/investigate 認証フロー
サブエージェントで実行されるので、大量のファイルを読み込んでもメインの会話コンテキストを圧迫しません。
5. PRサマリースキル（動的コンテキスト）
.claude/skills/pr-summary/SKILL.md
---
name: pr-summary
description: 現在のブランチの変更をPR用にまとめる
disable-model-invocation: true
---
## 現在の変更内容
変更ファイル一覧:
!`git diff main --name-only 2>/dev/null || echo "(mainブランチとの差分なし)"`
コミット履歴:
!`git log main..HEAD --oneline 2>/dev/null || echo "(コミットなし)"`
## タスク
上記の変更内容を分析して、以下の形式でPRの説明文を作成してください。
```markdown
## 概要
（変更の目的を1〜2文で）
## 変更内容
- （変更点を箇条書き）
## テスト方法
- （動作確認の手順）
使い方：
/pr-summary
## Skillsの権限制御
settings.jsonでスキルの実行権限を細かく制御できます。
### 特定のスキルだけ許可
```json
{
"permissions": {
"allow": [
"Skill(jp-commit)",
"Skill(new-component *)"
]
}
}
特定のスキルを禁止
{
"permissions": {
"deny": ["Skill(deploy *)"]
}
}
すべてのスキルを禁止
{
"permissions": {
"deny": ["Skill"]
}
}
CLAUDE.mdとの使い分け
| CLAUDE.md | Skills | |
|---|---|---|
| 役割 | プロジェクト全体のルール・方針 | 特定タスクの実行手順 |
| 読み込み | セッション開始時に常に読み込まれる | 呼び出し時のみ読み込まれる |
| 書く内容 | 技術スタック、規約、禁止事項 | 手順書、テンプレート、チェックリスト |
| 例 | 「TypeScriptを使う」「インデントは2スペース」 | 「/deploy で本番デプロイを実行」 |
CLAUDE.mdに「何を守るか」を書き、Skillsに「どう実行するか」を書く、という使い分けがおすすめです。
トラブルシューティング
| 問題 | 原因と対策 |
|---|---|
/スキル名 を打っても表示されない |
ディレクトリ構成を確認。~/.claude/skills/スキル名/SKILL.md または .claude/skills/スキル名/SKILL.md に配置されているか |
| Claudeが勝手にスキルを実行してしまう |
disable-model-invocation: true をフロントマターに追加する |
| スキルが多すぎて一覧が見づらい | スキルの説明文にはコンテキストウィンドウの2%という文字数制限がある。不要なスキルは削除するか user-invocable: false にする |
| 引数が渡されない |
$ARGUMENTS や $0 を使っているか確認。実行時に /スキル名 引数 の形式で渡す |
まとめ
| ポイント | 内容 |
|---|---|
| Skillsとは | 自作スラッシュコマンド。SKILL.md で定義する |
| 配置場所 |
~/.claude/skills/（パーソナル）or .claude/skills/（プロジェクト） |
| 必須ファイル |
SKILL.md（YAML フロントマター + Markdown指示） |
| 引数 |
$ARGUMENTS（全引数）、$0, $1...（個別引数） |
| 動的コンテキスト |
!`コマンド` でシェルの実行結果を埋め込み |
| サブエージェント |
context: fork で独立実行（コンテキスト節約） |
| 呼び出し制御 |
disable-model-invocation / user-invocable
|
Skillsを使えば、チーム全員が同じ品質で作業を実行できるようになります。よく使うプロンプトをSkill化して、開発ワークフローを効率化しましょう。
参考
@kotaro_ai_lab
AI活用や開発効率化について発信しています。フォローお気軽にどうぞ！