Agent Skillsを設計・配布する方法

TL;DR

Agent Skillsは、指示文だけでなくスクリプト、参考資料、アセット、フックを含むフォルダーとして設計する。SKILL.mdは段階的開示で薄く保ち、具体的な罠を記録し、JSONやYAML、使用ログによって必要な部分だけを決定論的に調整する。

Transcript

おすです。本日はですね、アンソロピック の公式ブログで、ま、車内でですね、数百 個のスキルとかを運用して掴んだ作り方と 配り方みたいな形で面白いブログが登場し てましたんでね、今回皆さんに解説して いきたいという風に思います。ま、僕も ですね、エージェントスキルはもう毎日の ように使ってるし、作ってるしみたいな 感じで、ま、皆さんもですね、え、ま、 スキルに関してのいろんな地見集めてるか なと思うんですけども、ま、公式からです ね、ま、なかなか面白い、え、読み応えの ある記事が、ま、登場してましたと。 こんな感じでですね、ま、公式ブログ出て たんですけど、はい。ま、ざっくりね、 どういうこと言ってるのかとか、ま、僕が どう考えてるのかとかね、含めて、ま、 今回はね、僕の方で紙砕いたというか、... Read More

Key Insights

• Agent Skillsは、SKILL.mdだけでなく、スクリプト、参考資料、アセット、フックを収められるフォルダーであり、説明と実行資源を一体化できる。
• 決定論的に処理したい部分は、自然言語の指示を増やすよりもスクリプトやフックへ移し、決められた段階でコードとして実行する設計が有効である。
• スキルの用途は、API参照、動作検証、データ取得分析、ランブック、運用、自動化、ひな型生成、コード品質、デプロイなどに分類できる。
• 良いスキルは、モデルが既に理解できる一般論を繰り返さず、実際に失敗した条件、固有名、回避策など、次の実行で役立つ具体的な罠を記録する。
• 段階的開示は、名前とdescriptionを常時参照できる入口にし、SKILL.mdや個別資料を必要になった時点で順番に読ませる情報設計である。
• SKILL.mdは、完了に必要な情報を保ちながら薄くし、詳細な例や参考資料を別ファイルへ分けることで、不要なコンテキストとノイズを抑えられる。
• エージェントの挙動は、最初から手順で縛り切らず、目的と理由を与えて試行し、揺れが大きい箇所だけJSONやYAMLで選択肢を狭める。
• スキルのdescriptionは単なる機能の要約ではなく、どの状況で発火すべきかを記述し、エージェントが適切なタイミングで選べるようにする。
• 配布方法は、プロジェクト固有の知識ならリポジトリ、複数案件で再利用するものならプラグインなどを選び、利用するハーネスとの互換性も考慮する。
• 使用ログは、よく使われるスキルと使われないスキルを把握し、失敗時の挙動を調べ、内容や発火条件を改善するための健康診断として利用できる。
• 🎬 このチャンネルの他の動画:
  • ハーネスエンジニアリングとは何か？
  • Antigravity 2.0の4製品の違いとは？
  • Qwen3.8-27Bの実力と用途は？
• 📺 このチャンネル: まさおAIじっくり解説ch

Questions & Answers

Q: Agent Skillsを作る方法は？

Agent Skillsは、まず対象業務を一つに絞り、SKILL.mdに目的、発火条件、必要な進め方を記述して作る。詳細資料は参考ファイルへ分離し、確実に実行したい処理はスクリプト、継続的な制御はフックとして同じフォルダーに配置する。実行後はログを確認し、必要な箇所だけ制約を追加する。

Q: Agent Skillsのフォルダーには何を入れますか？

Agent Skillsのフォルダーには、中心となるSKILL.mdに加えて、スクリプト、参考資料、アセット、フックなどを入れられる。テンプレートやJSON、YAMLのような定型データも格納し、手順の中で必要になった時だけ参照させる。これにより、説明だけでなく実行に必要な資源もまとめて管理できる。

Q: SKILL.mdを薄く保つ方法は？

SKILL.mdを薄く保つには、名前、description、主要な判断基準、参照先への導線だけを中心に置き、長い例や専門資料を別ファイルへ移す。フェーズごとに読む資料を指定すれば、エージェントは必要な時点で必要な情報だけを取得できる。ただし、分割によって作業完了に必要な文脈が欠けないよう、リンク切れにも注意する。

