Claude CodeでSalesforceエージェントスキルを構築する

※本記事は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エコシステムのプログラミング言語をすでに習得しています。しかし、プログラミング言語を理解しているからといって、必ずしもベストプラクティスに沿った高品質なコードを安定して生成できるわけではありません。スキルは、これを可能にします。

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

1skills/authoring-apex/
2├── SKILL.md              # 実行ルール
3├── references/           # デシジョンツリー、パターン、ガードレール
4├── assets/               # サンプルコード
5└── hooks/scripts/        # Python検証ツール

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

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

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

1---
2name: authoring-apex
3description: >
4  TRIGGER when: ユーザーがSalesforce Apexコードを作成、編集、またはレビューする場合 — 
5  対象は、サービスクラス、セレクタークラス、
6  トリガーハンドラー、テストクラス、バッチジョブ、Queueableクラス、
7  呼び出し可能メソッド、Apex RESTエンドポイントを含む.clsファイルまたは.triggerファイル。
8  DO NOT TRIGGER when: ユーザーがLWC JavaScript、Flow XML、
9  単独のSOQLクエリーを扱う場合、または既存のテストを実行する場合。
10---

この例は簡略化されたもので、実際には、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（英語）では各フェーズをさらに詳しく記述しますが、終了条件を伴うフェーズを順番に並べるという構造は同じです。

1このワークフローを順番どおりに実行してください。ステップの省略、結合、順序変更は禁止します。
2行き詰まった場合は停止し、不足しているコンテキストを確認してください。該当なしの場合は、
3レポートで「N/A」と記載し、その理由を1行で示してください。
4
5## 必須の入力
6
7作成に入る前に、以下を収集または推測する：
8
9- クラス種別（サービス、セレクター、バッチ、Queueable、Invocable、トリガーハンドラー）
10- 対象となるオブジェクトとビジネス目標
11- デフォルトの共有設定（理由がある場合を除き`with sharing`）
12- すでに使用中のトリガーフレームワーク（または明示的に選択されたもの）
13
14フェーズの構成:
15
16### フェーズ1 — 作成
171. **プロジェクト規約を確認する** — 既存のパターン、トリガー
18     フレームワーク、命名スタイルを調べる
192. **要件を満たす最小のパターンを選択する**:
20
21  | 要件                  | パターン                              |
22  | ------------------ | -------------------------------------- |
23  | ビジネスロジック       | サービスクラス                          |
24  | データアクセス         | セレクタークラス                        |
25  | トリガーロジック        | トリガーハンドラー（フレームワークが必要）　|
26  | Flowとの連携        | @InvocableMethod                       |
27  | 一括処理             | Batch Apex                            |
28  | 非同期処理          | Queueable                               |
29
303. 作成に入る前に、`assets/`内の**対応するテンプレートを確認する**
314. **ガードレールに従って作成する** — 以下の「ルール」セクションにあるすべてのルールを適用する
325. **テストクラスを生成する** — テストスキルに委任する
33
34### フェーズ2 — 検証
35
366. **Code Analyzerを実行する** — すべてのブロッキング違反を修正し、クリーンになるまで再実行する
377. **テストを実行する** — 合否とコードカバー率を記録する
38
39### フェーズ3 — レポート
40
418. **報告する** — ファイル、設計上の判断、アナライザー出力、テスト結果、デプロイメモ

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

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

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

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

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

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

