独自のagent skillの作り方とテスト方法

実際の 1 件の失敗から独自の agent skill を作成する

独自の agent skill を作成する最善の方法は、実際に発生した 1 件の失敗から要点を抽出することです。coding agent が 2 回間違えたタスクを見つけ、2 回とも入力した修正内容を書き留め、その修正を agent が自動的に読み込める SKILL.md ファイルとして保存します。それ以降は機械的な作業です。ファイルの構成と、skill が実際に適用されるかどうかを決める 1 行を設定します。

この順序が重要です。想像で作成した skill は、実際には経験していない問題を記録するだけで、毎回のセッションでコンテキストも消費します。実際に確認した失敗から抽出した skill には、独自のテストも付属します。同じ依頼をもう一度行い、今度は agent が正しく処理できるか確認できます。この形式が初めての場合は、先に agent skill とは何か、agent がどのように読み込むか を読んでから作成してください。

2 回失敗したタスクから始める

1 回なら偶然です。2 回ならパターンです。パターンにはファイルを作る価値があります。

実際のサーバーで繰り返し起きる失敗を見てみましょう。nginx に reverse proxy のブロックを追加するよう agent に依頼します。agent は /etc/nginx/conf.d/app.conf を編集してから sudo systemctl restart nginx を実行します。編集内容に typo があるため nginx は起動を拒否し、修正するまでサイトが停止します。

nginx: [emerg] unknown directive "proxy_pas" in /etc/nginx/conf.d/app.conf:12
Job for nginx.service failed because the control process exited with error code.

チャットで修正を指示します。サービスに触れる前に sudo nginx -t で設定をテストし、その後 restart ではなく reload で適用します。1 週間後、別のタスクで同じミスが起きます。この 2 回目がシグナルです。

失敗がまだ目の前にあるうちに、2 つの内容を書き留めます。入力したリクエストと、使った言葉のままの修正指示です。この 2 行が skill になります。リクエストは、トリガーが何に一致すべきかを示します。修正指示が、skill の全内容になります。

Anthropic の authoring guidance でも、これを最初に行うよう説明されています。skill を使わずに representative tasks で agent を実行し、どこで失敗するかを記録します。その後、失敗を修正する最小限の指示を書きます。失敗が仕様になります。そのため、どの失敗に基づくものか追跡できない skill は、通常、誰にも必要とされていなかった skill です。

同じ蒸留の具体例として、1 回の繰り返し失敗を skill に変える Ponytail の例（依頼以上に広範囲を書き換える agent）を、独自の skill を書く前に最初から最後まで読むことができます。

スキルの構成

スキルは、必須ファイルを 1 つ含むディレクトリです。

.claude/skills/nginx-config-changes/
├── SKILL.md
├── reference/
│   └── proxy-headers.md
└── scripts/
    └── check-and-reload.sh

SKILL.md はフロントマターブロックで始まります。これは、--- マーカーの間に記述する YAML の設定項目です。Docker Compose ファイルと同じ設定形式です。その後に、markdown で手順を記述します。以下は、先ほどの失敗に対応するスキル全体です。

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
---

## Rules

Run `sudo nginx -t` after every edit under `/etc/nginx`. Do not touch the service until it prints `test is successful`.

Apply the change with `sudo systemctl reload nginx`. Never use `restart`. A reload keeps the running workers serving traffic until the new config parses, so a broken config leaves the site up. A restart stops nginx first, so a broken config takes the site down.

If `nginx -t` fails, fix the file and test again. Never reload a config that failed the test.

For the proxy header defaults this project expects, see [reference/proxy-headers.md](reference/proxy-headers.md).

このファイルは 20 行未満で、完全なスキルになっています。構成要素は次のとおりです。

• name: 64 文字以内で、小文字、数字、ハイフンだけを使用します。claude または anthropic という単語は含められません。個人用スキルまたはプロジェクトスキルでは、表示ラベルとしてのみ使われます。入力するコマンドはディレクトリ名から決まるため、このスキルは /nginx-config-changes で呼び出します。
• description: スキルの機能と使用するタイミングを記述します。1,024 文字以内です。この行が実際の動作を決めます。次のセクションでは、この項目だけを扱います。
• 本文: 実際にスキルが起動したときだけ読み込まれる指示です。
• reference/: エージェントが必要に応じて読み込む追加ファイルです。SKILL.md からリンクし、リンクの深さは 1 階層に保ちます。別の参照ファイルから参照されるファイルは、一部しか読み込まれないことがあるためです。
• scripts/: エージェントが読み込むのではなく実行するファイルです。コンテキストを消費するのは出力だけなので、300 行のスクリプトでもコストは小さくなります。

