Perplexityにおけるエージェントスキルの設計、洗練、および維持

Perplexityのフロンティアエージェント製品は、モジュール化されたスキル（Agent Skills）にパッケージ化されたノウハウとドメイン専門知識を基盤としています。当社は、技術環境全体で厳選されたスキルのライブラリを維持しています。これらのスキルには、Perplexity Computerを動かす汎用ユーティリティ、金融・法律・医療などの分野における特定領域の能力、そしてユーザーのニーズに応えるための極めて広範なモジュールが含まれます。一部のスキルは頻繁には呼び出されませんが、呼び出された際には不可欠なものです。一貫して優れたユーザー体験を保証するため、Perplexityのエージェントチームはコードの品質と同等にスキルの品質を優先しています。

高品質なスキルを開発するために必要な直感とベストプラクティスは、従来のソフトウェア構築に必要なものとは大きく異なります。エージェントチームは、業務の過程でスキルを開発する優秀なエンジニアから多くのプルリクエストをレビューしています。その結果、ほぼ常に修正に向けた多数のコメントや提案が行われます。これは、コード作成における多くの有益なパターンが、スキルの作成においてはアンチパターンとなるためです。

例えば、PEP20 – The Zen of Python（Pythonの禅）のアフォリズムをいくつか取り上げると、優れたPythonコードを書くことが優れたスキルを書くこととは異なることがすぐに明らかになります。その20の教訓のうち、少なくとも半分は、スキルを作成する際には完全に間違っているか、あるいは積極的に誤解を招くものです。以下にその5つを挙げます。

PythonのZenと、Skillsの記述に関するこの記事の指針との5つの対比。

本ガイドは、Perplexityのエンジニアがスキルを開発およびレビューする際に使用する文書です。当社は、当社の発見と知見がより広いコミュニティの利益となるよう、このガイドを一般公開しています。日々の業務で本番環境のスキルを設計しているエンジニアの方、最適な分野で独自のスキルを開発しようとしているComputerユーザーの方、あるいはその両方の方にとって、本ガイドは有用なものです。

スキルとは何か？

スキルを作成する際、あなたは単なるソフトウェアを書いているのではありません（スキルが現在、エージェントシステムの主要な論理エンジンの一部であるとしても）。むしろ、あなたはモデルとその環境のためのコンテキストを構築しているのです。スキルには異なる制約と異なる設計原則があります。もしあなたがコードを書くようにスキルを書けば、失敗するでしょう。

スキルは、特にPerplexityで構築する方法という文脈において、少なくとも4つの性質を備えています。

スキルはディレクトリである

スキルは単一のSKILL.mdファイルではありません。多くの場合、スキルには複数のファイルが含まれます。スキル名で命名されたディレクトリの下には、以下のようなファイルが存在する可能性があります：

SKILL.md: フロントマターと指示

scripts/: エージェントが実行するコード（再発明ではなく）

references/: 条件付きで読み込まれる重要なドキュメント

assets/: テンプレート、スキーマ、データ

config.json: 初回実行時のユーザー設定

このハブアンドスポークパターンにより、スキルを非常に集中させ、緊密に保つことができ、フォルダ構造を非常に創造的に活用できます。場合によっては、特に複雑なスキルは、モデルがより適切にナビゲートできるように、複数階層の構造から恩恵を受けることがあります。仮に、スキルが300のトピックに関する知識を必要とし、それらが20の主題領域にグループ化できるとします。300の中から正しいトピックを確実に選択することは、今日の最高のフロンティアモデルにとっても解決されていない課題です。モデルにとっては、その領域内の15のトピックの中から選ぶよりも、20の領域の1つに焦点を絞る方がはるかに簡単な選択問題となります。

複数階層の構造が価値を提供する一例として、当社のチームは、前回の税務シーズンにComputerの米国所得税関連機能を動かすスキルにおいて、3レベルのトピック入れ子構造を採用しました。税法の複雑さを考えると、この階層は絶対的に不可欠でした。初期のテストでは、米国歳入法典の1,945のセクションすべてを含む単一のフォルダをモデルに提示すると、スキルを読み込まない場合よりもパフォーマンスが悪化しました。情報を論理的な細分に整理することは、高精度の読み取り操作を保証するために不可欠でした。

