platform-metadata-api-context-get

SKILL.md

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:

Section-specific (BEST): "Show me only the 'fields' section from CustomObject.json"

Multiple sections: "Show me 'fields' and 'description' from Flow.json"

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:

{
  "sections": ["title", "description", "fields", "wsdl_segment", ...],
  "title": "MetadataTypeName - Metadata API",
  "description": "Plain-text description of the metadata type.",
  "fields": {
    "fieldName": {
      "type": "string",
      "description": "Field description",
      "required": true
    }
  },
  "file_information": ".object",
  "directory_location": "objects",
  "wsdl_segment": "<xsd:complexType>...</xsd:complexType>",
  "declarative_metadata_sample_definition": [
    {
      "description": "Example description",
      "code": "<?xml version=\"1.0\"?>\n<MetadataType>...\n</MetadataType>"
    }
  ]
}

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 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. Load it with the Read tool only when needed.

Token Optimization Strategies

CRITICAL: To minimize token usage and costs:

Load only the specific metadata type(s) you need, not the full corpus

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 - Shows json.load() with section extraction

JavaScript/Node.js: examples/javascript_section_loading.js - Shows JSON.parse() with section extraction

Bash + jq: examples/bash_section_loading.sh - Shows jq command-line JSON processing

See examples/README.md for complete documentation and usage instructions.

Quick Pattern (adapt to your language):

Read the JSON file

Parse it into a data structure

Extract ONLY the sections you need (e.g., fields, description)

Ignore verbose sections (wsdl_segment, declarative_metadata_sample_definition)

What NOT to Do

NEVER use the read_file tool on these JSON files:

read_file assets/metadata_api/CustomObject.json  # Loads entire file into context!
read_file assets/metadata_api/Flow.json          # Wastes 60-80% tokens!

NEVER load all files:

read_file assets/metadata_api/*.json  # This loads ~15MB of data!

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:

First, check available sections by reading just the sections array from the JSON

Extract only the sections you need (e.g., fields for field definitions, description for overview)

Skip WSDL segments unless you specifically need schema validation

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:

Need field definitions?
  → Load ONLY 'fields' section (~50-200 tokens)

Need to understand what the type does?
  → Load ONLY 'description' section (~20-100 tokens)

Need XML structure example?
  → Load ONLY 'declarative_metadata_sample_definition' (~100-300 tokens)

Need all three?
  → Load 'fields' + 'description' + 'declarative_metadata_sample_definition'
  → Still skip 'wsdl_segment', 'file_information', 'directory_location'
  → Savings: ~60-70% vs loading entire file

Need schema validation?
  → Only then load 'wsdl_segment' (this is verbose)

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:

assets/metadata_api/
├── CustomObject.json
├── Flow.json
├── ApexClass.json
├── Profile.json
└── ... (600 more files)

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:

Include XML declaration:

<?xml version="1.0" encoding="UTF-8"?>

Use correct namespace:

<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">

Match root element to metadata type:

CustomObject → <CustomObject>

Flow → <Flow>

Profile → <Profile>

etc.

Namespace Declaration

The namespace is required and must be exactly:

http://soap.sforce.com/2006/04/metadata

Correct:

<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">

Incorrect:

<CustomObject>  <!-- Missing namespace -->
<CustomObject xmlns="http://salesforce.com/metadata">  <!-- Wrong namespace -->

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):

{
  "fields": {
    "nameField": {
      "type": "CustomField",
      "description": "The name field for the custom object",
      "required": true
    },
    "label": {
      "type": "string",
      "description": "The label for the custom object (effectively required for normal __c objects)",
      "required": false
    },
    "sharingModel": {
      "type": "SharingModel (enumeration)",
      "description": "The sharing model for the object (effectively required for normal __c objects)",
      "required": false
    },
    "enableHistory": {
      "type": "boolean",
      "description": "Enable field history tracking",
      "required": false
    }
  }
}

Validation Tips

Before deploying:

Validate XML syntax: Ensure well-formed XML (matching tags, proper nesting)

Check required fields: Verify all required fields are present

Verify namespaces: Namespace must be exact

Test field types: Ensure field values match expected types

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.

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:

Metadata API XML structure for source/deployment authoring (this skill, e.g. .profile-meta.xml, .cls-meta.xml).

Enterprise/Data API runtime sObject/record reference (no dedicated skill currently — fall back to the Salesforce API family router).

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" / "query" / "REST" / "sObject" / "record" / "runtime" → Enterprise/Data or Tooling API (other skill).

Tooling-specific signals: "Tooling API", ApexCodeCoverage, EntityDefinition, TraceFlag, "code coverage", "compile errors", SymbolTable, debug logging → Tooling API.

Default-when-no-signals rule: if the prompt has none of the signals above AND this skill (platform-metadata-api-context-get) was invoked directly by name, default to the Metadata API interpretation and explicitly disclose the assumption to the user (e.g., "Interpreting this as the Metadata API type for .cls-meta.xml authoring; let me know if you meant the Tooling API record or Enterprise/Data sObject"). The skill-invocation context itself is a signal of authoring/deployment intent.

Troubleshooting

File Not Found

Problem: Cannot find metadata type file

Solutions:

File names are case-sensitive PascalCase with no separators (e.g., CustomObject.json, NOT customobject.json, Custom_Object.json, or Custom-Object.json).

Before declaring "not found", consult references/metadata_index_table.md. Use this two-pass recovery algorithm against the index:

Normalize-and-substring (handles case + separator variants): strip non-alphanumeric characters and lowercase both the query and each index entry, then look for substring matches. Resolves: customobject, Custom_Object, Custom-Object → CustomObject.

On miss, fuzzy-match (handles missing-letter typos): use difflib.get_close_matches(query_normalized, index_normalized, n=3, cutoff=0.7) or Levenshtein distance ≤ 2. Resolves: customfeld → CustomField, apxclass → ApexClass. Pure substring matching cannot recover character deletions.

Multi-hit tiebreaker: when normalize-and-substring returns multiple matches (e.g., customobject matches both CustomObject and CustomObjectTranslation), prefer the entry whose normalized length equals the normalized query length; otherwise prefer the shortest match.

Some types have unexpected naming conventions (no underscores, no spaces, no abbreviations like "OAuth"); the index is the source of truth.

SOAP Envelope / Header Types (thin by design)

Two related patterns to recognize:

Result types (AsyncResult, SaveResult, DeleteResult, UpsertResult, Error, DescribeMetadataResult, etc.) — fields is empty AND wsdl_segment is populated. These are SOAP response wrappers; their schema lives entirely in wsdl_segment. Consume that section if you need their structure. They are not deployable source files.

SOAP request headers (AllOrNoneHeader, SessionHeader, CallOptions, DebuggingHeader, OwnerChangeOptions, etc.) — fields has 1–2 minimal entries, no wsdl_segment. These configure SOAP request behavior; they are call-time options, not metadata you author or deploy.

In both cases, the thin JSON output is correct. Don't try to author a .AsyncResult-meta.xml — these types have no source-file form.

Missing Section

Problem: Expected section not in JSON file

Solutions:

Check the sections array to see what's available

Not all metadata types have all sections

Some sections are type-specific (noted in index table)

Incomplete Field Information

Problem: Field definition lacks details

Solutions:

Check wsdl_segment for complete schema definition

Some fields have complex types defined in WSDL

Cross-reference with Salesforce documentation for enumerations

Following Sub-Type Pointers (e.g., ProfileObjectPermissions[])

When the fields section gives a complex type name like ProfileObjectPermissions[] or LayoutItem[] or ApprovalStep[], the sub-fields of that nested type are NOT in the fields section — they live in wsdl_segment for that complex type. The skill's "skip wsdl_segment by default" rule is for token economy on the simple-field path; for nested types you need to drill in.

Worked example — find the sub-fields of objectPermissions on Profile:

# 1. Get the field type name from the fields section
jq '.fields.objectPermissions' assets/metadata_api/Profile.json
# → {"type": "ProfileObjectPermissions[]", ...}

# 2. Pull just the matching complexType from wsdl_segment using grep -A
jq -r '.wsdl_segment' assets/metadata_api/Profile.json   | grep -A 30 'complexType name="ProfileObjectPermissions"'

The grep -A N window keeps token cost ~150 tokens instead of loading the whole wsdl_segment (which can be 5K+ tokens on large types). Use this pattern any time fields returns a Foo[] type and you need Foo's sub-fields.

XML Generation Errors

Problem: Generated XML fails validation

Solutions:

Verify namespace is exactly: http://soap.sforce.com/2006/04/metadata

Check all required fields are present

Ensure field values match expected types

Validate XML syntax (closing tags, proper nesting)

Deployment Failures

Problem: Metadata file won't deploy

Solutions:

Run sf project deploy validate first

Check Salesforce API version compatibility

Verify file naming matches conventions

Ensure directory structure matches SFDX format

Quick Reference: Common Metadata Types

Here are the most frequently used metadata types:

CustomObject: defines the schema for a custom sObject, including fields, relationships, and settings

Flow: automates business processes using a visual canvas of elements and connectors

ApexClass: compiled Apex server-side class; includes body, API version, and status

ApexTrigger: Apex code that executes before/after DML events on a specific sObject

Profile: controls object/field permissions, app visibility, and login settings for a user profile

PermissionSet: additive set of permissions granted to users independently of their profile

CustomField: defines a field on a standard or custom object, including type, picklist values, and formula

Layout: controls the arrangement of fields and related lists on a record detail/edit page

ValidationRule: enforces data quality by preventing saves when a formula condition is true

ApexPage: Visualforce page definition, including controller reference and markup

ApexComponent: reusable Visualforce component that can be embedded in pages

CustomTab: defines a tab pointing to a custom object, Visualforce page, or web URL

CustomApplication: defines an app's tab bar, nav items, and branding

LightningComponentBundle: LWC bundle including JS, HTML, and metadata descriptor

AuraDefinitionBundle: Aura (Lightning) component bundle with component, controller, helper files

StaticResource: uploaded file (JS, CSS, image, ZIP) accessible from Visualforce and LWC

EmailTemplate: email template for use in workflow rules, Process Builder, or Apex

Report: saved report definition including filters, groupings, and columns

Dashboard: collection of dashboard components backed by reports

For a complete list of all metadata types, see Index Table.