Salesforce 개발에서 AI 코딩 지원을 사용할 때, Apex나 SOQL보다 은근히 어려운 것이 Metadata API의 XML이라고 느낍니다.

예를 들어, CustomObject, Flow, PermissionSet, Profile 등은 겉보기에는 XML이지만, 요소명·필수 항목·배치 장소·API 유형의 문맥을 놓치면 배포(Deploy) 시에 실패합니다.

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-get

skill 읽는 법 - 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 개발 도구 측의 컨텍스트(Context)로 사용하게 하는 발상입니다.

다만, 이는 다음과 같은 위치 설정으로 보는 것이 안전합니다.

먼저 혼동하기 쉬운 점을 구분하겠습니다.

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 개발에서 자주 보이는 요소도 포함됩니다.

한편, 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에는 다음과 같은 주의사항도 있습니다.

Salesforce skills 라이브러리는 빠르게 진화하고 있습니다 ... 릴리스 사이에 Skill의 이름이 변경되거나, 구조가 재편되거나, 삭제될 수 있습니다 ... 이 리포지토리(repository)가 항상 신뢰할 수 있는 단일 원천(source of truth)입니다.

즉, Skills는 편리한 보조 자산이지만, GA API와 같은 안정성을 전제로 하기보다는 변화하는 오픈 소스 리포지토리로서 추적하는 것이 더 안전합니다.

Salesforce Developers Blog에서는 Metadata API Context Skill에 대해, AI assistant에게 Metadata API의 문맥(context)을 제공하여, 무효한 XML이나 배포 에러(deploy error)로 이어지는 환각(hallucination)을 줄이는 목적으로 소개하고 있습니다.

GitHub상의 platform-metadata-api-context-get skill에는 다음과 같은 설명이 있습니다.

• Salesforce Metadata API types에 대한 포괄적인 문서(documentation)를 제공한다 (SKILL.md에서는 604개의 Metadata API types를 대상으로 한다고 명시되어 있음)
• Salesforce DX 프로젝트 내의 metadata XML을 생성, 이해, 수정하기 위해 사용한다
• 각 metadata type에 대해 field definitions, 필수/선택 사항 구분, 허용되는 enum 값, XML structures, WSDL segments, examples, 파일명 규칙, SFDX 상의 배치 디렉토리(directory) 등을 참조할 수 있다
• metadata generation skill과 동일한 턴(turn)에서 읽어들여야 하는 필수(REQUIRED) 컴패니언(companion) skill로 설명되어 있다

여기서 중요한 것은 AI에게 "전부 읽게 하는" 것이 아니라, 필요한 섹션(section)만 읽게 하는 것입니다.

