CLAUDE.mdからAgent Skillsへ移行する方法【段階的ガイド】
Skill Gallery Team•2026年1月24日•5 分で読める
CLAUDE.mdを使っているプロジェクトで、Agent Skillsへの移行を検討していませんか？
この記事では、CLAUDE.mdからAgent Skillsへの移行方法と、両者の使い分けを解説します。
CLAUDE.mdとAgent Skillsの違い
CLAUDE.md
- Claude Code専用の設定ファイル
- プロジェクトルートに配置
- 常にコンテキストに読み込まれる
- プロジェクト固有のルールや背景情報に最適
Agent Skills
- 複数ツールで使える標準形式
- タスクに応じて読み込まれる（Progressive Disclosure）
- 特定のワークフローをパッケージ化
- 再利用・共有が容易
比較表
| 項目 | CLAUDE.md | Agent Skills |
|---|---|---|
| 互換性 | Claude Codeのみ | 複数ツール対応 |
| 読み込み | 常時 | タスクに応じて |
| 用途 | プロジェクト設定 | タスク特化のワークフロー |
| 共有 | プロジェクト内 | 複数プロジェクト/チーム |
移行すべきか？
移行が向いているケース
- 複数ツールで使いたい：Claude Code以外でも同じワークフローを使いたい
- 再利用したい：他のプロジェクトでも同じ指示を使いたい
- チームで共有したい：標準化したワークフローをチームで使いたい
CLAUDE.mdのままで良いケース
- プロジェクト固有の設定：このプロジェクトでしか使わない情報
- 常に参照が必要：毎回のタスクで必要な背景情報
- シンプルに保ちたい：ファイル1つで管理したい
段階的な移行手順
ステップ1：内容を分類する
既存のCLAUDE.mdの内容を以下の2つに分類します：
CLAUDE.mdに残すもの：
- プロジェクトの概要・背景
- 技術スタックの説明
- 常に守るべきコーディング規約
- 環境固有の設定
スキルに移行するもの：
- コードレビューの手順
- PR作成のテンプレート
- テスト作成のガイドライン
- 特定タスクのワークフロー
ステップ2：スキルを作成
移行対象の内容をSKILL.mdとして切り出します。
移行前（CLAUDE.md内）：
## コードレビュー
PRをレビューする際は以下の観点でチェックしてください：
1. セキュリティ
2. パフォーマンス
3. 保守性
4. テストカバレッジ
移行後（SKILL.md）：
---
name: code-review
description: PRのコードをセキュリティ・パフォーマンス・保守性の観点でレビューする
---
## 手順
PRをレビューする際は以下の観点でチェックしてください：
1. セキュリティ：SQLインジェクション、XSS、認証の問題
2. パフォーマンス：N+1クエリ、不要な再レンダリング
3. 保守性：複雑度、命名、コメント
4. テストカバレッジ：重要なロジックにテストがあるか
ステップ3：配置してテスト
mkdir -p .claude/skills/code-review
# SKILL.mdを配置
Claude Codeで動作確認：
/code-review
ステップ4：CLAUDE.mdを整理
移行した内容をCLAUDE.mdから削除し、スキルへの参照を追加：
# プロジェクト概要
[プロジェクトの説明...]
## 利用可能なスキル
- `/code-review` - コードレビュー
- `/pr-template` - PR作成
- `/test-generator` - テスト生成
移行のコツ
一度に全部移行しない
段階的に移行することで、問題が起きた際の切り分けが容易になります。
- まず1つのワークフローをスキル化
- しばらく使って問題がないか確認
- 問題なければ次のワークフローを移行
descriptionを丁寧に書く
スキルの自動適用のために、descriptionは具体的に書きましょう：
# ❌ 曖昧
description: コードをチェックする
# ⭕ 具体的
description: TypeScriptのPRをセキュリティ・パフォーマンス・型安全性の観点でレビューする
両方を併用する
完全に移行する必要はありません。CLAUDE.mdとAgent Skillsを併用するのが現実的です：
- CLAUDE.md：プロジェクトの背景情報、常時参照が必要なルール
- Agent Skills：特定タスクのワークフロー
まとめ
CLAUDE.mdとAgent Skillsは、それぞれ適した用途があります。
- プロジェクト固有の設定 → CLAUDE.mdに残す
- 再利用したいワークフロー → Agent Skillsに移行
段階的に移行して、両方のメリットを活かしましょう。
スキル一覧で、移行の参考になるスキルを探してみてください。
関連記事
- Claude Codeでスキルを設定する方法 - 移行後の設定
- 自分でスキルを作る方法 - SKILL.mdの書き方
- チームでスキルを共有する方法 - チームでの移行
- Agent Skillsとは？ - Agent Skillsの基本
claude-mdagent-skillsmigrationguideintermediate