ディレクトリを置く場所によって、スキルを利用できる範囲が決まります。

• リポジトリ内の .claude/skills/<name>/SKILL.md: このプロジェクトだけで使用します。リポジトリを clone した全員が利用できます。
• ~/.claude/skills/<name>/SKILL.md: 自分のマシン上のすべてのプロジェクトで使用します。他のユーザーには影響しません。
• <plugin>/skills/<name>/SKILL.md: plugin に含めて配布します。その plugin が有効な環境で利用できます。

mkdir -p .claude/skills/nginx-config-changes でディレクトリを作成し、ファイルを記述します。Claude Code はこれらのディレクトリを監視しているため、既存のスキルを編集すると、実行中のセッションに反映されます。セッション開始時に存在しなかった最上位の skills ディレクトリを作成した場合は、再起動が必要です。セッション開始時には監視対象が存在しなかったためです。

description フィールドは、ファイル内で最も効果の高い行です

起動時にエージェントは、利用可能なすべての skill の name と description をコンテキストに読み込みます。本文は読み込みません。リクエストを受け取った時点で、その 1 行だけを基準に skill が関連するかどうかを判断します。そのため、本文が完璧でも description が曖昧なら、本文は読まれません。

description は三人称で記述します。「nginx を安全にテストして reload する」は適切です。「nginx について支援できます」は適切ではありません。テキストは system prompt に挿入されるため、一人称ではモデル自身が話しているように読めるからです。

description には、skill が実行する内容と、適用する条件の 2 つを含めます。重要なユースケースを先に書いてください。Claude Code は一覧項目を 1,536 文字で切り捨てるためです。追加のトリガーフレーズやリクエスト例を記述する任意の when_to_use フィールドもあります。このフィールドは、同じ上限の範囲内で description の末尾に追加されます。

次に、実際に入力する言葉を使います。description: Helps with nginx は何にも一致しません。「helps with」と入力する人はいないからです。上の例では /etc/nginx、server block、reverse proxy、TLS (transport layer security) certificate path を明示しています。これは、この skill を起動すべきリクエストで使われる語彙にほぼ一致します。

description のテスト方法は次のとおりです。その 1 行と、これから入力するリクエストを、本文を一度も見たことがない人に提示し、その skill が適用されるか尋ねます。判断できない場合、モデルも判断できません。

本文は短くします。コンテキストに残り続けるためです

スキルを呼び出すと、レンダリングされた内容が1つのメッセージとして会話に入り、セッションの残りの期間も保持されます。Claude Code は、後のターンでファイルを再読み込みしません。記述した1行1行が、1回の回答ではなくセッション全体に対するコストになります。

Anthropic は、SKILL.md を500行未満に抑え、詳細を別ファイルへ移すことを推奨しています。コンパクションを考えると、この数値が任意ではない理由が分かります。コンテキストを解放するために会話が要約されると、Claude Code は各スキルの直近の呼び出しを再アタッチし、それぞれの先頭5,000トークンだけを保持します。そのうえで、直近に呼び出されたスキルから順に、合計25,000トークンの予算を埋めます。長いスキルは途中で切り捨てられます。長いスキルが複数あると、互いに完全に押し出されます。

そのため、モデルがすでに知っていることは書かず、未知の情報だけを記述します。nginx とは何か、リバースプロキシが何をするかは、モデルが知っています。一方、reload を restart 以上にするという独自ルールは知りません。このファイルが存在する理由は、そのルールだけです。

スキルから同梱スクリプトの実行をエージェントに指示する場合は、${CLAUDE_SKILL_DIR} を使ってパスを指定します。これにより、スキルのインストール先に関係なく解決されます。また、権限確認で実行が停止しないよう、同じコマンドを事前承認します。

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/check-and-reload.sh *)
---

この許可は、スキルを呼び出したターンに適用され、次のメッセージを送信すると解除されます。そのため、気付かないうちに永続的な許可になることはありません。

スキルが発動することを確認する方法