しかし、この階層は無償ではありません。階層レベルが増加すると、結果として生じる間接性を管理するために、情報アーキテクチャ全体にわたるキュレーションのレベルも引き上げる必要があります。当社は、モデルが最小限の間接性で情報を特定できるよう支援するために、クイックリファレンスガイド、カスタム検索ユーティリティ、およびその他のツールを考案しました。この場合、キュレーションという困難な作業を行ったことで、最終的に肯定的な結果が得られました。それは、汎用ツールだけを使用するよりも、モデルが税務関連のタスクをはるかに有能に遂行できるスキルを実現したことです。

拡大

スキルはフォーマットである

スキルはフォーマットです。コアとなるルートのSKILL.mdファイルには、名前と説明の両方が必要です。さらに、スキルはそのスキルが配置されているディレクトリ名と正確に一致する必要があります。名前はすべて小文字で、スペースを含まず、ハイフンを使用できます。説明はルーティングのトリガーとなります。これは一般的な失敗のポイントです。説明は、スキルが何をするかについての内部ドキュメントではありません。これは、モデルに対していつスキルを読み込むかという指示に相当します。そのため、「このスキルは〜する」ではなく、「〜の際に読み込む」と書かれているのを頻繁に見かけるでしょう。これは、ほとんどの実装が説明をモデルのコンテキストに注入する方法において重要です。

フロントマター内には、階層的なスキル依存関係を作成できる「depends:」と、レビューや評価に使用される「metadata:」もあります。異なるエージェントシステムは、それらのシステム固有の方法で使用される独自のフロントマターフィールドを定義することさえできます。代替手段として、スキル固有のメタデータを補助的なJSONまたはYAML設定ファイルにパッケージ化することも可能です。これは、モデルのコンテキストを細々とした情報で汚染することなく、スキルごとに異なるタイプの実行時動作を促進する必要があるエージェントシステムを構築する場合に望ましい方法です。最後に、同様の動作は、読み取り時にスキルのフロントマターを取り除くことによっても実現できます。Computerはこの手法を採用しており、これによりルートのSKILL.mdファイルに設定を保持できます。解析ロジックには細心の注意が必要であり、モデルコンテキスト内に保持することが有用な特定のフィールドがある場合は、条件付きの削除を実装することをお勧めします。

スキルは呼び出し可能である

スキルは呼び出し可能です。エージェントは実行時にスキルを読み込みます。重要な点として、スキルは常にコンテキストにバンドルされるわけではありません。デフォルトでは、ほとんどのエージェントシステムは、特定のニーズに応じてスキルを段階的に展開します。

Computerにおけるスキルの実装方法には、少なくとも3つのティアのコンテキストコストが存在します。そのプロセスは以下の通りです：

Computerがload_skill(name="...")を呼び出す

Computerがスキルディレクトリを分離された実行サンドボックスにコピーする

Computerが「depends:」タグ内の依存関係を再帰的に自動読み込みする

Computerがフロントマターを取り除き、エージェントは本体と追加ファイルのみを参照するようになる

エージェントシステムごとに、スキルのコンテンツを公開する方法を選択できます。例えば、ファイル階層をまったく公開せず、ファイルシステム操作を通じて階層を特定することをモデルに任せるシステムもあります。また、ある程度の切り捨てや深さ制限までファイルツリー全体のマッピングをモデルに提供することを選択するシステムもあります。コンテキストをクリーンに保つため、Computerは呼び出しコンテキストから完全なファイル階層を除外していますが、これはスキルごとに上書き可能です。

スキルは段階的である

スキルは段階的です。Computerには3つの異なるティアのコンテキストコストがあり、さまざまな段階でこれら3つすべてが発生します：

Skillコンテキストの3つの階層：インデックス、Skillの完全読み込み、実行時参照ファイル。

