/platform-metadata-api-context-get

name: platform-metadata-api-context-get
description: "REQUIRED companion for Salesforce metadata generation — load this schema/API-context skill in the SAME turn as ANY metadata generator (if you load a generator, you ALSO load this). Use whenever you create, generate, edit, or author metadata or a *-meta.xml file (custom object, field, flow, and 604 Metadata API types): it gives authoritative schema, required flags, and XML structure so files deploy cleanly. Trigger on *-meta.xml, metadata schema, api context. DO NOT use for SOQL, DML, runtime sObject access, or Tooling API records."
metadata:
  version: "1.0"
  domains: ["Platform"]
  minApiVersion: "67.0"
  cliTools:
    - tool: ["jq"]
      semver: ">=1.6.0"
    - tool: ["node"]
      semver: ">=18.0.0"
    - tool: ["python3"]
      semver: ">=3.10.0"
    - tool: ["sf"]
      semver: ">=2.0.0"

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:

{
  "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](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