Claude Code Skillsの作り方繰り返す作業を手順にまとめる

Claude Code Skillsは、繰り返す定型作業を .claude/skills/<スキル名>/SKILL.md の1ファイルにまとめ、/skill-name や会話の文脈から呼び出す仕組みです。最初は変更履歴の下書きを作る changes-summary スキルを最小構成で配置し、対象の依頼3件で指定どおり出力され、無関係な依頼2件で誤作動しないことを確認するのが到達点になります。

※2026年10月29日時点の公式ドキュメント（Extend Claude with skills）にもとづく手順ガイドです。実機での5件の差分比較実行は未実施であり、記事内の changes-summary スキルと5件のサンプル課題・確認表は手元で動作を点検するための編集側サンプル教材です。

スキル化する作業を選ぶ

最初に切り出すスキルは、「入力と出力の形式が決まっており、完了条件を1文で言える作業」に絞ります。1つのスキルに複数の目的を詰め込むと、起動条件が曖昧になり出力もばらつきます。

変更履歴の整理を題材にする理由

本記事では、Gitの変更差分から「公開用の変更履歴（Changelogやリリースノートの下書き）」を作る作業を題材にします。最初のスキルに適している理由は以下の3点です。

入力が明確：変更差分や変更ファイルというリポジトリ内の情報だけで完結する。
出力の型を固定しやすい：「追加・変更・修正の分類」「利用者への影響」「破壊的変更の有無」を見出しで指定できる。
禁止境界を引きやすい：「下書き出力までで完了し、git commit や外部公開は行わない」と安全に制限できる。

CLAUDE.mdやMCPとの役割差

常設ルールを書く CLAUDE.md や外部接続のMCPと役割を分けることで、設定の置き場所が明確になります。

仕組み	主な役割	向いている内容の例
CLAUDE.md	プロジェクト全体で常時守る前提・ルールの共有	テスト実行コマンド、ディレクトリ構成、コーディング規約、変更禁止ファイル
Claude Code Skills	特定の目的・成果物のために呼び出す作業手順	変更履歴の下書き作成、特定観点のコードレビュー手順、定型ドキュメント生成
MCP（外部接続）	外部サービスやデータベース等の情報取得・操作	チケット管理ツールの参照、社内ドキュメント検索、外部APIの呼び出し

すべての作業で常時守らせるルールは CLAUDE.mdの書き方プロジェクトのルールを短く伝えるの CLAUDE.md に置き、特定作業の手順と出力フォーマットだけをClaude Code Skillsに切り出します。本体の導入がまだの場合は Claude Codeをインストールする OS別の初期設定と起動確認を先に済ませてください。

最小のスキルを作る

最初から補助スクリプト等を増やさず、SKILL.md 1ファイルだけの最小構成で作ります。

配置場所とSKILL.mdの最小構成

プロジェクト単位のスキルは .claude/skills/<スキル名>/SKILL.md に配置します（個人環境で横断利用する場合は ~/.claude/skills/<スキル名>/SKILL.md も使えますが、まずはプロジェクト配下で試すと影響範囲を絞れます）。

プロジェクトルート/
└── .claude/
    └── skills/
        └── changes-summary/
            └── SKILL.md

先頭のYAMLフロントマターに name と description を書き、本文に手順を記述します。

name：スキルの識別名（ディレクトリ名と揃えた小文字英数字・ハイフン）。/skill-name で手動呼び出しする名前になります。
description：スキルが「何をするか」「いつ使い、いつ使わないか」の説明。文脈から自動選択される際の判断材料になります。
disable-model-invocation（任意）：true にすると自動呼び出しを止め、/skill-name の手動呼び出し専用にします。
user-invocable（任意）：false にすると / の候補に出さず、モデル側からのみ参照される構成にします。

入力情報と出力書式を固定したテンプレート

以下を .claude/skills/changes-summary/SKILL.md として保存します。

---
name: changes-summary
description: Git差分や変更ファイルの内容から、公開用の変更履歴（Changelog）やリリースノートの下書きを日本語で作成するときに使います。単純なコード解説やバグ原因の調査には使いません。
---

# 公開用変更履歴の下書き作成手順（changes-summary）

指定された変更差分または変更ファイルを読み取り、利用者やレビュアー向けの変更履歴の下書きを作成してください。