Computerは、利用可能なすべてのスキルの名前と説明を含むスキルインデックスを構築します。これに対する予算は、スキルあたり約100トークンです（短いほどさらに良い）。すべてのセッションで、すべてのユーザーに対してこのコストを支払っているため、非常に厳格です。これは会話の開始時にシステムプロンプトに注入されます。モデルは名前と説明の付いたスキルの束にアクセスできるため、「load_skill()」を呼び出すべきかどうかを判断できます。このインデックスに入るためのハードルは非常に高いです。スキルは非常に有用である必要があり、また全員が常にコストを支払っているため、説明は極めて密度が高く簡潔である必要があります。

エージェントシステムがスキルを読み込むと、SKILL.md の本文全体が続きます。理想的には、本文テキストは5,000トークンを超えないことです。それでも、スキルを読み込んだら、コンパクションの境界に達するまで、その負荷を会話の残りの部分が引き受けることになるため、各文に意味を持たせる必要があります。多くのスレッドでは、3つから5つの異なるスキルを読み込むため、このコストがさらに増大します。冗長な内容が多いスキルは、ほぼ確実に他のスキルだけでなく、全体的なエージェント能力も低下させます。要するに、スキルが読み込まれても適切に機能しないなら、それは無駄なコンテキストです。

段階的な進行の最終レベルは、スクリプトやサブスキル、フォーマットなどの特殊なケースです。ここでは、無制限の条件付き分岐ロジックを配置します。エージェントは必要な時のみこれを使用するため、ここに配置するものに対するハードルははるかに低くなります。

インデックスでは、すべてのトークンが重要です。読み込まれたスキル本文はより緩和されており、実行時は最も緩和されています。これは20,000トークンになることもあれば、0トークンになることもあります。これは、モデルのコンテキストを段階的に拡張することについて考えるかもしれないレベルです。

いつスキルが必要か？

エージェントチームは、特定のドメインやユースケースに対してスキルが本当に必要かどうかについて意見を求められることがよくあります。第一原理だけで決定的な答えを得られることはほとんどありません。これを正しく判断する唯一の方法は、スキルなしでエージェントを開始し、いくつかのヒーロークエリ（代表的なクエリ）を実行し、エージェントがうまく機能しているかどうかを確認することです。

スキルが必要な時

訓練済みモデルにとって「インディストリビューション（分布内）」のタスクは多く存在します。スキルを適用する必要があるのは、プロンプトの1文では不可能な特定の変更を加えたい場合のみです。つまり、特別なコンテキストなしではエージェントが間違えてしまう場合、あるいは実行間で極めて一貫性を保つ必要がある矛盾や非決定論が存在する場合にスキルが必要です。

知識は耐久性があるものの、訓練データには含まれていない場合があります。カットオフ（情報の遮断）や企業固有のワークフローが存在する場合もあれば、単なる好みの問題である場合もあります。例えば、ComputerにはHenry Modisett（当社のデザイン責任者）によって作成されたデザイン関連のスキルがいくつかあります。それらのスキルにすべてのトークンが存在する理由は、WebサイトやPDFのデザインに関してHenryが非常に優れたセンスを持っているからです。Henryは使用すべきフォントと避けるべきフォント、それらのフォントがどのような感触を与えるか、そしてトレーニングデータ単体では学習できないその他の判断事項を指定しています。

スキルが不要な時

エンジニアが一連のGitコマンドを順次実行するように記述したスキルを多く見かけます。これは不要です。モデルはすでにその方法を知っているため、素晴らしいドキュメントにはなりますが、スキルとしては不適切です。

スキルがシステムプロンプトからの指示を繰り返している例を見かけます。そのためにスキルは不要です。ほとんどのリクエストに関連する知識は、条件付きで読み込まれるスキルではなく、グローバルコンテキストに含めるべきです。

維持できる速度よりも速く変化するものがある場合、スキルは不要です。例えば、リモートのMCPエンドポイントにアクセスしていて、そのツールやツールのバージョンが頻繁に変更される場合、それらをスキルに注入すべきではありません。そうすると、ドリフトが生じ、モデルがミスを犯すことになります。

すべてのスキルは「税」である

