※本記事は2026年5月29日に米国で公開された Build a Salesforce Agent Skill with Claude Codeの抄訳です。本記事の正式言語は英語であり、その内容および解釈については英語が優先されます。

AIにコードを書かせるのは簡単です。とはいえ、セキュリティレビューに合格し、ガバナ制限を守り、指定したフレームワークに従い、静的解析でも高い評価を得られるコードを安定して生成させるとなると、そう簡単にはいきません。エージェントスキル（英語）を使えば、この問題を解決できます。エージェントスキルとは、開発チームが定義する「本番品質」を、エージェントが従い、検証ツールが強制できる形に落とし込んだ、構造化されたプロンプトパッケージです。LLMの出力には確率的なばらつきがあるため、どうしても例外的な結果が生じます。それを想定して検出するのが、このアーキテクチャーです。

この記事では、Apexを例に、Salesforceエージェントスキルの構造を詳しく見ていきます。わかりやすいように、Claude Codeを使って具体的な例を紹介しますが、ここで取り上げる原則はどのAIエージェントにも適用できます。エージェントスキルとは何か、プロジェクトの構造、最初のスキルの作成方法について、順を追って説明していきます。

エージェントスキルとは

エージェントスキルとは、Claudeを汎用的なアシスタントではなく、スペシャリストとして使えるようにするために構造化されたプロンプトパッケージです。スキルでは、モデルの学習データだけに頼るのではなく、明確に定義されたワークフロー、リファレンス、コードテンプレート、自動検証ツールを用意します。スキルが有効化されると、これらがコンテキストに読み込まれます。

Claudeの基盤である大規模言語モデル（LLM）は、Apex、LWC、SOQLといったSalesforceエコシステムのプログラミング言語をすでに習得しています。しかし、プログラミング言語を理解しているからといって、必ずしもベストプラクティスに沿った高品質なコードを安定して生成できるわけではありません。スキルは、これを可能にします。

各スキルは、次のような一定の構造を持つフォルダー内に配置されます。

最低限必要なのは、SKILL.mdです。これは、スキルの有効化時にClaudeが最初に参照するファイルです。その他の要素は、スキルの成長に応じて追加する足場となります。まずはSKILL.mdと参照ドキュメントを1つずつ用意し、指示だけではなく、仕組みによってルールを徹底したい段階でフックを追加するとよいでしょう。

スキルは、フロントマターにもとづいて有効化されます。フロントマターは、Markdownファイルの先頭で区切り記号「---」の間に記述されるYAML形式のメタデータブロックです。フロントマターはコンテンツとして表示されず、機械が読み取れる設定情報として使用されます。フロントマターは、どのような場合にそのスキルを有効にするかをエージェントに示します。nameフィールドでスキルを識別し、descriptionフィールドには、現在のタスクにこのスキルが適しているかどうかを判断するためのトリガールールを記述します。

以下の例では、descriptionでTRIGGER when / DO NOT TRIGGER whenという構造を使用して、スキルを有効にする条件と有効にしない条件の両方をエージェントに示しています。有効化の条件だけをモデルに伝えると、「このSOQLはApexコードの作成作業としてApexスキルで扱うのか、それともSOQLスキルで扱うのか」といったあいまいさが生じ、誤ったスキルが有効化されることがあります。この形式を使えば、そうしたあいまいさを排除できます。

この例は簡略化されたもので、実際には、descriptionにはもっと包括的な情報を記述します。すべてのクラス種別（Schedulable、AuraEnabled、HttpCalloutMock）を列挙し、除外するケースごとに、どのスキルが処理するかを明記します（LWC JavaScriptには「authoring-lwcを使用」など）。境界を具体的に定義するほど、誤ったスキルの有効化を減らせます。

条件に一致するタスクが検出されると、ClaudeはSKILL.mdを読み込み、ワークフローに従います。プロンプトで/skill-nameを指定して、スキルを手動で有効化することもできます。どちらの場合も、ワークフロー、リファレンス、テンプレートを含むスキルのコンテキスト全体が自動的に組み込まれます。SKILL.mdの内容を会話に貼り付ける必要はありません。

