Claude Code Skillsとは

Claude Code Skillsは、繰り返し使うワークフローや指示をカスタムスラッシュコマンドとして登録できる機能です。

例えば、コードレビューの手順をスキルとして登録しておけば、/reviewと打つだけでClaudeが毎回同じ品質基準でレビューしてくれます。デプロイ手順、テスト実行、ドキュメント生成など、チームで統一したいワークフローをすべてスキル化できます。

SkillsはAgent Skillsオープン標準に準拠しており、Claude Code以外のAIツールとも互換性があります。

基本的な仕組み

スキルは.claude/skills/ディレクトリにSKILL.mdファイルを置くだけで作成できます。

.claude/skills/review/
└── SKILL.md

この構成で、Claude Codeで/reviewと入力するとスキルが発動します。

2つの呼び出しモード

| モード | 説明 | |--------|------| | 手動呼び出し | /skill-nameとタイプして直接起動 | | 自動呼び出し | Claudeがスキルのdescriptionを読み、関連する文脈で自動適用 |

SKILL.mdの書き方

スキルの本体はYAMLフロントマター + マークダウンで構成されます。

最小構成

---
name: explain-code
description: コードを図と例え話で解説する
---

コードを解説するときは以下の手順で：

1. 日常的な例えで概要を説明
2. ASCIIアートでフローを図示
3. ステップごとにコードを解説
4. よくある間違いを指摘

これだけで/explain-codeコマンドが使えるようになります。

フロントマターのオプション一覧

---
name: fix-issue              # コマンド名（英数字・ハイフンのみ、64文字以内）
description: GitHubのissueを修正する  # 説明（自動呼び出しの判定に使われる）
argument-hint: [issue-number]        # 引数のヒント表示
disable-model-invocation: true       # Claudeの自動呼び出しを無効化
user-invocable: true                 # /メニューに表示するか
allowed-tools: Read, Grep, Glob      # 許可するツール
model: sonnet                        # 使用するモデル
context: fork                        # 分離コンテキストで実行
agent: Explore                       # サブエージェントの種類
---

| フィールド | 必須 | 説明 | |-----------|------|------| | name | いいえ | コマンド名。省略時はディレクトリ名 | | description | 推奨 | スキルの説明。Claudeの自動判定に使われる | | argument-hint | いいえ | 補完時に表示されるヒント | | disable-model-invocation | いいえ | trueで自動呼び出しを無効化 | | user-invocable | いいえ | falseで/メニューから非表示 | | allowed-tools | いいえ | スキル実行時に許可するツール | | context | いいえ | forkで分離実行 |

引数の渡し方

スキルには引数を渡せます。

$ARGUMENTSで全引数を取得

---
name: fix-issue
description: GitHub Issueを修正する
argument-hint: [issue-number]
---

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

1. `gh issue view $ARGUMENTS` でIssueの内容を確認
2. 原因を調査
3. 修正を実装
4. テストを書く
5. コミットを作成

/fix-issue 42
# → $ARGUMENTS が "42" に置換される

$0, $1, $2で個別引数を取得

---
name: migrate-component
description: コンポーネントをフレームワーク間で移行
---

$0 コンポーネントを $1 から $2 に移行してください。
既存のすべての挙動とテストを維持すること。

/migrate-component SearchBar React Vue
# → $0=SearchBar, $1=React, $2=Vue

スキルの配置場所

プロジェクトスキル（チームで共有）

your-project/
└── .claude/skills/
    ├── review/SKILL.md
    └── deploy/SKILL.md

Gitにコミットすれば、チームメンバー全員が同じスキルを使えます。

パーソナルスキル（自分だけ）

~/.claude/skills/
├── explain-code/SKILL.md
└── quick-test/SKILL.md

全プロジェクトで使えるユーティリティ的なスキルに最適。

モノレポ対応

packages/
  frontend/.claude/skills/frontend-lint/SKILL.md
  backend/.claude/skills/backend-test/SKILL.md

サブディレクトリごとにスキルを定義でき、作業中のパッケージに応じて自動で読み込まれます。

呼び出し制御

| 設定 | ユーザーが呼べる | Claudeが自動で呼べる | |------|:---:|:---:| | デフォルト | はい | はい | | disable-model-invocation: true | はい | いいえ | | user-invocable: false | いいえ | はい |

使い分け：

• デプロイのような危険な操作 → disable-model-invocation: trueで手動のみ
• API規約のような背景知識 → user-invocable: falseでClaude自動参照のみ

実用的なスキル例

1. コードレビュースキル

---
name: review
description: コードレビューを実行する。PR差分やコード変更のレビュー時に使用。
allowed-tools: Read, Grep, Glob
---

以下の観点でコードレビューを実施：