スキルの読み込みを監視すると、エージェントがスキルを見つけたことは確認できます。ただし、回答が変わったかどうかは分かりません。新しいセッションで、両方を確認してください。スキルを書いたセッションには、作成中に入力した内容がすでに残っているためです。その残ったコンテキストによって、ファイルの不足が見えなくなります。

1. プロジェクト内で claude を使い、新しいセッションを開始します。
2. スキル名を出さず、普段の業務で依頼するときの自分の言葉でリクエストを入力します。
3. 発動を確認します。スキルが発動しない場合は、description を修正します。まだ本文は問題ではありません。
4. 制御用として /nginx-config-changes で手動実行します。手動実行では正しく動作し、リクエストからは発動しても正しく動作しない場合、原因は指示ではなくトリガーにあります。
5. スキルを無効にして同じリクエストを実行し、2 つの回答を比較します。/skills メニューでスキルを選択し、Space を押して状態を off に切り替え、Enter を押して保存します。これにより .claude/settings.local.json に skillOverrides エントリが書き込まれます。完了したら、もう一度 Space を押すと状態が on に戻ります。
6. スキルが発動しないはずのリクエストを 2、3 件作成し、それらで発動しないことを確認します。

このループを自動化するには、公式マーケットプレイスから skill-creator プラグインをインストールします。

/plugin marketplace add anthropics/claude-plugins-official
/plugin install skill-creator@claude-plugins-official

インストール出力に Run /reload-plugins to activate. と表示された場合は、そのコマンドを実行します。次に、Claude にスキル名を指定して評価を依頼します。プラグインはスキルディレクトリ内の evals/evals.json にテストケースを保存し、各ケースを独自の subagent で実行します。そのため、毎回クリーンなコンテキストで開始されます。続いて with-skill と without-skill の比較を出力します。これは、スキルが消費するトークンと時間に対して測定した合格率の向上を示す、実質的な評価値です。

失敗モード: skill がまったく起動しない

リクエストを入力しても、agent が従来の誤った処理を実行し、skill の行が表示されません。以下を順に確認してください。

• 説明に skill の機能は書かれていますが、使用するタイミングが書かれていないため、リクエストと一致しません。
• 説明で、入力した語が避けられています。「nginx」と入力する場合、説明にも nginx と明記する必要があります。
• disable-model-invocation: true が frontmatter に設定されています。この設定により説明がモデルのコンテキストから完全に除外され、/name を使って呼び出した場合にのみ skill を起動できます。
• frontmatter の paths glob により、一致するファイルに対してのみ起動する設定になっています。作業対象のファイルが一致していません。
• skill が、開始ディレクトリの下にあるネストされた .claude/skills/ ディレクトリに配置されています。このような skill は、そのサブディレクトリ内のファイルを agent が読み取るか編集した後でのみ読み込まれます。それまでは skill を使用できません。

失敗パターン: スキルが常に起動する

反対の問題は、説明が広すぎて、スキルが無関係な作業でも起動することです。「サーバーで作業するときに使用する」と指定すると、サーバーリポジトリでのほぼすべての依頼に一致します。その結果、スキル本文が役に立たないタスクでも読み込まれ、その後のセッション中もコンテキストに残ります。

実際に必要な条件まで説明を絞り、対象となるファイルまたはコマンドを明記します。特定のファイルにだけ適用するスキルには paths glob を追加します。デプロイや commit などの副作用を伴う操作では disable-model-invocation: true を設定し、/name で自分から起動します。これにより、エージェントが独自にデプロイのタイミングを判断することを防げます。

失敗パターン: そのスキルは rules file に置くべきです

CLAUDE.md や AGENTS.md のような rules file は、すべてのセッションの開始時に読み込まれ、すべてのタスクに適用されます。スキルの本文は、そのスキルが起動した場合にのみ読み込まれます。判断基準は適用頻度です。パッケージマネージャーのようにリポジトリ内のすべてのタスクに当てはまる事実は、rules file に記述します。上記の nginx ルールのように、一部のタスクにだけ適用される手順は skill に記述します。nginx を編集しない日は、読み込みコストが発生しません。

本当の失敗は、同じ内容を両方に記述することです。2 つのコピーは次第に食い違い、エージェントが誤った動作をしたときに、どちらのコピーに従ったのか分からなくなります。各指示の配置先を 1 つに決めてください。skills、MCP servers、rules files の境界では、より難しいケースも扱います。たとえば、新しい指示ではなく新しいツールをエージェントに提供する MCP (model context protocol) server を選ぶべき場合などです。

