著者 独自のエージェントスキルの作り方とテスト方法
実際の失敗を1つのスキルに変換します。SKILL.mdの構成、発動を決めるdescriptionの1行、同じ依頼で効果を検証する方法を解説します。
実際の失敗から独自のエージェントスキルを作成する
独自のエージェントスキルを作成する最善の方法は、実際の失敗から要点を抽出することです。コーディングエージェントが 2 回誤ったタスクを見つけ、両方のときに入力した修正内容を書き留めます。その修正内容を、エージェントが自動的に読み込める SKILL.md ファイルとして保存します。それ以降に必要なのは、ファイルの構成と、そのスキルを実際に発動させるかどうかを決める 1 行の設定だけです。
この順序が重要です。想像で作成したスキルは、実際には経験していない問題を記録するだけで、毎回のセッションでコンテキストも消費します。実際に観察した失敗から抽出したスキルには、独自のテストも付いてきます。同じ依頼をもう一度行い、今度はエージェントが正しく処理できるか確認できます。形式自体が初めての場合は、まず エージェントスキルとは何か、エージェントがどのように読み込むか を読んでから、スキルを作成してください。
2 回失敗したタスクから始める
1 回なら偶然です。2 回ならパターンであり、ファイルに記録する価値があります。
実際のサーバーで繰り返し発生する失敗を見てみましょう。エージェントに nginx のリバースプロキシブロックを追加するよう依頼します。エージェントは /etc/nginx/conf.d/app.conf を編集し、その後 sudo systemctl restart nginx を実行します。編集内容に誤記があるため 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 行がスキルになります。依頼は、トリガーが一致すべき内容を示します。修正内容が、スキル全体の内容になります。
Anthropic 自身の作成ガイダンスでも、これを最初に行うよう示されています。スキルなしで代表的なタスクをエージェントに実行させ、どこで失敗するかを記録し、その失敗を修正する最小限の指示を書きます。失敗が仕様になるため、どの失敗にもさかのぼれないスキルは、通常、誰にも必要とされていなかったスキルです。
同じ抽出手順の実例として、依頼以上の範囲を何度も書き換えるエージェントという失敗を、Ponytail が 1 つのスキルに変える例を、独自のスキルを書く前に最初から最後まで読めます。
スキルの構成
スキルは、必須ファイルを1つ含むディレクトリです。
.claude/skills/nginx-config-changes/
├── SKILL.md
├── reference/
│ └── proxy-headers.md
└── scripts/
└── check-and-reload.shSKILL.mdで始まるのは、YAML で記述したいくつかの設定を含む frontmatter ブロックです。これは --- マーカーで囲みます。続いて、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行のスクリプトでも負担は小さくなります。
スキルが完全な構成へ発展するのは、そのスキルが是正する挙動が根強く、専用の構成を必要とする場合です。unlazy skill はその余地を Depth Tree、複数のゲートファイル、PLAN.md の契約に充てます。これにより、作業の大部分のブランチが未着手のままなのに、エージェントが完了を宣言することを防ぎます。
ディレクトリを置く場所によって、スキルを利用できる範囲が決まります。
.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 は 3 人称で書きます。"Tests and reloads nginx safely" は適切です。一方、"I can help you with nginx" は適切ではありません。テキストは system prompt に挿入されるため、1 人称ではモデル自身が話しているように読めるからです。
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回の回答だけでなく、セッション全体に及びます。
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 *)
---許可はスキルを呼び出したターンに適用され、次のメッセージを送信すると解除されます。そのため、気付かないうちに永続的な許可になることはありません。
スキルが発動することを確認する方法
スキルの読み込みを監視すると、エージェントがスキルを検出したことは確認できます。ただし、回答が変わったことまでは分かりません。両方を確認し、必ず新しいセッションでも確認してください。スキルを作成したセッションには、作成中に伝えた内容がすでに残っているためです。その残ったコンテキストによって、ファイルの不足が見えなくなります。
- プロジェクト内で
claudeを使って新しいセッションを開始します。 - スキル名を出さず、普段の作業日に自分の言葉で依頼を入力します。
- スキルが呼び出されたか確認します。発動しない場合は、説明を修正します。まだ本文が問題とは限りません。
/nginx-config-changesを使って手動で呼び出し、対照テストを行います。手動では正しく動作し、依頼時には正しく動作しない場合、問題は指示ではなくトリガーにあります。- スキルを無効にして同じ依頼を実行し、2 つの回答を比較します。
/skillsメニューでスキルを選択し、Spaceを押して状態をoffに切り替え、Enterを押して保存します。これにより.claude/settings.local.jsonにskillOverridesのエントリが書き込まれます。完了したら、もう一度Spaceを押すと状態がonに戻ります。 - スキルを発動させない依頼を 2 件ほど作成し、その場合に発動しないことを確認します。
このループを自動化するには、公式マーケットプレースから 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 にテストケースを保存し、各ケースを独自のサブエージェントで実行します。そのため、毎回クリーンなコンテキストで開始されます。続いて、スキルを使った場合と使わない場合の比較を出力します。これが実際に見るべき数値です。スキルによる合格率の改善を、スキルが消費するトークン数と時間に対して測定したものです。
スキル自体に検証手順を含めることもできます。別の評価実行に任せるのではなく、Old Coder スキルがエージェントに自分で再実行できる証拠レポートを返させる方法がこれに当たります。
失敗の種類: skill がまったく起動しない
リクエストを入力しても、agent が従来の誤った処理を行い、skill の行が表示されない場合があります。次の項目を順番に確認してください。
- description には skill の機能が書かれていても、使用するタイミングが書かれていないため、リクエストと一致していません。
- description が、入力した語を避けています。たとえば「nginx」と入力する場合、description にも nginx と記載する必要があります。
disable-model-invocation: trueが frontmatter に設定されています。これにより description がモデルのコンテキストから完全に除外され、/nameを使った場合にだけ skill を起動できる状態になります。- frontmatter の
pathsglob により、対象ファイルが一致する場合だけ起動するよう制限されています。作業中のファイルが一致していません。 - skill が開始ディレクトリ以下の入れ子になった
.claude/skills/ディレクトリにあります。この場所の skill は、そのサブディレクトリ内のファイルを agent が読み取るか編集した後にだけ読み込まれます。そのため、それまでは skill を利用できません。
障害パターン: スキルが常に発動する
反対に、説明が広すぎると、スキルが関係のない作業でも発動します。「サーバーで作業するときに使用する」という条件は、server リポジトリ内のほぼすべての依頼に一致します。その結果、本文が役に立たないタスクでも読み込まれ、その後のセッション中もコンテキストに残ります。
実際に重要な条件まで説明を絞り、対象となるファイルまたはコマンドを明記します。特定のファイルにだけ適用する場合は、paths glob を追加します。deploy や commit など副作用を伴う処理では、disable-model-invocation: true を設定し、/name で自分から呼び出します。これにより、エージェントが独自に deploy の適切なタイミングだと判断することを防げます。
失敗パターン: その手順はルールファイルに置くべきです
CLAUDE.md や AGENTS.md のようなルールファイルは、すべてのセッションの開始時に読み込まれ、すべてのタスクに適用されます。スキルの本文は、そのスキルが起動した場合にのみ読み込まれます。判断基準は頻度です。リポジトリ内のすべてのタスクに当てはまる事実（使用するパッケージマネージャーなど）は、ルールファイルに置きます。nginx に関する上記のルールのように、一部のタスクにだけ適用される手順はスキルに置きます。nginx を編集しない日は、その読み込みコストが発生しないためです。
本当の失敗は、同じ内容を両方に置くことです。2 つのコピーは次第に食い違い、エージェントが誤った動作をしたときに、どちらのコピーに従ったのか分からなくなります。各指示の置き場所は 1 つに決めてください。1 つの場所にだけ存在するルールが、それでも無視される場合は別の問題です。スキルへ移して解決することを期待する前に、無視された指示が処理される仕組みを確認する価値があります。スキル、MCP サーバー、ルールファイルの境界では、より難しいケースも扱います。適切な答えが、新しい指示ではなく新しいツールをエージェントに提供する MCP (model context protocol) サーバーになる場合も含まれます。
必要な価値が確認できたら共有する
実際の作業で 1 週間使い続けられたスキルは、コミットする価値があります。.claude/skills/ のプロジェクトスキルはコードと同じようにレビューされ、リポジトリと一緒に提供されます。そのため、チームメイトがクローンすれば、追加の設定なしで修正版を利用できます。コピーと貼り付けを使わずにリポジトリ間でスキルを移動する方法については、リポジトリ間でエージェントスキルを共有する方法で説明しています。
移植性について、1 点注意が必要です。Claude Code は多数の frontmatter フィールドを受け付けますが、Agent Skills 標準で許可されているのは 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 と、標準を読み込む他の環境で利用できます。ただし、ファイルを読み込む環境によって実行できることは変わります。Cowork は Anthropic のサンドボックスで実行される一方、Claude Code は自分のマシンまたは VPS で実行されるためです。そのため、上記の nginx スキルはチームメイトのチェックアウトに持ち込む価値がありますが、サーバーに接続できないサンドボックスでは役に立ちません。異なるモデルでも機能するように手順自体を書く作業は別途必要です。どのモデルでも機能するスキルの書き方で説明しています。
FAQ
SKILL.md ファイルはどのくらいの長さにすべきですか？
500 行未満にしてください。実用的なスキルの多くは、それよりかなり短くなります。本文はスキルの呼び出し時に会話へ追加され、その後のセッション中も残るため、各行は一度だけではなく繰り返し発生するコストになります。長いリファレンス資料はスキルディレクトリ内の別ファイルに移し、SKILL.md から 1 階層までのリンクを張ってください。そうすれば、エージェントは必要なときだけ読み込めます。バンドルされたスクリプトは読み込まれるのではなく実行されるため、コストは出力分だけです。
スキルがまったくトリガーされないのはなぜですか？
通常の原因は説明です。モデルが判断するとき、コンテキストに含まれるスキルの情報は説明だけだからです。説明にはスキルが何をするかだけでなく、いつ使うかを記載してください。また、実際のリクエストで入力する語句も含めてください。説明に問題がなければ、frontmatter の disable-model-invocation: true を確認してください。この設定があると、スキルはモデルから完全に隠されます。また、操作対象ではないファイルに限定する paths glob が設定されていないかも確認します。開始ディレクトリ配下のネストした .claude/skills/ ディレクトリにスキルがある場合も原因になります。このスキルは、エージェントがそのサブディレクトリ内のファイルを読み取るか編集した後でないと読み込まれません。
これはスキルにすべきですか、それともルールファイルの 1 行にすべきですか？
どの程度のタスクに適用するかを考えてください。ルールファイルはすべてのセッションで読み込まれるため、パッケージマネージャーやブランチ命名規則など、すべてのタスクに当てはまる事実を記載します。スキルはトリガーされた場合だけ読み込まれるため、少数のタスクに関係する手順を置くのに適しています。同じ指示を両方に記載しないでください。内容に差異が生じ、エージェントがどちらに従ったのか判断できなくなります。
スキルが実際に役立ったかどうかは、どう確認できますか？
ベースラインと比較してください。実際のリクエストをいくつか集め、スキルを利用できる状態で新しいセッションごとに実行します。その後、/skills メニューからスキルを無効にして同じリクエストを再実行し、両方の回答を並べて確認します。新しいセッションを使うことが重要です。スキルを作成した会話には説明が残っているため、不完全なファイルでも完全に見えてしまうからです。skill-creator プラグインを使うと、この比較を自動的に実行し、合格率をトークンコストの横に表示します。
同じ SKILL.md を別のエージェントで使用できますか？
はい。Agent Skills 標準で定義されているフィールド、つまり name、description、license、compatibility、metadata、allowed-tools の範囲内にとどめる場合は使用できます。Claude Code はこれより多くのフィールドに対応しており、他のツールでは実行されない shell command injection などの本文機能もサポートしています。標準外のフィールドを含むスキルをアップロードすると、使用可能なプロパティを列挙した明示的なエラーが発生します。そのため、スキルを Claude Code 内だけで使うのか、別の環境へ移行するのかを早い段階で決めてください。