Claude Code Skillsとは？SKILL.md・CLAUDE.md・Agent Skillsの違いと使い方

冒頭の結論：SkillsはSKILL.mdで専門タスクを再利用する

Claude Code Skillsは、Claude Codeに専門的な作業手順や知識を必要なときだけ読み込ませ、繰り返し使えるようにする仕組みです。現行の公式Docsでは、SkillsはAgent Skillsのオープン標準にもとづき、ディレクトリ内のSKILL.mdを中心に構成します。

Skillsの本文は常時すべてをコンテキストへ詰め込むのではなく、作業に関係するときに読み込む設計です。プロジェクト全体の指示を常に伝えるCLAUDE.mdやAGENTS.mdとは、置き場所と読み込み方の前提が異なります。

この記事で分かること

• SKILL.mdとAgent Skills標準の最小構成
• CLAUDE.md、AGENTS.md、MCP、PluginsとSkillsの役割差
• frontmatter、scope、context: fork、呼び出し設定の見方
• 個人開発でSkillを作る前に確認したい安全チェック

SKILL.mdとAgent Skillsの最小構成

最低限のSkillは、Skill名のディレクトリと、その直下のSKILL.mdで構成します。SKILL.mdのYAML frontmatterではnameとdescriptionを定義し、本文にはタスクの手順や判断基準を書きます。必要に応じてscripts、references、assetsなどの補助ファイルを同じSkillにまとめます。

---
name: review-changes
description: Review a change set against the project checklist.
---

# Review changes

確認観点、成果物、完了条件を短く書く。

この例で重要なのは名前を増やすことではなく、descriptionから「いつ使うSkillか」が分かることです。本文を長くしすぎず、詳細な手順や参照資料は必要なファイルへ分けると、更新時の確認範囲も小さくできます。

CLAUDE.md・AGENTS.md・Skills・MCP・Pluginsの役割

これらは競合する名称ではなく、異なる層の仕組みです。プロジェクトの常時ルールをSkillへ移すだけでは不十分ですし、SkillにMCP接続の権限まで任せてよいとも限りません。目的、読み込み方、変更者、権限の境界を分けて管理します。

scopeとSkillの見つかり方を確認する

Claude Codeでは、個人用、プロジェクト用、Pluginに含まれるSkillなど、置き場所によって適用範囲と優先順位が変わります。プロジェクト内のネストしたディレクトリから見つかるSkillや、Plugin namespaceで区別されるSkillもあるため、作成前に「誰の環境で、どのリポジトリで、どの名前で見えるか」を確認します。プロジェクトやPlugin由来のSkillは、信頼できる出所かどうかもレビュー対象です。

• 個人用かプロジェクト用かを決め、同じ名前のSkillとの優先関係を確認する
• Plugin由来なら、配布元、更新方法、namespace、含まれるMCPやHookの有無を見る
• Skillを追加・変更したときに、現在のClaude Codeで再検出されるかを確認する
• 複数のリポジトリで共有する場合は、プロジェクト固有のパスや秘密情報を本文に埋め込まない

context: fork・呼び出し設定・権限を混同しない

Skillのfrontmatterには、実行コンテキストや呼び出し方を調整する設定があります。context: forkはSkillを別のコンテキストで扱うための設定、disable-model-invocationはモデルによる自動呼び出しを止めるための設定です。dynamic context injectionのように、実行時に情報を差し込む仕組みもあります。

• descriptionは、Skillを使う場面と対象を具体的に書く
• 自動呼び出しを避けたい作業ではdisable-model-invocationの意味を確認する
• context: forkを使う場合は、元の会話と別コンテキストで何が見えるかを確認する
• allowed-toolsは事前許可の設定として扱い、Claude Codeのpermission settingsによる制御を別途確認する

個人開発で使いやすいSkills例

• SEO記事追加スキル：title、description、見出し、内部リンク、関連記事を確認する
• デザインレビュー用スキル：スマホ表示、文字サイズ、余白、CTAの見え方を確認する
• ビルド確認スキル：npm run build、主要ページ表示、エラーログ確認を手順化する
• 画像最適化スキル：ファイルサイズ、alt、表示崩れ、OGP差し替えを確認する
• セキュリティ確認スキル：.env、APIキー、権限設定、本番操作の有無を見る

Skillsは作業を任せる範囲を整理する仕組み

Skillsは便利な拡張というだけでなく、AIに任せる範囲を固定するための仕組みとして見ると使いやすくなります。たとえば「SEO記事追加なら、title、description、内部リンク、FAQ、build確認まで」「デザインレビューなら、スマホ表示、文字量、CTAだけを見る」のように、入力、手順、成果物、確認方法を切り分けます。

向いているケース

Skillsが向いているのは、何度も繰り返す作業です。たとえばメディアサイトで記事を追加するたびに、見出し構造、内部リンク、関連記事、SEOメタ、ビルド確認を行うなら、手順としてまとめる価値があります。

向いていないケース・注意点

• プロジェクト指示とタスク手順を混ぜすぎない
• Codex用のAGENTS.mdとClaude Code用の指示を同じものとして扱わない
• 古いビルドコマンドや古いディレクトリ構成を放置しない
• 一度しか使わない作業までSkills化しない

よくある誤解

Skillsは、AIを万能化する機能ではありません。むしろ、作業を狭く定義して、同じ品質で繰り返すためのものです。曖昧な巨大Skillを作るより、小さく具体的なSkillを少数持つ方が個人開発では扱いやすいです。

まとめ：ルールと手順を分けると運用しやすい

Claude Code Skillsとは、特定タスクを再利用しやすくするための手順化の仕組みです。CLAUDE.mdやAGENTS.mdに書くプロジェクト全体のルールとは分け、繰り返す作業だけを丁寧にまとめるのが現実的です。