実際の作業で役立つことを確認してから共有する

1 週間の実作業を乗り切ったスキルは、コミットする価値があります。.claude/skills/ 内のプロジェクトスキルはコードと同じようにレビューされ、リポジトリとともに提供されます。そのため、チームメンバーがクローンすれば、追加の設定なしで修正版を取得できます。コピーと貼り付けを使わずにリポジトリ間でスキルを移動する方法については、リポジトリ間でエージェントスキルを共有する方法で説明しています。

移植性について、1 点注意があります。Claude Code は多数の frontmatter フィールドを受け付けますが、Agent Skills standard で許可されているのは name、description、license、compatibility、metadata、allowed-tools の 6 つだけです。frontmatter にこれ以外のフィールドを含めたままスキルを claude.ai にアップロードしたり、Skills API 用にパッケージ化したりすると、そのフィールドを無視せず、処理全体が失敗します。

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

この 6 つのフィールドだけを使用すれば、同じファイルを Claude Code と、standard を読み込む他の環境で利用できます。別のモデルへ移しても機能するように命令自体を書く作業は別途必要です。その方法については、任意のモデルで動作するスキルを書く方法で説明しています。

FAQ

SKILL.md ファイルはどのくらいの長さにすべきですか？

500 行未満にしてください。実用的なスキルの多くは、それより大幅に短くなります。本文はスキルの呼び出し時に会話へ追加され、その後のセッション中も保持されます。そのため、各行は一度だけ発生するコストではなく、繰り返し発生するコストになります。長い参照資料はスキルディレクトリ内の別ファイルへ移し、SKILL.md から 1 階層の深さでリンクしてください。エージェントは必要な場合にだけ読み込めます。バンドルしたスクリプトは読み込まれるのではなく実行されるため、コストは出力分だけです。

スキルがまったく起動しないのはなぜですか？

通常の原因は description です。モデルが判断するときにコンテキストへ入っているスキルの部分は、description だけだからです。何をするスキルかだけでなく、いつ使用するかも記述してください。また、実際にリクエストで入力する語句を含めてください。description に問題がなさそうなら、frontmatter の disable-model-invocation: true を確認してください。これがあると、スキルはモデルから完全に隠されます。さらに、対象にしていないファイルだけに適用を限定する paths glob がないか確認してください。開始ディレクトリより下のネストした .claude/skills/ ディレクトリにスキルがある場合も原因になります。このスキルは、エージェントがそのサブディレクトリ内のファイルを読み取るか編集した後にだけ読み込まれます。

これはスキルにすべきですか、それとも rules ファイルの 1 行にすべきですか？

自分のタスクのうち、どの程度に適用されるかを考えてください。rules ファイルは毎回のセッションで読み込まれるため、パッケージマネージャーやブランチ命名規則など、すべてのタスクに当てはまる事実を記述します。スキルは起動した場合にだけ読み込まれるため、少数のタスクに関係する手順を置くのに適しています。同じ指示を両方に記述しないでください。2 つのコピーに差異が生じ、エージェントがどちらに従ったのか判断できなくなります。

スキルが実際に役立ったかどうかは、どう確認できますか？

ベースラインと比較してください。実際のリクエストをいくつか集め、それぞれをスキルが利用可能な新しいセッションで実行します。次に、/skills メニューからスキルを無効にして、同じリクエストをもう一度実行し、両方の回答を並べて確認します。新しいセッションを使うことが重要です。スキルを記述した会話には説明が残っているため、不完全なファイルでも完全に見えてしまうからです。skill-creator plugin はこの比較を代わりに実行し、トークンコストの横に合格率を表示します。

同じ SKILL.md を別のエージェントで使用できますか？

はい。ただし、Agent Skills standard で定義されているフィールドに限定してください。対象は name、description、license、compatibility、metadata、allowed-tools です。Claude Code はこれ以外にも多くのフィールドを受け付けます。また、他のツールでは実行されない、shell command injection などの本文機能もサポートしています。standard にないフィールドを含むスキルをアップロードすると、使用可能なプロパティの一覧を含む明示的なエラーが発生します。そのため、スキルを Claude Code 専用にするのか、別の環境へ移行するのかを早い段階で決めてください。