platform-metadata-api-context-get의 SKILL.md에서는 assets/metadata_api/*.json을 통째로 읽게 하지 않고, 필요한 섹션만 추출할 것을 강력히 권장하고 있습니다.

대표적으로는 다음과 같은 구분 사용법이 있습니다.

마찬가지로 SKILL.md에서는 "필요한 섹션만 읽어들임으로써 토큰(token) 소비를 60~80% 절감할 수 있다"라고 수치를 들어 설명하고 있습니다. 아울러, 큰 metadata JSON에 대해 파일 전체를 읽는 도구는 사용하지 말고, jq나 Python 등을 사용하여 섹션을 추출할 것을 권장합니다.

또한, 해당 skill의 README에는 한 단계 앞선 기준으로 Metadata Type 단위의 필터링이 적혀 있습니다 (604개 파일을 모두 읽으면 약 75,000 토큰, 필요한 15개 type로 좁히면 5005,000 토큰). "먼저 Type을 좁히고, 그다음 섹션을 좁힌다"는 2단계 전략으로 파악하면 정리하기 쉽습니다.

AI에게 Salesforce 메타데이터를 다루게 할 때는 다음과 같이 질문하는 것이 안전해 보입니다.

Flow metadata의 fields 섹션만 확인해 주세요.
record-triggered flow를 만들기 전에, 필요한 항목과 주의사항을 정리해 주세요.

반대로, 다음과 같은 질문 방식은 피하는 것이 좋습니다.

Salesforce Metadata API의 문서를 전부 읽고, 적절하게 Flow를 만들어 주세요.

후자는 불필요한 정보를 대량으로 읽게 할 뿐만 아니라, AI가 어떤 근거를 사용하고 있는지 추적하기 어렵게 만듭니다.

AI 코딩 지원에서 Salesforce metadata XML을 다룰 때는 다음과 같은 실수가 발생하기 쉽습니다.

• 존재하지 않는 요소(element) 이름을 생성함
• API 유형을 잘못 파악함
• 필수 항목을 누락함
• XML의 계층(hierarchy)이나 네임스페이스(namespace)를 틀림
• SFDX의 배치 위치를 틀림
• Flow나 PermissionSet의 복잡한 자식 요소(child element)를 대충 다룸

Metadata API Context Skill은 이러한 상황에서 AI에게 "공식 문서에 가까운 구조화된 문맥 (Context)"을 전달하기 위한 보조 도구입니다.

단, 이것은 AI를 완벽하게 만드는 마법은 아닙니다.

실무에서는 최소한 다음 사항들을 확인해야 합니다.

• 생성된 XML이 대상 API 버전의 Metadata API와 일치하는지
• 대상 조직에서 유효한 기능·라이선스·설정에 의존하고 있지 않은지
• sf project deploy validate 등으로 검증할 수 있는지
• 차분 리뷰 (Diff Review)를 통해 불필요한 설정 변경이 포함되지 않았는지
• 운영 조직(Production)이나 고객 고유 정보가 프롬프트·로그·기사에 포함되지 않았는지

Metadata API Context Skill을 사용하기 전에, 다음과 같이 질문을 분해해 두면 다루기 쉬울 것입니다.

예:

CustomObject

CustomField

Flow

PermissionSet

Profile

Layout

RecordType

동일한 이름이 Metadata API, Tooling API, Enterprise API 등에서 서로 다른 의미를 가질 수 있습니다. platform-metadata-api-context-get의 설명에서도 ApexClass 등은 API 문맥을 혼동하지 않도록 주의하라는 내용이 정리되어 있습니다.

예:

• 신규 생성하고 싶다
• 기존 XML을 읽고 싶다
• 차분 리뷰 (Diff Review)를 하고 싶다
• 필수 항목을 확인하고 싶다
• 샘플 XML을 보고 싶다
• 배포 에러 (Deploy Error)의 원인을 조사하고 싶다

예:

CustomObject의 fields와 description만 확인해서, 최소한으로 필요한 항목을 표로 만들어줘.

PermissionSet의 XML 예시를 확인하고 싶으니, declarative_metadata_sample_definition에 해당하는 정보를 바탕으로 구조만 설명해줘.

AI가 생성한 metadata XML은 곧바로 운영 브랜치(Production Branch)에 넣지 말고, 다음 순서로 다루는 것이 안전합니다.

• AI에게 초안을 작성하게 한다
• 근거로 삼은 Metadata Type과 섹션을 명시하게 한다
• 차분 (Diff)을 확인한다
• 로컬 또는 검증 조직에서 validate 한다
• 사람이 리뷰한다
• 필요하다면 수정한 후 PR (Pull Request)을 생성한다

이 주제를 사내 공유나 Qiita 기사로 작성할 경우, 공개 시 주의사항도 있습니다.

다음 정보는 공개 기사에 포함하지 않는 것이 안전합니다.

• 조직 ID (Org ID)
• 사용자 이름, 이메일 주소
• 인스턴스 URL, My Domain
• 고객명이나 업무 고유의 오브젝트 명칭
• 운영 환경의 권한 세트 (Permission Set)나 프로필 (Profile)의 실제 XML
• 접속 정보, 액세스 토큰 (Access Token), 인증 파일

샘플에서는 MyCustomObject__c와 같은 일반적인 플레이스홀더 (Placeholder)를 사용하는 것이 무난합니다.

공식 블로그에는 Metadata API Context Skill을 통해 AI 에이전트가 더욱 정확한 문맥을 얻을 수 있다는 취지의 설명이 있습니다.

단, 실제 배포 결과는 조직 설정, API 버전, 의존 기능, 권한, 패키지 구성 등에 따라서도 좌우됩니다.

따라서 공개 기사에서는 다음과 같은 표현에 머무는 것이 안전합니다.

• Metadata API의 문맥을 AI에게 전달하기 쉬워진다
• XML 생성·수정 시의 확인 자료를 늘릴 수 있다
• 할루시네이션 (Hallucination)이나 배포 에러를 줄이는 데 도움이 될 가능성이 있다
• 최종적인 validate와 리뷰는 반드시 필요하다

Metadata API Developer Guide에는 Metadata API Context MCP Tools (Beta)의 퀵스타트라는 별도의 항목도 존재합니다. 이것은 Salesforce Hosted MCP Servers (호스트형 MCP 서버) 중 하나로, 이용을 위해서는 Hosted MCP Server 측의 셋업이 필요합니다. Summer '26에서는 이 Metadata API Context MCP Server (Beta)가 하나의 도구에서 5개의 세분화된 도구 구성으로 변경되었다고 안내되어 있습니다.

한편, 본 기사에서 다루는 핵심은 Salesforce Developers Blog와 forcedotcom/sf-skills에 있는 Metadata API Context Skill입니다.

이름이 비슷하기 때문에, 기사나 사내 공유 시에는 다음과 같이 구분하여 작성하면 오해를 줄일 수 있습니다.

이번에는 Skill 측면의 정리에 집중하며, MCP Tool의 구체적인 사용법은 다루지 않습니다.

Metadata API Context Skill은 Salesforce 개발 시 AI를 사용할 때, Metadata API의 근거를 AI에게 전달하기 쉽게 만들기 위한 보조 도구로 이해하면 쉽습니다.

포인트는 다음 세 가지입니다.

• AI가 Salesforce metadata XML을 상상해서 쓰게 하는 것이 아니라, Metadata API의 타입(Type), 항목(Field), XML 구조를 근거로 전달함
• fields나 description 등 필요한 섹션만 읽게 함으로써, 토큰(Token) 양과 오해를 줄임
• AI가 생성한 결과는 차분 리뷰(Diff Review), 검증(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