スキル内のすべての文に適用できる有用なテストがあります：「この指示がなければ、エージェントは間違えるだろうか？」。その文が存在する必要がないのであれば、すべてのユーザーが毎回このコストを支払っているため、存在を許容することはできません。スキルを追加するかどうかを決定する際は、すべてのセッションとすべてのユーザーがトークンのコストを支払うというこの「税」を忘れないでください。

フランス語の方がはるかに響きの良い以下の有名な引用は、おおよそ次のように翻訳されます。「この手紙を長くしたのは、短くする時間がなかったからだ。」

« Je n’ai fait celle-ci plus longue que parce que je n’ai pas eu le loisir de la faire plus courte. » — Blaise Pascal, Lettres Provinciales, 1657

Pascalと同様に、すべてのスキルに時間を投資する必要があります。短いスキルを書くのは困難です。もしあなたのスキルが書くのが簡単であれば、それは長すぎるか、あるいは存在すべきではない可能性があります。優れたスキルとは、可能な限り短いものです。

もし、スキルの生成を一度で行い、5分でPR（プルリクエスト）を出そうとしているなら、結果はほぼ間違いなく標準以下になるでしょう。実際、LLMを使用してスキルを作成する場合、LLM自体はそこからおそらく恩恵を受けられないことが初期の研究で示されています：「自己生成されたスキルは平均して利益をもたらさず、モデルは自分が消費することで利益を得るはずのプロシージャルな知識を確実に作成できないことを示している。」

スキルの構築方法

言い換えれば、あなたが書くどのようなスキルにも、自分の意見を注入する必要があります。以下の手順に従ってください。

ステップ0：評価（Evals）を書く

まず評価の一部を作成します。評価ケースのソースは以下から取得できます：

実際のユーザークエリ：本番環境やあなたの「ブレイントラスト」からサンプリングする

既知の失敗：スキルが存在しなかったためにエージェントが失敗した例

近傍の混乱：ドメインの境界に近いが、別のスキルにルーティングされるもの

少なくとも、スキルが必要な時に読み込まれることをテストしているか確認すべきです。理想的には、本番環境などからこれらのいくつかをサンプリングします。既知のエラーケースも考慮してください。スキルを作成しようとした理由全体が、特定のエージェントの失敗に基づいているかもしれません。あるいは、リファクタリングを行っていて、単一のスキルでカバーされる2つの近いドメインで混乱が生じている可能性もあります。

類似のネガティブ例とポジティブ例から始めてください。ネガティブ例は非常に強力であり、ポジティブ例よりも重要な場合があります。

ステップ1：説明

これはスキルの中で最も難しい一行です。これはルーティングのトリガーであり、ドキュメントではありません。名前と説明を正しく設定するために、スキルの内容については考えないでください。スキルが適切な箇所で読み込まれ注入されているかどうか、そしてターゲット外の副作用がないかどうかのみを気にしてください（これが最大の失敗モードです）。スキルを追加するたびに、他のすべてのスキルをわずかに劣化させるリスクがあるため、回帰を最小限に抑える必要があります。

繰り返しになりますが、悪い説明はスキルが何をするか、あるいはなぜ有用かについて記述します。優れた説明は、エージェントがいつスキルを読み込むべきかを示します。例えば、プルリクエストを監視するためのものがあるとします。スキルが何をするかを書くのではなく、エンジニアがPRが機能することを確認したいときに使う、「babysit（見守る）」、「watch CI（CIを監視）」、「make sure this lands（必ずマージさせる）」のような苛立ちを含んだ表現を書きましょう。

以下は簡単なチェックリストです：

"Load when...（〜の際に読み込む）"で始める

50語以下を目指す

実際のクエリから、ユーザーの意図を記述する

ワークフローの要約はしない

実際のクエリは、80-20の法則でカバーできるものです。通常、2つか3つの例がうまく機能します。必要十分な量だけを追加することは簡単ではありません。

ステップ2：本体を書く

次に、スキル自体の内容を書きます。これがステップ0や1ではないことに注意してください。

ワークフローをLLMに伝えることは、同僚や実行システムに伝えるのとは全く異なります。新しいソフトウェアツールを学ぶ際、エンジニアはドキュメントを読み、経験者からウォークスルーを受け、ツールの使い方を学ぶ必要があるかもしれません。一方、少なくとも1年以上存在しているほぼすべてのソフトウェアツールについて、名前を挙げるだけでLLMは必要な情報をすべて把握しています。