スキルの形式自体（フロントマターを含むSKILL.md、リファレンス、アセット）は、AnthropicがApache 2.0の下で管理しているオープン仕様（英語）で、コミュニティも開発に参加できます。作成したSKILL.md、リファレンス、テンプレートは、別の環境でも利用できます。フックの仕組み（PostToolUseライフサイクルイベントを含むhooks.yaml）はClaude Code固有のものです。別のエージェントランタイムを使用する場合は、検証を別の方法で組み込むことになりますが、スキルの内容はそのまま移行できます。そのため、スキルは特定の実行環境に依存しない、いわばヘッドレスなものになります。Agentforce Vibes、Claude Code、Cursor、Visual Studio Code、Gemini CLI、OpenAI Codex、Windsurf、Roo Code、Gooseのほか、このオープン仕様をサポートする30以上のエージェントで使用できます。

エージェントスキルの構造

SKILL.md – 実行ルール

スキルを使用する際に従う重要なワークフローです。手順は変更できず、各フェーズには厳格な終了条件が設定されています。以下に、その構造を示す簡略化した例を紹介します。実際のSKILL.md（英語）では各フェーズをさらに詳しく記述しますが、終了条件を伴うフェーズを順番に並べるという構造は同じです。

フェーズが適用されない場合、ClaudeはそのフェーズをN/Aとして記録し、理由を記す必要があります。これは、「順序や完全性が重要な場合は、番号付きリストを使って、指示を連続したステップとして示す」というAnthropicのベストプラクティスに対応しています。

references/: ナレッジライブラリ

referencesは、一般的な学習では一貫した対処ができない、特定の失敗モードに対処するための参照ドキュメントです。つい情報を詰め込んでしまいがちなので、以下にAnthropicのベストプラクティスをいくつか示します。

ベストプラクティス 理由 Apexの例
ファイルサイズ ドキュメントが大きくなるほど、Claudeが重視するポイントに偏りが生じます。短く、目的が明確なファイルのほうが、安定して注意を向けられます。 関心ごとに分けます。コアパターン（Factory、Strategy、セレクター、サービス）は1つのファイルにまとめ、高度なパターン（Unit of Work、ドメインモデル、Facade）は別のファイルに分けます。
階層構造 目次と見出しがあると、Claudeがすべてを読まなくても関連するセクションを見つけられます。 SKILL.mdで「作成前にbest-practices.mdを読む」と指示しておくと、Claudeはファイル全体を確認することなく、必要な見出しに移動できます。
1セクションにつき1つのルール 各セクションのポイントを1つに絞ると、適用されるルールからあいまいさを排除できます。 「SOQL in Loops」という見出しのセクションなら、ループ内のSOQLだけを扱い、DMLや共有設定、null安全性は扱いません。
短いセクションを数多く 各セクションを自己完結させる（約20～40行）ことで、Claudeはドキュメント全体を読み込まずに1つのルールを適用できます。 アンチパターンであれば、1項目ごとに、見出し、「失敗する理由」の説明、BAD（悪い例）コードブロック、修正方法、GOOD（良い例）コードブロックを1つずつ用意します。
抽象的ではなく具体的に BAD/GOODのペアは、実質的にfew-shotの例として機能します。Anthropicは、例は「出力を方向付ける最も信頼できる方法の1つ」だと述べています。抽象的なルール（「ガバナ制限を避ける」）だと解釈に幅が出ますが、具体的なペアであれば振る舞いが安定します。 // BAD: 1回の反復につきSOQLを1回実行。レコード101件目で100件のクエリー制限を超過する。

