Claudeスキル入門：SKILL.mdを1枚書いて「自分用の手順書」を作る

Claudeスキル・MCP
Claudeスキル・MCP のアイキャッチ

Claudeの「スキル」は、SKILL.mdというMarkdownファイル1枚から作れます。この記事では、最初の1本を書くための構成・frontmatterの決まり・descriptionの書き方・育て方を、公式ドキュメントに沿って整理します。

AIエージェントとツールのイラスト

スキルとは何か

スキル（Agent Skills）は、特定の作業のやり方をまとめた指示・スクリプト・資料のフォルダです。Claudeは必要なときだけ読み込むので、普段のコンテキストを圧迫しません。Claude Codeでも使えます。

MCPが「外部サービスへの接続口」を与えるのに対し、スキルは「どう進めるか」という手順の知識を与えます。両者は併用できます。

仕組み 役割 読み込まれ方
ルール／CLAUDE.md 常に守る前提・規約 常に読み込み
スキル 特定タスクの手順・ノウハウ 必要なときだけ読み込み
MCP 外部ツール・データへのアクセス 接続したツールとして利用
サブエージェント 独立した作業ウィンドウで処理 別コンテキストで実行し要約を返す

最小構成：SKILL.mdを1枚書く

Claude Codeでは、個人用なら ~/.claude/skills/スキル名/SKILL.md、プロジェクト用なら .claude/skills/ 以下に置きます。ファイルは、--- で囲んだYAML frontmatterと、本文の手順で構成します。

---
name: summarize-changes
description: 未コミットの変更を要約し、危険な箇所を指摘する。ユーザーが「何が変わった？」「コミットメッセージを書いて」「差分をレビューして」と言ったときに使う。
---

## 手順
1. git diff の内容を確認する
2. 変更を3行以内で要約する
3. 危険そうな箇所（削除・設定変更）を箇条書きで挙げる
ノートに書き込む手元
Photo: mrsdkrebs / CC BY 2.0（Openverse経由）

frontmatterの決まり

公式のベストプラクティスでは、次の制約が示されています。

項目 ルール
name 最大64文字。小文字・数字・ハイフンのみ。予約語は不可
description 最大1,024文字。空は不可。XMLタグ不可

frontmatterのYAMLが壊れていると、本文は読み込まれてもメタデータが空になります。/スキル名 では呼べても、Claudeがdescriptionで自動選択できなくなるので注意してください。

効くのは「description」

起動時にClaudeが読むのは、全スキルのnameとdescriptionだけです。ここで「いつ使うか」が伝わらないと、スキルは使われません。

  • 悪い例：「データを処理する」「ファイルをいろいろ扱う」（何を・いつ使うかが不明）
  • 良い例：何をするかに加え、「〜と言われたとき」「〜のファイルを扱うとき」といった発動条件まで書く

長くなったら分割する（段階的開示）

Anthropicのエンジニアリングブログ「Equipping agents for the real world with Agent Skills」は、段階的開示（progressive disclosure）を中核の設計原則としています。

  1. name/descriptionだけが常に読み込まれる
  2. 関連があると判断したら、SKILL.md本文を読む
  3. 必要に応じて、参照ファイルやスクリプトを読む・実行する

SKILL.mdは約500行以内に収め、詳細は別ファイルに移します。参照ファイルはSKILL.mdから直接リンクし、ファイルをまたぐ入れ子は避けます。長い参照ファイルには冒頭に目次を付けると、途中までしか読まれない場合でも要点が伝わります。

expense-report/
├── SKILL.md          # frontmatter + 手順（目次の役割）
├── scripts/validate.py
├── references/POLICY_FAQ.md
└── assets/template.md

育て方のコツ

  • 小さく始める：まず1本を1〜2週間使い、足りない点を直す。増やすのはその後。
  • 失敗から作る：Claudeがつまずいたタスクを観察し、その穴を埋める形で書く。
  • ステップごとに自由度を変える：文面づくりは緩く、請求書の生成のように正確さが要る部分はスクリプトで固定する。
  • 第三者のスキルはコードと同様に扱う：スクリプトを含みうるため、導入前に中身を確認する（Microsoftのガイドも同じ注意を促しています）。

まとめ

最初の1本は、「毎回同じ説明をしている作業」を選ぶと失敗しにくいです。descriptionに発動条件を書き、本文は短い手順にして、使いながら直していきましょう。

主な情報源

各ツールは提供元の規約に従ってご利用ください。情報は各情報源の公開時点のものです。収集・要約はAI、公開判断は人。