繰り返しの作業を、AIコーディングエージェントの再利用可能なスキルに変える方法

AIコーディングエージェントに同じチェックリストを何度も貼り付けているなら — 「コンベンショナルコミットを書いて、テストを実行して、それからチェンジログを更新する」 — それはエージェントが代わりに覚えていられる作業をあなたがしているということです。最近のエージェントの多くは、繰り返しの手順を小さく再利用可能なファイルにまとめられるようになっています。Claude Codeではこれをスキルと呼び、同じファイルが/deployのようなスラッシュコマンドの動力にもなります。このガイドでは、ゼロから一つ作る手順を追ったうえで、他のツールにも通じる原則を説明します。

スキルとは何か

スキルとは、SKILL.mdという単一のファイルが入ったフォルダのことです。そのファイルには2つの部分があります。エージェントにそのスキルをいつ使うべきかを伝えるYAMLのフロントマターと、スキルが実行されるときに従う指示を記したMarkdownの本文です。すべてをCLAUDE.md(やAGENTS.md)ファイルに詰め込むことに対する主な利点は、**プログレッシブ・ディスクロージャー(段階的開示)**です。本文はスキルが実際に呼び出されたときにのみ読み込まれるため、長い参照資料は必要になるまでほとんどコストがかかりません。

スキルの呼び出し方は2通りあります。/skill-nameと入力して直接呼び出す方法と、自動的に呼び出す方法です。後者では、エージェントがあなたのリクエストを読み取り、それをスキルのdescriptionと照合し、関連していれば読み込みます。

スキルの置き場所

フォルダをどこに置くかで、誰がそれを使えるかが決まります。Claude Codeでは、公式ドキュメントによれば:

• ~/.claude/skills/<name>/SKILL.md — 個人用。あなたのすべてのプロジェクトで使えます。
• .claude/skills/<name>/SKILL.md — プロジェクト用。リポジトリにコミットされるので、チームの全員が同じコマンドを使えます。

フォルダ名がそのままコマンドになります。summarize-changesという名前のフォルダなら、/summarize-changesが使えるようになります。

具体的な例

コミット前に、未コミットの変更を要約し、リスクのある点があれば指摘してくれるスキルを作ってみましょう。ディレクトリを作成します:

mkdir -p ~/.claude/skills/summarize-changes

そして、これを~/.claude/skills/summarize-changes/SKILL.mdとして保存します:

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any
risks you notice such as missing error handling, hardcoded values, or tests
that need updating. If the diff is empty, say there are no uncommitted changes.

これが機能するポイントは2つあります。1つ目は、descriptionがあなたのためではなくエージェントのために書かれていることです — トリガー(「何が変わったか」「コミットメッセージが欲しい」「差分をレビューする」)を名指しすることで、エージェントはいつそれを使えばよいかを把握します。2つ目は、!`git diff HEAD`の行が動的なコンテキスト注入である点です。Claude Codeはこのコマンドを実行し、その出力を、エージェントがスキルを読む前にプロンプトに貼り付けます。指示はあなたの実際の差分がすでに埋め込まれた状態で届くので、答えは当て推量ではなく、あなたの本物の作業ツリーに基づいたものになります。

どれか一つのファイルに小さな編集を加え、エージェントを起動して、両方の方法を試してみてください — 「何を変更した?」と尋ねて自動的に呼び出すか、/summarize-changesと入力して直接実行するか、です。

引数を渡す

スキルは入力を受け取れます。本文中の$ARGUMENTSというプレースホルダーは、コマンドの後に入力した内容に置き換えられ、インデックス付きのバリアント($0、$1)は特定の単語を取り出します。/fix-issue 4821として呼び出されたスキルは、課題番号を直接参照できるので、チケットごとに1つずつではなく、1つのファイルですべての課題に対応できます。

長く使えるスキルのための5つの原則

これらは、Claude Codeのスキルを書く場合でも、Cursorのコマンドでも、あるいは — OpenAIの2026年6月のRecord & Replay機能以降であれば — エージェントが記録してくれた自動化を編集する場合でも当てはまります:

1. descriptionはモデル向けに書く。 具体的なトリガーフレーズを前面に出しましょう。descriptionが曖昧だと、エージェントはスキルを自動で読み込まず、結局あなたは/を入力して名前を思い出す羽目に戻ります。
2. 各スキルは1つの仕事に絞る。 デプロイしてマイグレーションを実行してSlackに投稿する、というスキルは信頼しづらく、デバッグはもっと困難です。小さく単一目的のスキルのほうが、組み合わせがうまくいきます。
3. ライブのコンテキストを説明するのではなく注入する。 実際の差分、テスト結果、ファイル一覧を取り込むほうが、エージェントに「現在の状態を確認して」と伝えるよりも優れています — エージェントが誤って推測しうる一段階を取り除いてくれるからです。
4. 副作用のあるものはゲートをかける。 デプロイ、マイグレーション、削除を行うスキルでは、エージェントが自動的に発火させるのではなく、明示的な呼び出しを必須にしましょう。取り返しのつかない操作の前には、人間を介在させたいものです。
5. チームのスキルはリポジトリにコミットする。 プロジェクトのスキルを.claude/skills/に置いてチェックインすれば、すべての開発者 — そしてCIでのすべてのエージェント実行 — が同じ手順に従います。あなたの取り決めが、一人の頭の中だけに留まらなくなります。

いつスキルに頼るべきか

目安はこうです。同じ複数ステップの指示を3度目に貼り付けた瞬間、あるいはCLAUDE.mdのある部分が事実から手順へと変わったとき、それをスキルに移しましょう。再利用可能なコマンドが手に入り、コンテキストファイルは無駄なくスリムなまま保たれ、指示は実際に必要なときだけ読み込まれます — それが、あなたとエージェントの両方を目の前のタスクに集中させ続けてくれるのです。