// GOOD: SOQLの実行は全体で1回。
命令よりも理由と結果を示す 「Xは禁止」と伝えるより、「XはYという理由で失敗する」と示すほうが効果的です。Anthropicは、「理由を説明することで、Claudeが未知のケースにも応用できるようになる」と述べています。Claudeは理由がわかれば、例とは異なって見えるパターンにも同じルールを適用します。 「Salesforceでは、1トランザクションにつきDMLステートメントは150件までしか許可されません。200件のレコードに対するトリガーでループ内にDMLを書くと、151件目のレコードで150件の上限を超過し、バッチ全体がロールバックされます」
肯定形で表現する 「Xをしてはいけない」という表現では、何をすべきかをClaudeが推測しなければなりません。期待する動作を直接示すことで、Claudeが目指すべき目標を1つに絞れます。 すべてのクラスでsharingを明示的に宣言し、ユーザー向けロジックにはwith sharingを、両方のコンテキストから呼び出されるユーティリティクラスにはinherited sharingを使用します。
さまざまな例 Claudeが特定の形だけに引きずられないよう、エッジケースも扱います。Anthropicは、限定的なパターンマッチングを避けるために、3～5個の多様な例を示すことを推奨しています。 selector.clsでは、getByIds（一括取得）、getByName（サニタイズを伴うLIKE）、getWithContacts（親-子サブクエリー）、getContactsWithAccount（子-親クエリー）の4つのメソッドを示せます。同じパターンを4つの形で示せます。これにより、Claudeは「1つのクエリーメソッド」ではなく、「セレクター」という概念を学びます。

authoring-apexスキルでは、どのような参照ファイルを含めるとよいかを見てみましょう。

リファレンス ドキュメントの内容 この情報がない場合に起こる問題
best-practices.md コーディング規約（4スペースインデント、120文字以内の行）、命名規則、ApexDoc要件、APIバージョン管理、一般的なガイダンス プロジェクト規約とのずれ — Claudeは正しく動くコードを生成しますが、チームの既存のスタイルには合っていません。
design-patterns.md Factory、Strategy、セレクター、サービス、バッチ、Queueable、Unit of Work、ドメインモデルなど、各パターンを選ぶためのデシジョンツリー。各パターンに「使用する場面」の表を用意して、Claudeが最も一般的なパターンをデフォルトで選ばないようにします。 この情報がないと、セレクターやStrategyのほうが適している場面でも、Claudeはすべてをサービスクラスとして作成する傾向があります。
anti-patterns.md Apexでよくあるミスをまとめます。各項目には、BAD/GOODのコードペアと、スケール時に失敗する理由を説明します。 Claudeが人間の開発者よりも起こしやすい、一般的なミスを扱います（例：AccessLevelの指定なしにdatabase.query()を生成する。Assert.areEqualではなく従来のSystem.assertEqualsを使用するなど）。
security-guide.md USER_MODE（API 56以降）を使用したCRUD/FLSの適用、下位互換性のためのSecurity.stripInaccessible()、SOQLインジェクション対策、XSS対策パターン。 この情報がないと、Claudeは管理者プロファイルのユーザーでは動作しても、標準ユーザーではINSUFFICIENT_ACCESSが発生するコードを生成することがあります。
transaction-security-policy.md 特殊なケース向けのリファレンス。この例では、TxnSecurity.EventConditionの実装（拡張トランザクションセキュリティ）を扱います。これらのクラスはglobalであり、システムコンテキストで実行され、監視イベントを評価します。 これらは特殊なケースです。共有設定や可視性についての一般的なルールは、これらのクラスには当てはまりません。このリファレンスがないと、Claudeがwith sharingを適用してしまい、こうした種類のクラスが機能しなくなります。

このようなリファレンスの構成は、Anthropicが言う「指示の背景にある文脈と動機を提供する」という方法を活用したものです。単に「何をすべきか」だけを示すのではなく、「なぜそうするのか」も説明することで、Claudeが機械的にパターンマッチングするのではなく、未知の状況にも正しく応用できるようにします。

anti-patterns.mdの例を見てみましょう。この構造は、繰り返し問題が起きやすいプラクティスを対象に設計されています。すべてのセクションで同じBAD/GOOD形式を使用しています。Claudeが個別のミスを認識し、回避できるようにするためです。アンチパターンの詳細については、こちらのドキュメントをご覧ください。

トランザクションセキュリティポリシーのような特殊なケースでは、この構造に沿ってMarkdownを作成し、通常のルールがどれも当てはまらない特定のApex機能を1つ扱うことができます。このMarkdownでは、通常のルールが当てはまらないのはどのような場合か、代わりに何をすべきか、なぜそうするのかをClaudeに教える必要があります。BAD/GOODのペアはありません。この文脈では、「悪い」コード（例：global without sharing）が実際には正しいコードだからです。この例では、assetsフォルダーにある実例を参照していることに注意してください。