## 1. 入力の確認
- ユーザーから対象の差分（テキスト、対象ファイル、または比較範囲）が指定されている場合はそれを使用する。
- 対象が明示されていない場合は、現在の未コミット差分や直近の変更対象を確認してよいかユーザーに尋ねる。
- 差分が空の場合や、変更内容が読み取れない場合は、推測で変更履歴を作らず「変更差分が確認できません」と報告して終了する。

## 2. 分類と除外のルール
- 変更点を以下の3分類に整理する（該当がない分類は「該当なし」と記載する）：
  - **追加（Added）**：新しい機能、画面、設定項目など
  - **変更（Changed）**：既存機能の挙動変更、表示文言の更新、仕様調整など
  - **修正（Fixed）**：不具合の修正、エラー対処など
- 内部の変数名変更やインデント調整など、外部の挙動や利用者に影響しない変更は「内部整理のみ（公開履歴への記載対象外）」として区別する。

## 3. 出力書式
以下のテンプレートに沿って日本語で出力してください。

```text
## 変更履歴の下書き

### 要約（1〜2文）
- （今回の変更全体の目的を短く書く）

### 分類別の変更点
- 追加（Added）：
- 変更（Changed）：
- 修正（Fixed）：

### 注意事項・影響範囲
- 破壊的変更や設定変更の要否：（あり / なし とその内容）
- 公開履歴から除外した内部変更：（あれば記載）
```

## 4. 禁止事項（完了条件）
- 画面上に下書きを出力した時点で作業完了とする。
- ファイルの無断書き換え、`git commit`、`git push`、外部への公開操作は一切行わない。

呼び出して結果を確認する

SKILL.md を保存したら、「対象の依頼3件で正しく動くか」と「対象外の依頼2件で誤発動しないか」の両面から点検します。

不要な場面で起動しないか点検する5件のサンプル課題

【サンプル1（対象：機能追加と不具合修正の混在）】
/changes-summary 以下の差分から変更履歴の下書きを作ってください。
- src/form.js: 空欄送信時にエラーメッセージを表示する処理を追加
- src/price.js: 税込計算の端数処理が切り上げになっていた不具合を切り捨てに修正

【サンプル2（対象：破壊的変更を含む設定変更）】
今回の変更から公開用のリリースノート下書きをまとめてください。
- config/auth.json: トークン有効期限の設定キー名を `expire_sec` から `token_ttl_seconds` に変更（旧キーは廃止）

【サンプル3（対象：内部リファクタリングのみ）】
/changes-summary 次の変更を整理してください。
- src/utils.js: 内部のローカル変数 `tmpArr` を `filteredItems` にリネーム（外部仕様や出力の変更なし）

【サンプル4（対象外：既存関数の仕組み解説）】
src/price.js の税込計算関数がどのような順番で処理しているか、初心者向けに仕組みを解説してください。

【サンプル5（対象外：エラー原因のデバッグ相談）】
テストを実行すると `TypeError: Cannot read properties of undefined` が出ます。原因の切り分け手順を教えてください。

各サンプルの確認観点は以下のとおりです。

サンプル	区分	確認する起動挙動	期待される出力のポイント
サンプル1	対象	`/changes-summary` で明示的に呼び出せるか確認する	「追加」に空欄エラー表示、「修正」に端数処理が入り、出力書式どおりに並ぶ
サンプル2	対象	文脈（「リリースノート下書き」）から自動適用される	「変更」にキー名変更が入り、「注意事項・影響範囲」に旧キー廃止（破壊的変更）が明記される
サンプル3	対象	`/changes-summary` で起動し、除外ルールが働く	公開用の追加・変更・修正を無理に作らず、「公開履歴から除外した内部変更」として整理される
サンプル4	対象外	スキルが不要に介入しない	変更履歴のテンプレートではなく、通常のコード解説として回答される
サンプル5	対象外	スキルが不要に介入しない	変更履歴のテンプレートではなく、エラー原因の調査手順が回答される

失敗する指示を修正する

作成したClaude Code Skillsが呼び出されない場合や出力が崩れる場合は、「配置と構文」「description の条件」「指示の範囲」の3点を確認します。

スキルが呼び出されない・崩れる原因の切り分け表

