/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 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 field, formula field, picklist, lookup, master-detail, validation rule, permission set, profile, custom tab, lightning record page, flexipage, list view, custom application, flow, layout, record type, sharing rules, report, and 604 Metadata API types. It provides the authoritative schema, fields, field properties, required flags, allowed enum values, and XML structure so generated *-meta.xml deploys cleanly — skipping it causes hallucinated element names and deploy failures. Trigger on *-meta.xml, metadata schema, api context, 'Salesforce metadata', or 'sfdx project'. 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/suppor