assets/：具体例によるfew-shot

Anthropicは、Claudeの出力形式、トーン、構造を方向づける最も信頼性の高い方法の1つに、few-shotとして機能する例の使用を挙げています。few-shotとは、テンプレートとして使える良い例をいくつか提示するといった意味です。各テンプレートには、必須要件として、ApexDocコメント、バルク対応のロジック、明示的なsharing宣言、CRUD/FLSの適用、テストを容易にするための依存性の注入が組み込まれています。Claudeはテンプレートをもとにコードを作成する際に、テンプレートの構造からこれらの要件を引き継ぎます。学習済みの知識から引き出す必要はありません。

Apexには幅広い可能性がありますが、ここでは有効なユースケースをいくつか掘り下げてみましょう。

アセット ドキュメントの内容 この情報がない場合に起こる問題
service.cls ビジネスロジックを取りまとめる役割。クエリーを委譲し、DML 操作をまとめ、エラーを処理します。 Claudeが関心の分離を考慮することなく、クエリーロジック、DML、オーケストレーションを1つの巨大なメソッドに入れてしまいます。
selector.cls SOQLアクセスを一元化します。sObjectごとに1つのセレクターを使用します。 Claudeが場当たり的にクエリーを書いて、serviceコードやtriggerコードに分散させてしまいます。その結果、コードレビューでセキュリティやパフォーマンスの観点からSOQLを監査しにくくなります。
batch.cls 大量データの非同期処理（1万件以上のレコード）。Database.BatchableとDatabase.Stateful。 Claudeが、エラーが発生しても適切に報告せず、そのまま処理してしまうバッチジョブを書いたり、失敗を報告する手段がないステートレスなバッチを使用したりしてしまいます。
queueable.cls オブジェクトを渡し、ジョブをチェーニングする非同期処理。 Claudeが深さを制限せずにジョブをチェーニングして無限再帰を招いたり、partial DMLを使わないためにエラーを見落としたりしてしまいます。
transaction-security-policy.cls 拡張トランザクションセキュリティのEventCondition実装。 Claudeは、通常のルール（with sharing、USER_MODE）が当てはまらないクラスに、通常のルールを適用してしまいます。トランザクションセキュリティポリシー（TSP）クラスは、プラットフォームの要件により、global without sharingである必要があります。

各テンプレートは、単に「特定のクラスをどう書くか」を示すものではありません。必須要件を構造に組み込んだ、事前に用意されたfew-shot例です。

hooks.yamlと検証スクリプト：セーフティネット

フックは、ライフサイクルの特定のタイミングでClaude Codeが自動実行するシェルコマンドです。フックはhooks.yamlで設定します。スクリプトは、そのコマンドが実行するものです。一般的には、ツールの入出力を検査して構造化されたフィードバックを返す、Pythonの検証スクリプトです。

フックによって、人が介入しなくてもフィードバックループが完結します。Claudeがコードなどを生成すると、フックがすぐにそれを評価し、その結果をClaudeが同じ会話ターンの中で受け取ります。Claudeが問題全体を把握している状態のまま、その文脈内で修正が行われます。

hooksファイルは、検証スクリプトが適切なタイミングで実行されるように設定します。たとえば、ユーザーがプロンプトを送信したタイミングで、事前チェックが実行されます。

また、ファイルの書き込みまたは編集が行われるたびに、PostToolUseフックが実行されます。

Claude Codeは、フックのコンテキストをJSON形式で標準入力（stdin）に渡します。ペイロードの構造はライフサイクルイベントによって異なります。PostToolUseにはツール名、入力パラメーター、出力が含まれ、UserPromptSubmitにはユーザーのプロンプトテキストが含まれます。

開発チーム向けの事前チェックを例に考えてみましょう。SKILL.mdのワークフローでは、検証フェーズで「Code Analyzerを実行する」と指示しています。しかし、Code Analyzerがインストールされていなかったり、バージョンが誤っていたりすると、どうなるでしょうか。フックがない場合、Claudeはワークフローの途中でコマンドを実行しようとしてエラーを受け取ります。開発者はエラーの原因がプラグインの不足にあることを突き止めなければなりません。フックを設定しておけば、Apex関連の作業が始まった時点でチェックが実行されます。