症状	主な原因	確認箇所と修正方法
`/` の候補にスキル名が出ない	配置場所のズレ、またはファイル名の誤り	`.claude/skills/<name>/SKILL.md` の階層にあるか、ファイル名が小文字の `skill.md` 等になっていないか確認する
認識されない・読み込みエラーになる	YAMLフロントマターの構文崩れ	ファイル先頭と末尾の `---` が正しく閉じているか、`name:` や `description:` のコロン後に半角スペースがあるか確認する
手動の `/` で呼べない	`user-invocable: false` が設定されている	手動で呼び出したいスキルの場合は `user-invocable: false` を削除する
関連する依頼でも自動で選ばれない	`description` が抽象的すぎる、または `disable-model-invocation: true` になっている	自動選択させたい場合は `disable-model-invocation` を外し、`description` に具体的な用途キーワード（「変更履歴」「リリースノート」等）を入れる
関係ない質問でも毎回発動してしまう	`description` の対象範囲が広すぎる	「コードを扱うときに使う」のような広い表現をやめ、「いつ使い、いつ使わないか」を `description` に明記する
出力が途中で省略されたり指示が無視される	1つの `SKILL.md` に手順や長文資料を詰め込みすぎている	完了条件を1つに絞り、長い参考資料は別ファイルに分けて必要時だけ参照させる

曖昧な説明・不足情報・広すぎる範囲の修正例

失敗しやすい記述と修正後の違いを比較します。

修正前（失敗しやすい例）：

---
name: helper-skill
description: コードの変更を確認してまとめるときに使います。
---

変更内容を読んでいい感じに要約し、必要ならドキュメントも更新してコミットしてください。

この例には3つの欠点があります。

description が広すぎ、通常のコードレビューやデバッグ時にも誤発動しやすい。
出力見出しや分類基準がなく、毎回書式が変わる。
「ドキュメント更新とコミット」まで含めており、意図しない変更やコミットが起きやすい。

修正後（改善例）： 前章の changes-summary テンプレートのように、description に**適用条件（変更履歴・リリースノート作成）と除外条件（コード解説・バグ調査には使わない）**の両方を書き、本文で出力書式と「下書き出力までで完了しコミットはしない」という完了条件を固定します。

チームで保守できる形にする

作成したClaude Code Skillsをチームで共有し、仕様変更に合わせて更新する手順を整理します。

リポジトリでの共有範囲と依存ファイルの揃え方

チームで共有するスキルは、個人ホーム（~/.claude/skills/）ではなくリポジトリ内の .claude/skills/<スキル名>/SKILL.md に置いてGit管理に含めます。共有時は次の3点を守ります。

個人の絶対パスや秘密情報を書かない
/Users/自分の名前/... などのローカルパスや、APIキー・認証情報・社外秘データを SKILL.md に含めない。
補助ファイルは同じスキルフォルダ内に同梱する
参照テンプレート等がある場合は .claude/skills/changes-summary/ 配下にまとめ、リポジトリ内の相対パスで参照する。
常設ルール（CLAUDE.md）と重複させない
ブランチ命名規則やテストコマンドは CLAUDE.md に置き、スキルには固有の手順だけを書く（アプリ作成の基本手順は Claude Codeの使い方｜初心者向けアプリ作成プロンプトと動作確認も参照）。

サンプル入力と期待結果を使った変更時の回帰確認

プロジェクトの仕様変更に伴い SKILL.md を更新した際は、前章の「対象3件・対象外2件のサンプル入力」を使って回帰確認を行います。

対象サンプル（機能追加＋修正、内部変更のみ）で新しい出力書式どおりに出るか。
description を変更した場合、対象外の質問（コード解説など）で誤発動しないか。
「ファイル変更やコミットを行わない」という完了条件が維持されているか。

よくある質問（FAQ）

他人のスキルをそのまま使える？

外部公開されている SKILL.md を無確認で配置・実行しないでください。スキルには任意のコマンド実行やファイル操作を促す記述を含められるため、導入前に SKILL.md と同梱ファイルの全文を読み、不審なシェルコマンドや外部通信、意図しないファイル変更の指示がないか確認してから調整して使います。

出典・参考資料

Claude Code Docs - Extend Claude with skills

AmoriのAI実験室

本文執筆：agy ／確認・編集：制作担当

編集・検証方針

すべての記事を見る