本体を書く際は、明白なことは飛ばしてください。多くのエンジニアは、誰かが実行すべきすべてのコマンドをリストアップするREADME.mdファイルを書く経験が豊富です。スキルを書くときはドキュメントを書いているように感じてしまい、そこに立ち戻るのが簡単ですが、そうするとスキルはゴミになります。ですから、一連のコマンドを書き出さないでください。

例えば、「git log # コミットを特定; git checkout main; git checkout -b <clean-branch>; git cherry-pick <commit>;」と書く必要はありません。

代わりに、「クリーンなブランチでコミットをチェリーピックせよ。意図を保持して競合を解決せよ。きれいにマージできない場合は理由を説明せよ。」と書きます。

モデルは、特に問題が発生した際、前者のような過度に指示的な一連のコマンドよりも、後者の方がはるかに良い仕事をしてくれます。脆弱になるため、指示過多になったり過度に規定的になったりしないでください。代わりに、複数のアプローチが機能しうる柔軟性を持たせてください。繰り返しますが、人間にとって優れたドキュメントは、モデルにとって悪いドキュメントであることがほとんどです。

次に、落とし穴（Gotchas）やネガティブな例に焦点を当ててください。これらは、何をすべきでないかという点でモデルをガイドすることが多いため、非常に価値の高いコンテンツです。エージェントがつまずくたびに行を追加していけば、実行することで学習し、落とし穴は有機的に増えていきます。

最後に、条件付きの部分や内容量が極端に重い部分があるなら、ハブである SKILL.md からそれを切り離し、スポークの1つに置いてください。段階的に読み込める付属ファイルに入れ、次にその仕組みを詳しく見ていきます。

ステップ3：階層を利用する

スクリプトやリファレンスがある場合、または特定のツールを使用している場合は、スキルの階層を活用してください：

Skill内でのスクリプト、参照、アセット、設定の推奨用途。

メインのスキルから条件付きまたは分岐するものは何でも、フォルダに切り出してください。また、特に複雑なスキルにはマルチレベルの階層が使用できることも覚えておいてください。これらについては、機能をモノリシック（単一構成）に実装すべきか、スキルのコレクション（おそらくdepends:に基づく読み込み関係を伴う）として実装すべきか、注意深く検討する必要があります。

ステップ4：反復する

次に、ブランチ上で何度も反復を行ってください。メインブランチからスキルなしで開始し、いくつか反復を行い、ヒーロークエリセットを構築し、大量の評価を実行します。あなたのスキルコードをレビューする人は、評価セット一式が揃った単一のチェンジセットを提出してくれたことに感謝するでしょう。連続した漸進的な変更（新しい落とし穴以外）をレビューするのは非常に困難なので、最小限に抑えるようにしてください。

おそらく多くの小さな単語の変更を行うことになるでしょう。説明における小さな変更は、ルーティングに大きな影響を与える可能性があるため（他のスキルへの波及効果を含む）、ステップ5の前にすべての作業を完了させてください。

ステップ5：出荷

出荷してください。

スキルの維持方法

スキルを書き終えたら、それを維持しなければなりません。

落とし穴のフライホイール（相乗効果）

この時点から、落とし穴のリストは大幅に増えたり変化したりする傾向があります。評価されていないPR（プルリクエスト）を作成して説明を変更するエンジニアをよく見かけます。スキルがマージされた後に説明を変更している場合、あなたは軌道から外れています。スキルをルーティングするかどうかを決定する要素に変更を加えている場合は、その変更をサポートする評価をいくつか書く必要があります。

スキルは「アペンド・モストリー（追記型）」です。落とし穴セクションが時間の経過とともに最も価値を蓄積します：

エージェントが何かに失敗する → 落とし穴を追加

エージェントがターゲット外のスキルを読み込む → 説明を厳格化し、ネガティブな評価を追加

エージェントが読み込むべき時にスキルを読み込まない → キーワードとポジティブな評価を追加

