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 は公開された標準規格なので、対応しているツールなら同じファイルを使えます。

前提・検証環境

スキルの仕組み

スキルは、必要な分だけ段階的に読み込まれます(仕様では 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点です。