Q: Agent Skillsで段階的開示を使う方法は？

段階的開示は、最初にスキル名とdescriptionだけを候補情報として持たせ、必要と判断された時にSKILL.mdを読ませる方法である。さらにSKILL.md内でフェーズ別の参考資料を案内し、現在の工程に該当するファイルだけを取得させる。情報を一度に詰め込まず、作業の進行に合わせてコンテキストを追加できる。

Q: Agent Skillsのdescriptionには何を書くべきですか？

descriptionには、スキルが何をするかだけでなく、どのような依頼や状況で発火すべきかを書く。要約だけでは選択の判断材料が不足するため、対象タスクや利用条件を短く具体化することが重要である。この情報はエージェントが常に参照する入口となり、適切なスキルを呼び出すために使われる。

Q: Agent Skillsの挙動を安定させる方法は？

挙動を安定させるには、まず目的と理由を示して複数回動かし、揺れや失敗が生じる部分を確認する。その後、出力形式や選択肢をJSONやYAMLで限定し、確実性が必要な処理をスクリプトやフックへ移す。最初から全手順を固定すると柔軟性を失うため、ログに基づいて制約の強さを調整する。

Q: Agent Skillsに具体的な罠を残す方法は？

具体的な罠は、一般的な注意事項ではなく、失敗した条件、対象の名前、起きた問題、回避方法が分かる形でSKILL.mdの専用セクションなどへ残す。同じ失敗が繰り返される場合は、記述を増やすだけでなく、スクリプトやフックで自動的に防げるか検討する。これにより、スキルを運用経験から継続的に育てられる。

Q: Agent Skillsをリポジトリとプラグインのどちらで配布すべきですか？

特定のプロジェクトでしか使わないドメイン知識や、その知識に基づくスキルはリポジトリに置くのが適している。一方、複数のプロジェクトで再利用するスキルは、保守しながら必要な場所へ導入できるプラグインなどでの配布が候補になる。ただし、利用者が異なるハーネスを使う場合は仕様差と移植性を考慮する。

Q: Agent Skillsの使用状況を改善に生かす方法は？

使用状況を改善に生かすには、ツール利用前のフックなどを通じて、どのスキルがいつ使われたかをログへ残す。頻繁に使われるスキル、使われないスキル、失敗が起きたセッションを比較すれば、descriptionの発火条件や内容を見直せる。ログは推測ではなく実際の運用状況に基づく健康診断として機能する。

Q: Claude Code用のスキルを他のエージェントへ移植できますか？

Claude Code用のスキルは、すべてをそのまま他のエージェントへ移植できるとは限らない。YAMLフロントマターの項目、モデルの努力レベルに関する指定、ユーザーフラグ、フックの仕組みなどがハーネスごとに異なるためである。共通化する場合は、移植先で対応する機能を確認し、固有設定を分離して書き換える必要がある。

Summary & Key Takeaways

• Agent Skillsは、単一のMarkdownではなく、SKILL.md、スクリプト、参考資料、アセット、フックなどをまとめたフォルダーとして扱う。確実に実行したい処理はコードへ寄せ、テンプレートや設定形式も同梱することで、必要な情報の位置をエージェントが把握しやすくする。ただし、フロントマターやフックの仕様はハーネスごとに異なり、そのまま移植できるとは限らない。

• SKILL.mdは、名前とdescriptionを入口にした段階的開示で構成する。最初から全資料を読み込ませず、現在のフェーズに必要な参考ファイルだけをリンクから取得させる。一般論を増やすのではなく、実際に遭遇した具体的な罠や次の利用者が迷う点を残すことが重要である。繰り返し起こる問題は、注意書きのままにせずスクリプトやフックへ移す。

• 手順を細かく固定しすぎるとエージェントの能力を狭めるため、まず目的と理由を示し、実行結果を見ながら制約を調整する。出力の揺れが大きい場合はJSONやYAMLで取り得る値を限定し、セッションやツール使用のログから失敗を発見する。プロジェクト固有の知識はリポジトリに置き、再利用可能なスキルはプラグインなどで配布し、利用状況も継続的に点検する。