開発者は、ツールチェーンに不足があることを事前に発見できるので、ワークフローの途中で検証フェーズが失敗してから気づくという事態を避けられます。

指示とフックの違いはここにあります。SKILL.mdには、「検証フェーズでCode Analyzerを実行する」と書かれています。フックは、ワークフローが始まる前にCode Analyzerを実行できることを確認します。指示は望ましい動作を示すものであり、フックは機械的に実行されるものです。この両方が必要です。

エージェントスキルには、なぜ人間と機械の両方による検証が必要になるのか

スキルはすべてを解決する切り札ではありません。スキルによってClaudeの出力のばらつきはかなり小さくできますが、それでもClaudeは本質的に非決定論的なシステムです。ここで問題になるのは、次の2点です。

動作を完全に指定することはできない。SKILL.mdがどれほど正確であっても、実際の要件にはテンプレートやリファレンスではカバーしきれない、新しい組み合わせが含まれます。それでもClaudeは判断を下さなければなりません。新しいモデルほどプロンプトを文字どおりに解釈するため、記述が少し足りないだけでも結果にばらつきが出ます。SKILL.mdでパターンを指定せずに「エラー処理を追加する」とだけ書くと、毎回異なるアプローチが使われることになります。

出力は確率に左右される。プロンプトを構造化し、役割を割り当て、例を提示し、検証フックを使っても、結局は正答率を最適化しているにすぎません。正答率が60%から95%に向上すれば、もちろん大きな改善ではありますが、残りの5%に対応するために検証ツールが必要です。このアーキテクチャーには、予防的対策（構造化されたプロンプト、リファレンス、テンプレート）と検出的対策（自動検証ツール、採点ルーブリック、エラー時のブロック）の両方が含まれます。このスキルは、Claudeが間違えることもあるという前提に立っています。完全な出力が可能であるかのように見なすのではなく、修正プロセスをワークフローに組み込んでいるのです。

さっそく始めてみましょう

Anthropicは、プロンプトの作成についてこう述べています。「背景情報をほとんど知らない同僚にプロンプトを見せて、それに沿って作業してもらってみてください。その同僚が戸惑うようなら、Claudeも戸惑います」。適切に作成されたエージェントスキルには、人間にとってもモデルにとっても、あいまいな点がありません。

スキルをゼロから構築する必要はありません。Anthropicが提供するskill-creatorスキル（英語）を使うと、意図の整理、SKILL.mdの記述、テストケースの作成、evalの実行、そして出力が求める基準に達するまで反復するという一連のプロセスを進められます。skill-creatorスキルをインストールし、作成したいスキルをClaudeに伝えてみてください。skill-creatorスキルが土台を作成し、エッジケースについて聞き取り、実際に動作し、調整可能なドラフトを生成してくれます。

Salesforceに特化したサンプルを使って始めてみたい場合は、Agentforce Vibesスキルライブラリ（英語）で、Apex、LWC、Flowなどの本番品質のスキルを利用できます。こうしたスキルをインストールして使い、どのように構成されているかを確認してみてください。この記事で説明したものと同様のパターンに従っています。Agentforce Vibesスキルライブラリでは、ルールと理由をSKILL.mdにインラインで記述し、Markdown形式の参照ドキュメントの代わりに、完全なApexソースファイルをテンプレートとして使っています。これにより、少ないファイル数でスキルを自己完結させることができますが、モジュール性は損なわれます。1つのルールを更新するには、メインのワークフローファイルを編集する必要があります。

スキルは、ニーズに合わせて成長していきます。まずはskill-creatorまたは既存のスキルから始めてみましょう。プロジェクトに合わない部分をカスタマイズし、既存のスキルでは埋められないギャップが出てきたら、新しいスキルを構築してみるとよいでしょう。

関連情報

執筆者について

Dave Norrisは、Salesforceのデベロッパーアドボケイトです。技術的なテーマを、多様な読者に広くわかりやすく説明することに情熱を注いでいます。Salesforceで10年以上勤務し、現在、SalesforceとMuleSoftの認定資格を40以上保有。2013年に、Salesforce認定テクニカルアーキテクトの資格を取得しています。