Knowledge
Agent Skills(SKILL.md)の作り方 ― 定型作業を Claude Code に覚えさせる
毎回同じ指示を書いている作業は、Agent Skills にすると一言で頼めるようになります。リリースノート作成のスキルを実際に作り、自動で呼ばれる様子とスキルなしとの違いを確かめました。
Agent Skills は、AI エージェントに「この作業はこの手順でやる」という知識を渡すための仕組みです。フォルダに SKILL.md というファイルを1つ置くだけで作れます。
2026年10月22日、Anthropic はこの規格を、Linux Foundation 傘下の Agentic AI Foundation(AAIF)に寄贈すると発表しました。発表によると、ChatGPT・Cursor・GitHub Copilot・VS Code など70以上のエージェント製品が対応し、公開されたスキルは100万件、インストールは約2億8,000万件にのぼります(Anthropic の発表)。
この記事では、実際に「コミット履歴からリリースノートを書く」スキルを作り、Claude Code で使ってみます。
こんな場面で役立つ
- 毎週のリリースノートや週報を、同じ書式で書かせたい。毎回「この見出しで、この順番で」と指示を書き直す必要がなくなります。
- チームで決めた手順を、全員の AI に同じように守らせたい。スキルをリポジトリに入れておけば、clone した人の Claude Code でも同じ手順で動きます。
- 長い手順書を毎回プロンプトに貼っている。スキルは必要になったときだけ読み込まれるので、普段の会話を圧迫しません。
- Claude Code 以外のツールでも同じ手順を使いたい。SKILL.md は公開された標準規格なので、対応しているツールなら同じファイルを使えます。
前提・検証環境
- 確認日:2026年11月12日
- Claude Code 2.1.322 / macOS
- 仕様:agentskills.io の Specification、Claude Code のスキルのドキュメント
スキルの仕組み
スキルは、必要な分だけ段階的に読み込まれます(仕様では progressive disclosure と呼ばれています)。
| 段階 | 読み込まれるもの | タイミング |
|---|---|---|
| 1. メタ情報 | name と description(約100トークン) | 起動時に全スキル分 |
| 2. 本文 | SKILL.md の本文(5,000トークン未満を推奨) | スキルが使われるとき |
| 3. 付属ファイル | scripts/・references/・assets/ の中身 | 本文の手順で必要になったとき |
つまり AI は、普段は説明文(description)だけを見て、どのスキルを使うかを判断しています。説明文の書き方が、スキルが呼ばれるかどうかを決めます。
手順
1. フォルダを作る
Claude Code では、置き場所によって使える範囲が変わります。
- 自分だけ・全プロジェクトで使う:
~/.claude/skills/<スキル名>/SKILL.md - そのプロジェクトだけで使う(チームで共有できる):
.claude/skills/<スキル名>/SKILL.md
今回はプロジェクトに置きます。書式の見本は別ファイルに分けました。
.claude/skills/release-notes/
├── SKILL.md
└── references/
└── format.md
2. SKILL.md を書く
---
name: release-notes
description: gitのコミット履歴から、利用者向けの日本語リリースノートを作成する。「リリースノートを書いて」「今週の変更をまとめて」「変更履歴を利用者向けに整理して」と頼まれたときに使う。
---
# リリースノートの作成
## 手順
1. `git log --since="<対象期間の開始日> 00:00" --pretty=format:"%ad %s" --date=short` で対象期間のコミットを取得する。期間の指定がなければ直近7日間とする。
2. コミットメッセージの接頭辞で分類する。
- `feat:` → 新機能
- `fix:` → 不具合の修正
- `docs:` `chore:` `refactor:` `test:` → 利用者に影響しないので載せない
3. [references/format.md](references/format.md) の書式に従って書く。
4. 最後に「載せなかったコミット」の件数を1行で添える。
## 書き方の注意
- 開発者向けの言葉(関数名・ファイル名など)は使わず、利用者が何をできるようになったかで書く。
- 1項目は1文にする。
先頭の --- で囲んだ部分(フロントマター)のルールは次のとおりです。
name:英小文字・数字・ハイフンで64文字以内。フォルダ名と同じにする。Claude Code では省略でき、省略するとフォルダ名が使われます。description:1,024文字以内。何をするスキルかに加えて、どんな頼まれ方をしたときに使うかを書きます。今回は「リリースノートを書いて」「今週の変更をまとめて」と、実際に言いそうな言い回しを並べました。
3. 書式の見本を付属ファイルに分ける
references/format.md に、出力の見本を書きます。本文から参照しておくと、スキルが使われたときだけ読み込まれます。
# リリースノートの書式
```
## リリースノート(YYYY年M月D日〜M月D日)
### ✨ 新機能
- 〜できるようになりました。
### 🐛 不具合の修正
- 〜する不具合を修正しました。
(載せなかったコミット:N件)
```
- 該当がない見出しは丸ごと省く。
- 日付は対象期間の最初と最後のコミット日にする。
4. 名前を出さずに頼んで、自動で使われるか確かめる
検証用のリポジトリに、次の5件のコミットを用意しました。
2026-11-11 chore: 依存パッケージを更新
2026-11-11 feat: 予約一覧をCSVで出力できるようにした
2026-11-10 docs: READMEにセットアップ手順を追加
2026-11-10 fix: 予約日時が9時間ずれる不具合を修正
2026-11-09 feat: メールアドレスでのログインに対応
Claude Code に、スキルの名前を出さずに「今週の変更を、利用者向けにまとめてほしい」とだけ頼みました。
実行結果(Claude Code の動きを抜粋)
ツール呼び出し: Skill {"skill": "release-notes", "args": "今週の変更"}
ツール呼び出し: Bash git log --since="2026-11-05" … / cat references/format.md
## リリースノート(2026年11月9日〜11月11日)
### ✨ 新機能
- メールアドレスでログインできるようになりました。
- 予約一覧をCSVファイルとして出力できるようになりました。
### 🐛 不具合の修正
- 予約日時が9時間ずれて表示される不具合を修正しました。
(載せなかったコミット:2件)
依頼の言葉が説明文に合っていたので、Claude Code は自分で release-notes スキルを選びました。手順どおりに docs: と chore: を除き、付属ファイルの書式どおりに書いています。
5. スキルなしの場合と比べる
スキルのフォルダを一時的に外し、まったく同じ依頼をしました。
実行結果(スキルなし・抜粋)
## 今週のアップデート(11月9日〜11月12日)
### 新機能
- **メールアドレスでログインできるようになりました**
ログイン画面でメールアドレスを入力してサインインできます。
- **予約一覧をCSVで出力できるようになりました**
予約一覧をCSVファイルでダウンロードできます。Excelなどの表計算ソフトで集計や共有に使えます。
…
内容は十分に読めるものですが、見出し・書式・粒度がスキルありの場合と違い、「Excel などで集計に使えます」のようにコミットにない推測も書き足されました。スキルの価値は、毎回同じ書式・同じ判断基準で仕上がることにあります。
6. 名前で直接呼ぶ
スキルは /release-notes のようにスラッシュコマンドとしても呼べます。後ろに書いた言葉は、引数として渡されます。
/release-notes 11月11日以降
実行結果
## リリースノート(2026年11月11日〜11月11日)
### ✨ 新機能
- 予約一覧をCSVファイルとして書き出せるようになりました。
(載せなかったコミット:1件)
不具合の修正がない期間なので、書式のルールどおり「不具合の修正」の見出しが省かれています。
つまずきポイント
git log --sinceに日付だけを渡すと、その日の早い時刻のコミットが漏れる。最初の版では手順に--since="2026-11-11"のような日付だけの指定を書いていました。git はこれを「11月11日の今の時刻以降」と解釈するので、0件になりました。Claude Code が自分で気づいて00:00を付けて取り直し、スキルにも直すよう提案してくれました。上の SKILL.md は修正後のものです。スキルは一度使ってみて、手順の穴を埋めながら育てるのが近道です。- 説明文に「いつ使うか」を書かないと、自動では呼ばれにくい。AI は普段、説明文しか見ていません。「〜を作成する」だけでなく、「〜と頼まれたときに使う」まで書いておきます。
- 他人が作ったスキルは、中身を見てから使う。Claude Code では、スキルの
allowed-toolsに書いたツールは確認なしで使えるようになります。この設定は、信頼していないフォルダでの-p実行でも有効です。また、本文に!`コマンド`と書くと、AI が読む前にそのコマンドが実行されます。公式ドキュメントも、リポジトリに入っているスキルのallowed-toolsを確認するよう勧めています。シェルの実行自体を止めたい場合は、設定で"disableSkillShellExecution": trueにします。 - 編集はその場で反映される。既存のスキルフォルダの中の追加・編集・削除は、Claude Code を再起動しなくても反映されます。ただし、起動時になかったスキル用フォルダを新しく作った場合は、
/reload-skillsを実行します。
まとめ
Agent Skills は、「毎回同じことを指示している作業」を、フォルダ1つで AI に覚えさせる仕組みです。作るときに大事なのは、どんな頼まれ方をしたときに使うかまで説明文に書くこと、そして一度使ってみて手順を直していくことの2点です。