システムプロンプトの変更 → 競合や重複がないか確認

社内テストや本番環境での単一の失敗例に気づき、落とし穴を追加するのは簡単です。それはネガティブな例であるため、明示的なガイダンスを実際に変更しているわけではありませんが、モデルに「ねえ、こんな既知の失敗があるよ」と知らせるものです。

80-20の法則から99.9%や99.99%の成功率を目指す過程で、この落とし穴リストを増やすのは簡単です。これらのネガティブな例を見たら、落とし穴セクションに追記してください。長い指示を追加したり、説明を変更したりすべきではありません。

評価スイート

Perplexityでは、さまざまなことをチェックするために多くの評価スイートを実行しています。スキルの読み込みとスキルファイルの読み取りがあり、これによってスキルの読み込み自体の精度、再現率、禁止事項のチェックが行われます。エージェントは意図した通りにスキルをルーティングするでしょうか？これらは、新しいスキルが既存の境界を壊さないことを保証します。

適切な段階的読み込みをチェックする評価もあります。エージェントはスキルを読み込むかもしれませんが、アクセサリーファイルは読み取るでしょうか？例えば、金融クエリ用の金融スキルがある場合、特別なFORMATTING.mdファイルを読み取るでしょうか？

ドメイン内でのエンドツーエンドのタスク完了をテストするスキルの評価もあります。完全なエージェントループを実行し、LLMジャッジを使用して、よく定義された基準のルーブリックに基づき結果を採点します。

最後に、これらの評価を異なるモデルに対して実行することが重要です。Computerは少なくとも3つの異なるオーケストレーションモデルファミリー（GPT、Claude Opus、Claude Sonnet）をサポートしています。異なるエージェントオーケストレーターに対してスキルの読み込みとドメインスキルを実行し、動作に違いが出ないことを確認する必要があります。SonnetとGPTは、スキルに関しては非常に異なる動作をします。

最終的な考えと要点

スキルを構築すればするほど、構築が上手くなります。もしあなたがスキルを使って自動化を行ったり、日常的なタスクの再現性を高めようとしたりしていないのであれば、今すぐ始めてください。

スキルを構築する行為はスキルの構築スキルを向上させますが、ビジネスプロセスの自動化にも極めて優れています。スタンドアップミーティングの前、スプリントの最後など、毎週行うことや、エンジニアとして日次、週次、あるいは四半期ごとに行うことを説明できるなら、時間を買い戻すためにスキルを書くべきです。

ポストモーテム（事後分析）を自動化できますか？プルリクエストをレビューできますか？あなたができるどんなタスクであっても、少なくとも最初のパスはエージェントスキルに任せることができます。大幅な時間を節約できるでしょう。

とはいえ、スキルが簡単だとか、常に必要だとは限らないことを忘れないでください。「レス・イズ・モア（少ないことはより豊かである）」です。その他の要点：

スキルの前に評価を書く。隣接するが異なるスキルのためのネガティブ例や禁止読み込みを含める。

説明が最も難しい部分です。「Load when...（〜の際に読み込む）」と書く（すべての単語が注意力のコストになる）。

落とし穴は非常に価値の高いコンテンツです。薄く始め、エージェントが失敗するにつれて増やしていく。

新しいスキルを追加すると、触れていない既存のスキルを壊す可能性があることを忘れないでください（遠隔作用に注意）。

スキルを書く・維持する際は、利用可能なすべてのツールを使用してください。詳細を知りたい場合は、Agent SkillsのWebサイトに良い例が多数あり、当社の社内リポジトリとパブリックエコシステムの両方に、よく設計されたスキルの例が多く含まれています。

引用

@online{perplexity2026DesigningRefiningAndMaintainingAgentSkillsAtPerplexity,
  author = {{Perplexity} and Marshall Kiely and Daisy Lee and Jerry Ma and Lauren Kolm},
  title = {{Designing, refining, and maintaining agent skills at Perplexity}},
  date = {2026-05-01},
  url = {https://www.perplexity.ai/hub/blog/designing-refining-and-maintaining-agent-skills-at-perplexity}
}