はじめに
Salesforce開発でAIコーディング支援を使うとき、ApexやSOQLよりも地味に難しいのが Metadata API のXML だと感じます。
たとえば、CustomObject、Flow、PermissionSet、Profileなどは、見た目はXMLでも、要素名・必須項目・配置場所・API種別の文脈を外すとデプロイ時に失敗します。
Salesforce Developers Blogでは、こうした課題に対して Metadata API Context Skill が紹介されています。
本記事では、実際の本番組織での検証手順ではなく、公開情報をもとに次の観点を整理します。
- Metadata API Context Skillは何を補助するものか
- Salesforce Metadata APIと、AI向けのSkillsをどう分けて理解するか
- AIに任せる前に、人間側で確認しておきたいこと
- 公開記事やチーム利用で避けたい注意点
※本記事は個人の整理メモです。内容は 2026-08-02時点で確認した公式情報・公式GitHub をもとにしています。
この記事で扱うもの / 扱わないもの
扱うもの
- Salesforce Developers Blogで紹介された Metadata API Context Skill の位置づけ
-
forcedotcom/sf-skillsリポジトリの概要 -
platform-metadata-api-context-getskill の読み方 - Metadata API XMLをAIに扱わせる前のチェック観点
扱わないもの
- Agentforce Vibesの契約・利用条件の詳細
- 特定組織に対する実デプロイ手順
- 本番組織のメタデータを使った検証
- 「このSkillを使えば必ずデプロイ成功する」という断定
公式ブログでは、Metadata API Context Skillを使うことでAIエージェントがMetadata APIの文脈を参照しやすくなると説明されています。一方で、最終的なデプロイ可否や組織固有の制約は、通常どおり開発者が確認する必要があります。
まず結論
Metadata API Context Skillは、ざっくり言うと AIにSalesforce Metadata APIの根拠資料を渡しやすくするためのSkill と捉えると理解しやすいです。
AIに「SalesforceっぽいXML」を想像で書かせるのではなく、Metadata APIの型・項目・XML構造・サンプルに近い情報を、AI開発ツール側のコンテキストとして使わせる発想です。
ただし、これは次のような位置づけで見るのが安全です。
| 観点 | 整理 |
|---|---|
| 主な目的 | Metadata API XMLの生成・理解・修正を補助する |
| 根拠 | Salesforce Developers Blog、Salesforce Skills GitHub、Metadata API Developer Guide |
| 向いている場面 | CustomObject、Flow、PermissionSetなどのメタデータ定義をAIに扱わせる前の文脈付与 |
| 注意点 | AIの誤りを完全に防ぐものではない。最終確認・デプロイ検証は必要 |
| 公開記事で避けること | 組織固有のメタデータ、インスタンスURL、My Domain、組織ID、顧客固有設定の掲載 |
Salesforce Metadata APIとSkillsを分けて考える
最初に混同しやすい点を分けます。
Salesforce Metadata API
Metadata APIは、Salesforce組織のカスタマイズ情報を取得・デプロイ・作成・更新・削除するためのAPIです。
Metadata API Developer Guideでは、Summer '26 / API version 67.0 のドキュメントとして、Metadata APIの導入、利用方法、Metadata Typesの一覧などが公開されています。
たとえば、Metadata Typesの一覧には多数のメタデータ型が並んでおり、CustomObject、ApexClass、Flow、PermissionSet、Profileなど、Salesforce開発でよく見る要素も含まれます。
Salesforce Skills / sf-skills
一方、forcedotcom/sf-skills は、Salesforceの開発作業をAIツールから扱いやすくするためのSkills集です。
GitHub READMEでは、Salesforce Skills LibraryはAgentforce agents、Lightning apps、Flow、Apex、SOQL、LWC、UI bundles、objects and fields、permission setsなどの領域を含むSkills集として説明されています。
導入方法もREADMEに書かれており、Agentforce Vibesでは自動インストール・自動更新、それ以外のAIツールでは npx skills add forcedotcom/sf-skills を実行する形になっています。
また、READMEには次の注意もあります。
The Salesforce skills library is evolving rapidly ... Skills may be renamed, restructured, or removed between releases ... This repository is always the source of truth.
つまり、Skillsは便利な補助資産ですが、GA APIのような安定性を前提にするより、変化するオープンソースリポジトリとして追う ほうが安全です。
Metadata API Context Skillが補助すること
Salesforce Developers Blogでは、Metadata API Context Skillについて、AI assistantにMetadata APIの文脈を与え、無効なXMLやデプロイエラーにつながるハルシネーションを減らす目的で紹介されています。
GitHub上の platform-metadata-api-context-get skill では、次のような説明があります。
- Salesforce Metadata API typesの包括的なドキュメントを提供する（SKILL.mdでは604個のMetadata API typesを対象とすると書かれています）
- Salesforce DXプロジェクト内のmetadata XMLを作成・理解・修正するために使う
- 各metadata typeについて、field definitions、必須/任意の区別、許容されるenum値、XML structures、WSDL segments、examples、ファイル名規約、SFDX上の配置ディレクトリなどを参照できる
- metadata generation skillと 同じターンで読み込む必須（REQUIRED）のcompanion skill として説明されている
ここで重要なのは、AIに「全部読ませる」のではなく、必要なセクションだけを読ませる という考え方です。
section-specific consumption という考え方
platform-metadata-api-context-get の SKILL.md では、assets/metadata_api/*.json を丸ごと読ませず、必要なセクションだけを抽出することが強く推奨されています。
代表的には、次のような使い分けです。
| 目的 | 読ませるセクションの例 |
|---|---|
| 項目定義を確認したい | fields |
| そのMetadata Typeの役割を理解したい | description |
| XML例を見たい | declarative_metadata_sample_definition |
| WSDL上の定義を確認したい |
wsdl_segment（冗長なので必要なとき以外は読ませない） |
| ファイル名の規約を確認したい | file_information |
| SFDXプロジェクト内の配置場所を確認したい | directory_location |
同じくSKILL.mdでは「必要なセクションだけを読み込むことでトークン消費を60〜80%削減できる」と数値付きで説明されています。あわせて、大きなmetadata JSONに対してファイル全体を読むツールは使わず、jq やPythonなどでセクションを抽出することが推奨されています。
なお、同skillのREADMEにはもう一段手前の目安として、Metadata Type単位の絞り込みが書かれています（604ファイルをすべて読むと約75,000トークン、必要な1〜5 typeに絞れば500〜5,000トークン）。「まずTypeを絞り、次にセクションを絞る」の二段構えで捉えると整理しやすいです。
AIにSalesforceメタデータを扱わせるときは、次のように聞くと安全そうです。
Flow metadataのfieldsセクションだけを確認してください。
record-triggered flowを作る前に、必要な項目と注意点を整理してください。
逆に、次のような聞き方は避けたほうがよさそうです。
Salesforce Metadata APIのドキュメントを全部読んで、いい感じにFlowを作ってください。
後者は、不要な情報を大量に読ませるだけでなく、AIがどの根拠を使っているのか追いづらくなります。
「Metadata APIの文脈」を渡すと何がうれしいのか
AIコーディング支援でSalesforce metadata XMLを扱うと、次のような間違いが起きやすいです。
- 存在しない要素名を作る
- API種別を取り違える
- 必須項目を落とす
- XMLの階層やnamespaceを誤る
- SFDXの配置場所を誤る
- FlowやPermissionSetの複雑な子要素を雑に扱う
Metadata API Context Skillは、こうした場面で「公式ドキュメントに近い構造化された文脈」をAIに渡すための補助になります。
ただし、これは AIが正しくなる魔法 ではありません。
実務では、少なくとも次の確認は残ります。
- 生成されたXMLが対象APIバージョンのMetadata APIに合っているか
- 対象組織で有効な機能・ライセンス・設定に依存していないか
-
sf project deploy validateなどで検証できるか - 差分レビューで不要な設定変更が入っていないか
- 本番組織や顧客固有情報がプロンプト・ログ・記事に出ていないか
AIに依頼する前の小さなチェックリスト
Metadata API Context Skillを使う前に、次のように問いを分解しておくと扱いやすそうです。
1. 何のMetadata Typeかを明確にする
例:
CustomObjectCustomFieldFlowPermissionSetProfileLayoutRecordType
同じ名前がMetadata API、Tooling API、Enterprise APIなどで別の意味を持つ場合があります。platform-metadata-api-context-get の説明でも、ApexClassなどはAPI文脈の取り違えに注意するよう整理されています。
2. 何をしたいのかを分ける
例:
- 新規作成したい
- 既存XMLを読みたい
- 差分レビューしたい
- 必須項目を確認したい
- サンプルXMLを見たい
- デプロイエラーの原因を調べたい
3. 読ませるセクションを絞る
例:
CustomObjectのfieldsとdescriptionだけを確認して、最低限必要な項目を表にしてください。
PermissionSetのXML例を確認したいので、declarative_metadata_sample_definitionに相当する情報をもとに、構造だけ説明してください。
4. 最終成果物を直接コミットさせない
AIが生成したmetadata XMLは、いきなり本番ブランチへ入れるのではなく、次の順で扱うほうが安全です。
- AIに下書きを作らせる
- 根拠にしたMetadata Typeとセクションを明記させる
- 差分を見る
- ローカルまたは検証組織でvalidateする
- 人間がレビューする
- 必要なら修正してからPR化する
記事やチーム共有での注意点
このテーマを社内共有やQiita記事にする場合、公開上の注意もあります。
本番組織の情報を出さない
次の情報は公開記事に含めないほうが安全です。
- 組織ID
- ユーザー名、メールアドレス
- インスタンスURL、My Domain
- 顧客名や業務固有のオブジェクト名
- 本番の権限セットやProfileの実XML
- 接続情報、アクセストークン、認証ファイル
サンプルでは、MyCustomObject__c のような一般的なプレースホルダーを使うのが無難です。
「必ず成功する」と書かない
公式ブログには、Metadata API Context SkillによりAIエージェントがより正確な文脈を得られる、という趣旨の説明があります。
ただし、実際のデプロイ結果は組織設定、APIバージョン、依存機能、権限、パッケージ構成などにも左右されます。
そのため、公開記事では次のような表現に留めるのが安全です。
- Metadata APIの文脈をAIに渡しやすくなる
- XML生成・修正時の確認材料を増やせる
- ハルシネーションやデプロイエラーを減らす助けになる可能性がある
- 最終的なvalidateとレビューは必要
Metadata API Context MCP Toolとの違いに注意
Metadata API Developer Guideには、Metadata API Context MCP Tools (Beta) のクイックスタートという別項目も存在します。こちらはSalesforce Hosted MCP Servers（ホスト型MCPサーバー）の1つで、利用にはHosted MCP Server側のセットアップが必要です。Summer '26では、この Metadata API Context MCP Server (Beta) が1つのツールから5つの粒度の細かいツール構成に変わった、と案内されています。
一方、本記事で扱っている中心は、Salesforce Developers Blogと forcedotcom/sf-skills にある Metadata API Context Skill です。
名前が似ているため、記事や社内共有では次のように分けて書くと誤解を減らせます。
| 名前 | 本記事での扱い |
|---|---|
| Metadata API Context Skill |
sf-skills リポジトリ上のSkillとして整理 |
| Metadata API Context MCP Tools (Beta) | Salesforce Hosted MCP Serversの1つ。Metadata API Developer Guideにクイックスタートがある別文脈で、Hosted MCP Serverのセットアップが前提 |
今回はSkill側の整理に絞り、MCP Toolの具体的な使い方は扱いません。
まとめ
Metadata API Context Skillは、Salesforce開発でAIを使うときに、Metadata APIの根拠をAIへ渡しやすくするための補助として見ると理解しやすいです。
ポイントは次の3つです。
- AIにSalesforce metadata XMLを想像で書かせるのではなく、Metadata APIの型・項目・XML構造を根拠として渡す
-
fieldsやdescriptionなど、必要なセクションだけを読ませることで、トークン量と誤解を減らす - AIが生成した結果は、差分レビュー、validate、組織固有条件の確認を通してから使う
AIコーディング支援が便利になるほど、「何をAIに渡すか」「何を人間が確認するか」の線引きが大事になります。
Metadata API Context Skillは、その線引きを考えるための良い題材だと感じました。
参考（公式情報）
- Build Smarter with Metadata API Context Skills | Salesforce Developers Blog
https://developer.salesforce.com/blogs/2026/07/build-smarter-with-metadata-api-context-skills - Salesforce Skills Library | GitHub
https://github.com/forcedotcom/sf-skills/blob/main/README.md - Metadata API Context Get Skill | GitHub
https://github.com/forcedotcom/sf-skills/tree/main/skills/platform-metadata-api-context-get - Metadata API Developer Guide - Introduction to Metadata API
https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_intro.htm - Metadata API Developer Guide - Metadata Types
https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_types_list.htm