REQUIRED companion for Salesforce metadata generation — load this schema/API-context skill in the SAME turn as ANY metadata generation skill; if you load a generator, you ALSO load this. Use it whenever you create, generate, add, edit, or author metadata or a *-meta.xml file: custom object, custom f

Salesforce Metadata API Skill This skill provides comprehensive documentation for all 604 Salesforce Metadata API types . Use this skill to create, understand, and modify Salesforce metadata XML files in your Salesforce DX projects. Overview The Salesforce Metadata API allows you to retrieve, deploy, create, update, or delete customizations for your org. This skill gives you access to detailed documentation for each metadata type, including: Field definitions and data types Required vs. optional fields WSDL schema definitions Sample XML structures File naming conventions Directory locations in Salesforce DX projects How to Use This Skill CRITICAL: Section Specific Consumption ALWAYS consume only the specific sections you need from JSON files, NOT entire files. CRITICAL: For assets/metadata api/ .json files, always use jq or programmatic JSON parsing to extract only the specific sections you need. Do not load these files whole via Read , cat , read file , or any other tool that injects the complete file — they contain verbose WSDL segments and other sections that waste 60 80% of tokens. (Loading small files like this SKILL.md or the index table with Read is fine; the rule applies specifically to the large metadata type JSON files.) Each JSON file contains multiple sections (fields, description, wsdl segment, etc.). Most use cases only require 1 2 sections: For field definitions : Load only the fields section For understanding purpose : Load only the description section For XML examples : Load only the declarative metadata sample definition section Skip by default : wsdl segment (verbose schema), file information , directory location This reduces token consumption by 60 80% per file . Quick Start To get information about a specific metadata type: 1. Section specific (BEST): "Show me only the 'fields' section from CustomObject.json" 2. Multiple sections : "Show me 'fields' and 'description' from Flow.json" 3. Avoid loading entire files : Don't ask for "the CustomObject metadata type" specify sections Example Queries (Section Specific) Recommended: "Show me only the 'fields' section from CustomObject.json" "What fields are in the 'fields' section of Profile.json?" "Load the 'description' and 'fields' sections from Flow.json" "Give me just the 'declarative metadata sample definition' from ApexClass.json" Avoid: "Show me the CustomObject metadata type" (too broad entire file) "Load CustomObject.json" (includes unnecessary WSDL and other sections) JSON File Structure Each metadata type is stored as a JSON file in assets/metadata api/ with the following structure: Note: string values ( title , description , file information , directory location , wsdl segment ) are stored as plain text — no markdown headers ( / ) or code fences. file information holds just the file suffix (e.g. .object , .ai ) and directory location just the SFDX folder name (e.g. objects , aiApplications ). Available Sections The sections array indicates which top level keys are present in each file. Common sections include: title : The metadata type name and header description : What the metadata type represents fields : The type's own fields, with types and descriptions sub types : (composite types only) a map of referenced sub type name → that sub type's fields, e.g. Flow → sub types.FlowActionCall file information : File naming conventions and extensions directory location : Where files are stored in SFDX projects wsdl segment : XML schema definition from the WSDL declarative metadata sample definition : Example XML code Some metadata types have additional sections specific to their functionality. See the [Index Table](references/metadata index table.md) for a complete breakdown. More detail: background on why token optimization matters, worked usage examples, common workflows, a full section glossary, and versioning/support notes live in [ references/usage guide.md ](references/usage guide.md). Load it with the Read tool only when needed. Token Optimization Strategies CRITICAL : To minimize token usage and costs: 1. Load only the specific metadata type(s) you need, not the full corpus 2. Load only specific sections from each file, not entire files Section Specific Loading (BEST PRACTICE) CRITICAL WARNING: DO NOT use the read file tool (or any whole file reading tool) on these JSON files! read file loads the entire file content into your context, defeating the purpose of section specific consumption. You will waste 60 80% of your token budget loading unnecessary WSDL segments and verbose sections. (Using Read on small files such as this SKILL.md or the index table is fine — this rule is only about the large metadata type JSON files.) Approach : Programmatically parse the JSON file and extract ONLY the sections you need using code, not whole file reading tools. Working Examples Available : We provide complete, working code examples in multiple languages: Python : [ examples/python section loading.py ](examples/python section loading.py) Shows json.load() with section extraction JavaScript/Node.js : [ examples/javascript section loading.js ](examples/javascript section loading.js) Shows JSON.parse() with section extraction Bash + jq : [ examples/bash section loading.sh ](examples/bash section loading.sh) Shows jq command line JSON processing See [ examples/README.md ](examples/README.md) for complete documentation and usage instructions. Quick Pattern (adapt to your language): 1. Read the JSON file 2. Parse it into a data structure 3. Extract ONLY the sections you need (e.g., fields , description ) 4. Ignore verbose sections ( wsdl segment , declarative metadata sample definition ) What NOT to Do NEVER use the read file tool on these JSON files : NEVER load all files : Token Impact : Section specific: 50 200 tokens per metadata type Entire file: 500 2000 tokens per metadata type Savings: 60 80% per file When to Load Multiple Types Related types : CustomObject + CustomField + ValidationRule Permission sets : Profile + PermissionSet + PermissionSetGroup UI components : Layout + CompactLayout + QuickAction Automation : Flow + WorkflowRule + ApexTrigger When to Load Specific Sections (STRONGLY RECOMMENDED) Many metadata types have large WSDL segments or extensive field lists. Always load only the specific sections you need from each JSON file rather than consuming the entire file: 1. First, check available sections by reading just the sections array from the JSON 2. Extract only the sections you need (e.g., fields for field definitions, description for overview) 3. Skip WSDL segments unless you specifically need schema validation 4. Skip declarative metadata sample definition unless you need complete XML examples This approach can reduce token consumption by 60 80% per file by excluding verbose WSDL definitions and lengthy examples. Conceptual Approach to Using This Skill Step 1: Identify Your Need Ask yourself: What am I trying to build or modify? Which Salesforce metadata type(s) am I working with? Which specific information do I need? Field definitions only? → Load fields section Understanding what it does? → Load description section XML example? → Load declarative metadata sample definition section Schema validation? → Load wsdl segment section (rarely needed) Step 2: Find the Right Type Use one of these methods: Direct reference : If you know the type name (e.g., "CustomObject") Index search : Check references/metadata index table.md for related types Common types : See the "Quick Reference: Common Metadata Types" section below Step 3: Load Selectively (Section Specific) Decision Tree for Section Loading : Request format : Single section (BEST): "Show me only the 'fields' section from ApexClass.json" Multiple sections : "Load 'fields' and 'description' from CustomObject.json" Skip verbose sections : Never load wsdl segment unless explicitly needed Step 4: Apply to Your Code Use the loaded information to: Create new metadata XML files Understand existing files in your project Validate field names and types Generate correct XML structure with proper namespaces File Location All metadata type JSON files are located in: Path Resolution When using this skill, files are referenced as: Absolute: assets/metadata api/CustomObject.json Relative to skill root: ./assets/metadata api/CustomObject.json The skill will automatically resolve paths based on the working directory. Metadata File Generation Requirements When generating Salesforce metadata XML files, follow these requirements to ensure valid, deployable files. XML Structure Requirements All metadata files must: 1. Include XML declaration : 2. Use correct namespace : 3. Match root element to metadata type : CustomObject → <CustomObject Flow → <Flow Profile → <Profile etc. Namespace Declaration The namespace is required and must be exactly: Correct : Incorrect : Required vs. Optional Fields Each metadata type has different field requirements: Schema required ( required: true in the JSON): the WSDL marks the field as required. Effectively required (not flagged but practically needed): in many cases the WSDL marks fewer fields as required than the authoring contract actually demands. CustomObject is the canonical example — the JSON marks only externalDataSource , externalName , nameField as required: true (the first two are external object only quirks), but a normal c CustomObject also needs label , pluralLabel , deploymentStatus , and sharingModel to deploy. Always cross check with the declarative metadata sample definition examples. Conditionally required : some fields are required only when certain features are enabled. Optional : most fields can be omitted if not needed. Example from CustomObject (note: practical authoring needs more than what required: true marks): Validation Tips Before deploying: 1. Validate XML syntax : Ensure well formed XML (matching tags, proper nesting) 2. Check required fields : Verify all required fields are present 3. Verify namespaces : Namespace must be exact 4. Test field types : Ensure field values match expected types 5. Use Salesforce CLI : Run sf project deploy validate to catch errors More detail: field type→XML mapping tables, file naming/two file/child type conventions, and full well formed file examples are in [ references/usage guide.md ](references/usage guide.md). Duplicate and Ambiguous Type Names Some Metadata API type names also exist as Enterprise/Data API or Tooling API object names. Examples include ApexClass, ApexTrigger, CustomField, CustomObject, EmailTemplate, Layout, Profile, PermissionSet, RecordType, StaticResource, WebLink, ValidationRule, and Flow. When the prompt is ambiguous (e.g., "tell me about Profile" or "what fields are on ApexClass"), ask whether the user wants: 1. Metadata API XML structure for source/deployment authoring (this skill, e.g. .profile meta.xml , .cls meta.xml ). 2. Enterprise/Data API runtime sObject/record reference (no dedicated skill currently — fall back to the Salesforce API family router). 3. Tooling API developer tooling record reference (no dedicated skill currently — fall back to the Salesforce API family router). Heuristics that resolve most ambiguity without asking: Mentions of package.xml , force app/ , sfdx , .meta.xml , "deploy", "retrieve", "authoring", "blueprint", "template", "class definition", or "permissions" in a deployment sense → Metadata API (this skill). "What fields are on X" / "what columns" / "DML" / "SOQL" / "

platform-metadata-api-context-get