1# Apexのアンチパターン
2
3## 目次
4
5- [ループ内SOQL](#soql-in-loops)
6- 
7
8---
9
10## ループ内SOQL
11**アンチパターン:** `for`ループまたは`while`ループ内でSOQLクエリーを実行すること。
12
13**失敗する理由:** Salesforceには、1つの同期トランザクションで実行できるSOQLクエリーは
14100件までという厳格な制限があります。トリガーは最大200件のレコードをまとめて処理するため、
15ループ内でSOQLを1回実行すると、100件を処理しただけで上限に達します。
16
17```apex
18// BAD: 1回の反復につきSOQLを1回実行。レコード101件目で100クエリー制限を超過する。
19for (Account acc : accounts) {
20    List contacts = [SELECT Id FROM Contact WHERE AccountId = :acc.Id];
21}
22
23修正方法: クエリーは一括で1回だけ実行し、取得した結果を反復処理します。
24
25// GOOD: SOQLの実行は全体で1回。
26Map contactsByAccount = new Map();
27for (Contact c : [SELECT Id, AccountId FROM Contact WHERE AccountId IN :accountIds]) {
28    ...
29}
30// Salesforce Well-Architectedのアンチパターンに合わせて、他の項目を追加します。

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

1# トランザクションセキュリティポリシー（Apex条件）
2
3## 目次
4
5- [概要](#overview)
6- [クラスの形式](#class-shape)
7- [共有設定](#sharing)
8- [ガードレール](#guardrails)
9- [例](#example)
10
11---
12
13## 概要
14
15条件ビルダーでは不十分な場合、拡張トランザクションセキュリティポリシーはApexを呼び出します。
16`TxnSecurity.EventCondition`を実装し、単一の
17`evaluate(SObject event)`メソッドを定義します。
18
19## クラスの形式
20
21- クラスは**`global`**として宣言する（［設定］で選択できるようにするために必須）
22- `TxnSecurity.EventCondition`を実装する
23- シグネチャ: `global Boolean evaluate(SObject event)`
24
25## 共有設定
26
27これらのクラスは、ユーザー向けのコントローラーでは**ありません**。`without sharing`を使用します。
28`with sharing`をデフォルトとする通常のルールはここでは適用されません。
29適用すると、エラーが明示されないまま、ポリシーが正しく機能しなくなります。
30
31## ガードレール
32
33- 一括SOQLクエリーは最大1つとする（ループ内でSOQLは実行しない。ガバナ制限は引き続き適用される）
34- トランザクションをブロックする場合は`true`、許可する場合は`false`を返す
35
36## 例
37
38`assets/transaction-security-policy.cls`を参照してください。

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

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

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

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

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

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

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

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

1{
2  "hooks": {
3    "UserPromptSubmit": [
4      {
5        "hooks": [
6          {
7            "type": "command",
8            "command": "python3 ${CLAUDE_SKILL_DIR}/hooks/scripts/preflight-apex-check.py",
9            "timeout": 10000
10          }
11        ]
12      }
13    ]
14  }
15}

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

1---
2name: authoring-apex
3description: ...
4hooks:
5  PostToolUse:
6    - matcher: "Write|Edit"
7      hooks:
8        - type: command
9          command: "python3 ${CLAUDE_SKILL_DIR}/hooks/scripts/preflight-apex-check.py"
10          timeout: 90000
11---

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

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

1import json, subprocess, sys
2
3MINIMUM_VERSION = "5.5.0"
4
5def parse_version(v):
6    """バージョン文字列を比較可能なタプルに変換します。"""
7    return tuple(int(x) for x in v.split(".")[:3])
8
9def main():
10    hook_input = json.load(sys.stdin)
11    prompt = hook_input.get("prompt", "").lower()
12
13    # Apex関連の作業である可能性が高い場合のみチェックする
14    apex_keywords = ["apex", ".cls", "class", "trigger", "service", "selector", "batch"]
15    if not any(kw in prompt for kw in apex_keywords):
16        sys.exit(0)
17
18    try:
19        result = subprocess.run(
20            ["sf", "plugins", "--json"],
21            capture_output=True, text=True, timeout=15
22        )
23        if result.returncode == 0:
24            plugins = json.loads(result.stdout)
25            for plugin in plugins:
26                if plugin.get("name") == "@salesforce/plugin-code-analyzer":
27                    version = plugin.get("version", "0.0.0")
28                    if parse_version(version) >= parse_version(MINIMUM_VERSION):
29                        sys.exit(0)
30                    else:
31                        print("=== 事前チェック ===")
32                        print(f"  [警告] Code Analyzer {version} は、最低対応バージョンである {MINIMUM_VERSION} を満たしていません。")
33                        print(f"  インストール: sf plugins install @salesforce/plugin-code-analyzer@latest")
34                        sys.exit(0)
35    except (FileNotFoundError, subprocess.TimeoutExpired, json.JSONDecodeError):
36        pass
37
38    print("=== 事前チェック ===")
39    print("  [警告] Salesforce Code Analyzerがインストールされていません。")
40    print("  authoring-apex skillでは、検証のためにSalesforce Code Analyzerが必要です。")
41    print("  インストール: sf plugins install @salesforce/plugin-code-analyzer")
42    sys.exit(0)
43
44if __name__ == "__main__":
45    main()

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

指示とフックの違いはここにあります。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または既存のスキルから始めてみましょう。プロジェクトに合わない部分をカスタマイズし、既存のスキルでは埋められないギャップが出てきたら、新しいスキルを構築してみるとよいでしょう。

関連情報

• GitHub：Salesforceのエージェントスキル集（英語）
• Trailhead：プロンプトの基本事項
• Trailhead：プロンプトエンジニアリングのテクニック
• GitHub：Anthropic Skill Creator（英語）
• ドキュメント：Claude Code

執筆者について

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