🏃‍♀️

Claude Code キャッチアップ: CLAUDE.md から SKILL.md への切り出し

に公開
Claude Code
tech

Claude Code キャッチアップ: CLAUDE.md から SKILL.md への切り出し

1. はじめに

Claude Codeを2025年6月ごろから利用しています。開発作業、調査、ドキュメント作成など幅広い用途で活用してきました。
初期はデグレや性能低下が頻発していたため、安定版の1.0.59に固定する運用をしていました。しかし最近になってアップデートが強制されたので、重い腰を上げてバージョンを上げることに決めました。
どうせバージョンを上げたなら新機能を使いたいということで、本記事ではキャッチアップとして「CLAUDE.mdからSKILL.mdへの切り出し」を実際に行います。

2. Claude Codeの設定ファイル構造（2025年末時点）

（本記事の内容や参考文献のリンク先についてはいずれも2025年末時点のものです）

公式ドキュメント[1]によると、Claude Codeは複数の設定ファイルをサポートしており、それぞれ読み込みタイミングが異なります。以下のような種類があります。

ファイル 用途 読み込みタイミング
CLAUDE.md 常に有効な指示・コンテキスト 常時
rules/*.md パス固有ルール 該当ファイル操作時
skills/*/SKILL.md タスク固有の知識拡張 トリガー時のみ
agents/*.md サブエージェント定義 委譲時のみ

CLAUDE.mdは起動時にすべて読み込まれるため、設定を詰め込みすぎるとコンテキスト（コンテキストウィンドウ）を圧迫します[2]。一方、Skillsは起動時にはメタデータ（name, description）のみが読み込まれ、実際に必要になった時点で本体が読み込まれます[3]。この仕組みにより、コンテキストの消費を抑えながら多様な設定を持てるようになりました。

3. 切り出したい設定: 「ドキュメント保存のガイドライン」

現在、CLAUDE.mdに以下の設定をベタ書きしています。

## ファイル保存場所のガイドライン

### ドキュメントファイル
- **保存場所**: プロジェクトホームの `.96kudye/docs/` ディレクトリ
- **ファイル名形式**: `YYMMDD_[filename].md`
  - 例: `250818_ARCHITECTURE_OVERVIEW.md`
  - 作成日を先頭に付けて整理しやすくする
  - マークダウンの場合ファイル名は英大文字が望ましい

この設定は「ドキュメントにまとめて」「記録して」といった指示があった際に、指定のディレクトリ・フォーマットでファイルを出力させるためのものです。調査対応、仕様検討、PRレビューの保存など、日常的に多用する指示だったためCLAUDE.mdに記載しています。
.96kudyeはglobalでgitignoreしているディレクトリです。最初は.claude/docs/を利用していましたが、Claude Codeの社内での活用が広まり、Gitに.claudeディレクトリがコミットされることも増えてきたため、個人用のディレクトリを用意しました。

また、日付については誤った値を出力されることが多いため、別途以下の指示も加えています。

## 時刻取得のガイドライン

- ファイル名やドキュメント記載内容に現在時刻が必要な場合は、必ず環境情報に含まれる現在の日付を確認する
- **重要**: ファイル名を作成する前に、必ず環境情報の日付を声に出して（テキストで）確認すること
  - 例: 「環境情報によると今日は2025-10-14なので、YYMMDDは251014です」
- 絶対に推測や記憶に頼らず、環境情報を参照すること

これらの設定は常に必要なわけではなく、ドキュメント保存時にのみ必要となります。大した分量ではないですが、今回はこの設定を切り出していこうと思います。

4. RulesとSkillsのどちらを使うべきか

CLAUDE.mdから設定を切り出す際、RulesとSkillsのどちらを使うべきでしょうか。公式ドキュメント[1:1]を参考に、両者の特徴を比較して判断します。

Rulesの特徴

Rulesはファイルパス操作時にトリガーされます[1:2]。

---
paths:
  - "src/api/**/*.ts"
---
# API開発ルール
- すべてのAPIエンドポイントに入力検証が必須

上記の例では、src/api/配下の.tsファイルを編集する際にのみルールが読み込まれます。「このパスのファイルはこう書け」という用途に適しています。

Skillsの特徴

Skillsはタスク種類（descriptionでのマッチング）でトリガーされます[3:1]。

---
name: save-document
description: |
  ドキュメントやレポートをファイルに保存する。
  「ドキュメントにまとめて」「ファイルに出力して」「記録して」
  などの指示があった場合に使用。
---

descriptionに記載されたキーワードや説明に基づいて、Claudeが自動的にスキルを選択します。「このタスクはこう実行しろ」という用途に適しています。

判断

今回切り出したい「ドキュメント保存のガイドライン」は、以下の特徴があります。

  • 「ドキュメントにまとめて」という**発言（タスク種類）**でトリガーしたい
  • 特定のファイルパスへの操作ではない

したがって、Skillsが適切と判断しました。

5. 実装: Skillsとして切り出す

save-documentスキルの作成

Skillsとして切り出すため、ここまでのことを伝えた上でCLAUDE.mdから~/.claude/skills/save-document/SKILL.mdを作成するようClaude Codeに指示を出しました。作成されたファイルが以下になります。

---
name: save-document
description: |
  ドキュメントやレポートをファイルに保存する。
  「ドキュメントにまとめて」「ファイルに出力して」「記録して」
  「メモを残して」などの指示があった場合に使用。
allowed-tools:
  - Write
  - Bash
---

# ドキュメント保存ガイドライン

## 保存場所
- プロジェクトホームの `.96kudye/docs/` ディレクトリに保存する

## ファイル名形式
- `YYMMDD_[FILENAME].md`
- 例: `250818_ARCHITECTURE_OVERVIEW.md`
- 作成日を先頭に付けて整理しやすくする
- ファイル名は英大文字が望ましい

## 日付の取得方法
- **重要**: ファイル名を作成する前に、必ず環境情報に含まれる現在の日付を確認すること
- 確認した日付をテキストで明示する
  - 例: 「環境情報によると今日は2025-10-14なので、YYMMDDは251014です」
- 絶対に推測や記憶に頼らず、環境情報を参照すること

descriptionにトリガーワードを明記して適切に発動するようになっています。allowed-toolsについては、ファイル書き込みを行うこと、スキル内で時刻の確認を行う（dateコマンドの実行をする）ことがあるのでこれらのツールを許可しています。
また、関連する日付取得のルールも統合されており、うまく整理できています。

配置場所

  • ~/.claude/skills/: 全プロジェクト共通で使用する場合
  • .claude/skills/: 特定プロジェクトのみで使用する場合

今回は全プロジェクトで使いたいため、~/.claude/skills/に配置します。

6. まとめ

本記事では、Claude CodeのSkills機能を使って、CLAUDE.mdから設定を切り出す方法を紹介しました。
Rulesなどの他の機能との使い分けや連携を考える一助になれば幸いです。

AIコーディングエージェントには新機能が続々追加されており、常に追い続けるのは少し大変です。
しかし、いざキャッチアップしようとやってみると、調査から実装までの大部分をそのAI自身に任せられるため、思ったよりも楽に感じました。
今後も定期的に新機能を試し、運用に取り入れていきたいと思います。

7. 参考文献

公式ドキュメント

脚注に記載

参考記事

脚注

  1. Settings - Claude Code ↩︎ ↩︎ ↩︎

  2. Memory - Claude Code ↩︎

  3. Skills - Claude Code ↩︎ ↩︎

Discussion