クイックサマリー: SKILL.mdは、Claude Codeに特定タスク専用の手順書を教えるためのMarkdownファイルです。.claude/skills/<スキル名>/SKILL.mdに置くだけで、スラッシュコマンドや自然文の指示から自動的に呼び出されます。本記事はZennの解説記事「SKILL.mdとは何か・構造を理解する」（pekopugu氏）を題材に、仕組み・構造・つまずきやすいポイントを整理した実践ガイドです。
Claude Codeに毎回同じ長い指示をコピペしていて、消耗していませんか。「この作業のときはこの手順で」というルールをチャットのたびに書き直すのは、時間の無駄であるだけでなく、指示の抜け漏れによる品質のばらつきという課題も生みます。
その解決策が、指示を外部ファイルとして管理する「スキル（Agent Skills）」の仕組みです。この記事では、その中核となるSKILL.mdファイルの構造と書き方を、実例をもとに解説します。なお、スキルの仕組み自体はAnthropicが公式に提供するオープンな仕様であり、公式のサンプルスキル集はanthropics/skillsリポジトリでOSSとして公開されています。
- SKILL.mdとは何か、CLAUDE.mdとの役割の違い
- フロントマター（name / description）と本文の書き方
- スキルが呼び出されないときの原因と改善策
- 実際の開発フローにスキルを組み込む具体例
SKILL.mdとは何か — CLAUDE.mdとの違い
SKILL.mdとは、Claude Codeに特定の作業を任せるための「専用命令書」ファイルです。参照元のZenn記事によると、.claude/skills/<スキル名>/SKILL.mdに配置するとClaude Codeが自動的に認識し、次の2通りの方法で呼び出せるようになります。
- 明示的な呼び出し: チャットで
/スキル名と入力する - 自動呼び出し: descriptionに書いたフレーズに合致する自然文の指示（例:「次の記事の指示書を作って」）を入力する
ここで重要なのが、CLAUDE.mdとの役割分担です。CLAUDE.mdはプロジェクト全体に常時適用されるルールを書くファイルで、Claude Codeの起動のたびに読み込まれます。一方SKILL.mdは、呼び出されたときだけ本文が読み込まれる「呼び出し型」の命令書です。常時読み込まれるのはフロントマターのname・descriptionのみのため、スキルを増やしてもコンテキスト消費を小さく抑えられるという設計上の利点があります。
| 項目 | CLAUDE.md | SKILL.md |
|---|---|---|
| 適用範囲 | プロジェクト全体 | 特定タスクのみ |
| 読み込みタイミング | 起動時に常時 | 呼び出し時のみ（description除く） |
| 向いている内容 | コーディング規約・環境情報 | 定型作業の手順書・フォーマット |
SKILL.mdの構造 — 3つの構成要素
SKILL.mdは大きく3つの要素で構成されています。
① フロントマター（name / description）
---
name: zenn-article-generator
description: Zenn記事の生成指示書を作成する。「Zenn記事を書いて」「次の記事の指示書を作って」と言われたら必ず使う。
---nameはスキルの識別名で、ディレクトリ名と一致させます。descriptionは「いつ呼び出すか」の判断基準になる最重要フィールドです。Claude Codeはdescriptionを常時保持しており、ユーザーの指示がその内容と合致したときにスキルを起動します。
② 本文（Markdown）
フロントマターより下は、通常のMarkdownで書く指示内容です。実行手順・ルール・出力フォーマット・参照情報などを詳細に記述します。参照元記事の実例では、リポジトリ情報やシリーズ構成を表形式で整理し、Claude Codeが迷わず参照できるようにしていました。
③ 配置場所
.claude/
└── skills/
└── zenn-article-generator/
└── SKILL.mdディレクトリ名がそのままスキル名になり、ファイル名はSKILL.mdで固定です。この命名規則は変更できないため、最初に覚えておくと迷いません。
インストール・配置手順
スキルの追加は、ファイルを1つ作るだけで完了します。プロジェクトのルートで次のように配置します。
mkdir -p .claude/skills/my-skill
# .claude/skills/my-skill/SKILL.md をエディタで作成作成後、Claude Codeのチャットで /my-skill と入力してスキルが起動すれば動作確認は完了です。公式ドキュメント（Claude Code Skills）でも、スキルはフロントマター付きのSKILL.mdを配置する方式で管理することが示されています。また、公式マーケットプレイス経由で既製スキルを導入する場合は /plugin marketplace add → /plugin install の手順も利用できます。
Antigravity CLI（agy）で使う場合
類似のスキル方式はClaude Code以外のCLIにも広がっています。Antigravity CLIでは、ワークスペース単位なら<プロジェクトルート>/.agents/skills/、グローバルなら~/.gemini/antigravity-cli/skills/にSKILL.mdを配置する構成が用いられます。同じ作業標準を複数のCLIで共有したい場合は、スキルファイルを両方のディレクトリに同期する運用が考えられます。
カスタマイズの要点: descriptionにトリガーフレーズを列挙する
参照元記事で最も実用的な知見がここです。著者は「SKILL.mdを作るだけでは動きませんでした」と率直に報告しています。descriptionに「何をするスキルか」だけを書いた状態では、Claude Codeがスキルの存在を把握していても呼び出しタイミングを判断できず、無視されてしまったとのことです。改善策は次の2点です。
- 「Zenn記事を書いて」「次の記事の指示書を作って」のように、呼び出しに使う具体的なフレーズを列挙する
- 「〜と言われたら必ず使う」という強い表現を入れて、呼び出しの見落としを防ぐ
実開発フローにSKILL.mdを組み込む方法
SKILL.mdが真価を発揮するのは、繰り返し発生する定型作業の自動化です。具体的なシナリオを3つ挙げます。
シナリオ1: 記事・ドキュメント生成の指示書化。参照元記事のzenn-article-generatorスキルはまさにこの用途で、「次の記事の指示書を作って」と一言入力するだけで、リポジトリ情報・シリーズ構成・スラッグ規則を踏まえた記事生成指示書が作られます。執筆ルールをチャットに毎回貼り付ける必要がなくなります。
シナリオ2: リリース前チェックの定型化。「テスト実行 → lint → CHANGELOGの更新確認 → コミットメッセージ規約の確認」という手順をSKILL.mdに書いておけば、/release-checkのような1コマンドで毎回同じ品質ゲートを通せます。常時実行が必要な処理はhooksに、呼び出し型の手順はスキルに、という使い分けが整理のコツです。
シナリオ3: CLAUDE.mdの肥大化対策。プロジェクト指示書に「特定作業のときだけ必要な手順」が溜まってくると、起動のたびに不要な指示まで読み込まれてしまいます。呼び出し型の手順をSKILL.mdへ切り出すことで、CLAUDE.mdを常時必要なルールだけに保てます。
職種別に見ると、テックブログを運営する開発者なら記事フォーマットの統一に、受託開発のエンジニアなら顧客ごとのコーディング規約の切り替えに、データ分析担当ならレポート出力形式の固定に、それぞれ応用できます。
類似の指示ファイル方式との比較
AIコーディングツール各社が「指示の外部ファイル化」の仕組みを提供しています。主要な方式を比較します。
| 方式 | 対応CLI/ツール | ライセンス | 読み込み方式 | 特徴 |
|---|---|---|---|---|
| SKILL.md | Claude Code（Antigravity CLIも同形式を採用） | 仕様は公開・公式サンプルはanthropics/skillsでOSS | 呼び出し型 | description合致で自動起動。本文は必要時のみ読込 |
| CLAUDE.md | Claude Code | 仕様は公開 | 常時 | プロジェクト全体の恒常ルール向け |
| .cursorrules / Project Rules | Cursor | 仕様は公開 | 常時または条件付き | エディタ統合型。Rules for AIとして設定 |
| AGENTS.md | Codex CLIほか複数ツール | 公開仕様 | 常時 | ツール横断を狙った共通指示ファイル規約 |
「呼び出し型の専門命令書」という位置づけはSKILL.mdの際立った特徴です。常時適用型のファイルだけで運用するとコンテキストが肥大化しやすいため、両者の併用が現実的な構成と考えられます。
注意点・制約・セキュリティ
- ファイル名は固定:
SKILL.md以外の名前では認識されません。スキル名はディレクトリ名で決まります。 - descriptionの品質が呼び出し精度を左右する: 曖昧なdescriptionはスキルの無視につながります。トリガーフレーズの列挙が実用上の必須テクニックです。
- 外部通信は仕組み自体には無い: SKILL.mdは静的なMarkdownファイルであり、配置しただけで外部にデータが送信されることはありません。ただし、本文に書いた指示がコマンド実行やAPI呼び出しを促す場合はその内容に従って動作するため、第三者製スキルを導入する際は本文とスクリプトの中身を確認してから使うことを推奨します。
- シークレットを書かない: SKILL.mdはリポジトリにコミットされる前提のファイルです。APIキーやトークンを本文に記載しない運用が安全です。
- ツール間の互換差: フロントマターの拡張キー（allowed-tools等）はClaude Code固有のものがあり、他CLIへそのままコピーすると解釈されない場合があります。
まとめ
- SKILL.mdは
.claude/skills/<スキル名>/SKILL.mdに置くだけで使える、Claude Codeの呼び出し型「専用命令書」です - 常時適用のCLAUDE.mdと呼び出し型のSKILL.mdを使い分けることで、指示の管理とコンテキスト消費の両方を改善できます
- 呼び出し精度はdescriptionの書き方で決まります。トリガーフレーズの列挙と「必ず使う」の明記が実践的なポイントです
まずは1つ、毎回コピペしている指示をSKILL.mdに切り出すところから始めてみてください。さらに詳しい仕様はClaude Code公式ドキュメントと、元記事であるZennの解説記事を参照すると理解が深まります。
コメント