## チェック項目
- セキュリティ：SQLインジェクション、XSS、認証漏れ
- パフォーマンス：N+1クエリ、不要な再レンダリング
- 可読性：命名、関数の長さ、コメントの過不足
- テスト：カバレッジ、エッジケース

## 出力フォーマット
各指摘を以下の形式で出力：
- 🔴 Critical：即修正必須
- 🟡 Warning：修正推奨
- 🔵 Suggestion：改善提案

2. PR作成スキル

---
name: create-pr
description: 変更内容からPull Requestを作成する
disable-model-invocation: true
allowed-tools: Bash(git *), Bash(gh *)
---

PRを作成してください：

1. `git diff main...HEAD` で変更内容を確認
2. 変更の要約を作成
3. 以下のフォーマットでPRを作成：

## Summary
- 変更の概要を箇条書き

## Test Plan
- テスト項目を箇条書き

3. 動的コンテキスト注入スキル

---
name: pr-summary
description: 現在のPRを要約する
context: fork
agent: Explore
---

## PRコンテキスト
- PR差分: !`gh pr diff`
- PRコメント: !`gh pr view --comments`
- 変更ファイル: !`gh pr diff --name-only`

上記のPR情報を要約してください。

!`コマンド`構文で、スキル読み込み時にシェルコマンドの出力を動的に注入できます。

4. API規約スキル（背景知識型）

---
name: api-conventions
description: このプロジェクトのAPI設計規約。API実装時に自動参照。
user-invocable: false
---

## API設計規約

- RESTful命名規則を使用
- レスポンスは `{ data, error, meta }` 形式
- エラーは `{ code, message, details }` 形式
- すべての入力パラメータをバリデーション
- ページネーションは cursor ベース

user-invocable: falseなので/メニューには表示されませんが、ClaudeがAPI関連の作業をする際に自動的に参照します。

5. サブエージェント調査スキル

---
name: deep-research
description: トピックをコードベース全体で徹底調査
context: fork
agent: Explore
---

$ARGUMENTS について徹底的に調査：

1. Glob/Grepで関連ファイルを網羅的に検索
2. コードを読んで分析
3. ファイルパス付きで調査結果をまとめる
4. パターンと不整合を指摘

context: forkで分離コンテキストで実行されるため、メインの会話を汚しません。

ファイル構造のベストプラクティス

大きなスキルは補助ファイルに分割できます。

~/.claude/skills/codebase-visualizer/
├── SKILL.md              # メインの指示（500行以内推奨）
├── reference.md          # 詳細なリファレンス
├── examples/
│   └── sample-output.md  # 出力例
└── scripts/
    └── visualize.py      # 実行スクリプト

SKILL.mdから補助ファイルを参照すれば、Claudeが必要に応じて読み込みます。

拡張シンキング

スキル内にultrathinkキーワードを含めると、Claude Codeの拡張思考モードが有効になります。

---
name: complex-analysis
description: 複雑な問題を深く分析する
---

ultrathink でこの問題を分析してください...

パーミッション制御

スキルの使用をパーミッション設定で制御できます。

{
  "permissions": {
    "allow": ["Skill(review)", "Skill(create-pr *)"],
    "deny": ["Skill(deploy *)"]
  }
}

特定のスキルだけを許可/拒否することで、チーム内での安全な運用が可能です。

トラブルシューティング

スキルが自動で発動しない

• descriptionにユーザーが自然に使うキーワードを含めているか確認
• /メニューにスキルが表示されるか確認
• 直接/skill-nameで呼び出して動作確認

スキルが頻繁に自動発動しすぎる

• descriptionをより具体的に書く
• disable-model-invocation: trueで手動のみにする

スキルが/メニューに表示されない

• /contextで除外スキルの警告がないか確認
• スキルのdescriptionが合計で文字数制限を超えている場合はSLASH_COMMAND_TOOL_CHAR_BUDGET環境変数で拡張

.claude/commandsとの関係

旧来の.claude/commands/review.md形式は現在もサポートされていますが、skillsに統合されました。

# 旧形式（互換性あり）
.claude/commands/review.md

# 新形式（推奨）
.claude/skills/review/SKILL.md

同じ名前のskillとcommandがある場合、skillが優先されます。新規作成する場合はskills形式を使いましょう。

まとめ

Claude Code Skillsは、AIコーディングワークフローを再利用可能なコマンドにまとめる機能です。

• SKILL.mdを書くだけでカスタムコマンドが作れる
• 引数対応で柔軟なワークフローを定義
• 自動/手動の呼び出し制御でAIの自律性を調整
• プロジェクト/個人/チームの各スコープで共有可能
• サブエージェント実行で分離コンテキストにも対応
• 動的コンテキスト注入でシェルコマンド出力を活用

一度スキルを作れば、チーム全員が同じ品質で同じワークフローを実行できます。Claude Codeを使っているなら、まずは自分がよく繰り返す作業を1つスキル化するところから始めてみてください。