/platform-value-set-generate

name: platform-value-set-generate
description: "Use to create, generate, or validate a Salesforce GlobalValueSet (reusable picklist shared across fields) or customize a StandardValueSet (built-in picklists like Industry, Lead Source, Opportunity Stage). Trigger on global/standard value set, reusable picklist, .globalValueSet-meta.xml or .standardValueSet-meta.xml, or deploy errors adding values to a standard picklist. DO NOT TRIGGER for a one-off inline picklist on a single field with no reuse — use platform-custom-field-generate."
metadata:
  version: "1.0"
  domains: ["Platform"]
  minApiVersion: "60.0"
  relatedSkills:
    - "platform-custom-field-generate"
  cliTools:
    - tool: ["sf"]
      semver: ">=2.0.0"
  mcpTools:
    metadata-grounding:
      tools: ["query_metadata", "search_metadata"]
      semver: ">=1.0.0"

Overview

Generates and validates the two reusable picklist value-set metadata types — **GlobalValueSet** (a new reusable set shared across fields) and **StandardValueSet** (customizing a built-in catalog picklist like Industry or Lead Source) — and wires a CustomField to one via `<valueSetName>`.

Scope

• **In scope:** creating a GlobalValueSet, customizing a StandardValueSet, referencing either from a field, and the related deployment errors.
• **Out of scope:** a one-off inline picklist on a single field with no reuse → use **`platform-custom-field-generate`** (inline `<valueSetDefinition>`). Generating the *field* that references a value set is also `platform-custom-field-generate`'s job; this skill produces the value set itself.

**Two different metadata types — do not confuse them:**

| Concern | GlobalValueSet | StandardValueSet | |---------|----------------|------------------| | Folder | `globalValueSets/` | `standardValueSets/` | | File suffix | `.globalValueSet-meta.xml` | `.standardValueSet-meta.xml` | | Root element | `<GlobalValueSet>` | `<StandardValueSet>` | | Name source | filename (dev name) | `<fullName>` = fixed catalog name | | Value element | `<customValue>` | `<standardValue>` | | Can add NEW values? | Yes | No — modify existing only | | Can create a new NAME? | Yes | No — only the fixed catalog | | `*` wildcard in package.xml | Supported | Not supported |

---

Specification

1. Purpose

This document defines the mandatory constraints for generating value-set metadata XML. The agent must verify these constraints before outputting XML to prevent Metadata API deployment errors.

• **GlobalValueSet** — a reusable, named set of picklist values defined once and referenced by any number of picklist/multi-select fields. Use when the same value list is shared across multiple fields.
• **StandardValueSet** — the value list behind a Salesforce-defined standard picklist (Industry, Lead Source, etc.). You can only **modify** the values in a fixed catalog of named sets; you cannot invent a new set or add brand-new values.

---

2. GlobalValueSet — Syntactic Essentials

**File:** `globalValueSets/<DeveloperName>.globalValueSet-meta.xml`

The developer name comes from the **filename**, not a `<fullName>` tag.

Required Elements

| Element | Requirement | Notes | |---------|-------------|-------| | `<masterLabel>` | Required | UI label for the value set | | `<sorted>` | Required | `true` = alphabetize values in the UI; `false` = preserve listed order | | `<customValue>` | Required (≥1) | One per value (see below) |

`<customValue>` Sub-Elements

| Sub-element | Requirement | Notes | |-------------|-------------|-------| | `<fullName>` | Required | The value's API name. Use the value text **as the user spelled it** — spaces are allowed and must be preserved (e.g. `Closed Won`, not `Closed_Won`). Must start with a letter. This is a value name, NOT a field API name, so do not append `__c` or replace spaces with underscores. | | `<default>` | Optional | At most one value `true`. Omit it (or use `false`) on the rest — it is not required on every value. | | `<label>` | Required | UI label for the value | | `<color>` | Optional | Hex color, e.g. `#FF0000` | | `<isActive>` | Optional | Omit (active) or `false` to deactivate | | `<description>` | Optional | Per-value description |

The `__gvs` Suffix — do NOT use it in metadata

**Rule: reference a GlobalValueSet by its bare developer name. Never add `__gvs`.**

In API 57.0+ orgs the platform *stores/displays* a GlobalValueSet's developer name with a `__gvs` suffix internally, but the **Metadata API (deploy and retrieve) always uses the bare name** — `<valueSetName>Priority_Levels</valueSetName>`, not `Priority_Levels__gvs`. The suffix was briefly emitted by a Winter '23 change that caused deploy failures and was patched out. So:

• The file is `globalValueSets/Priority_Levels.globalValueSet-meta.xml` — **no `__gvs`** in the filename.
• A field references it as `<valueSetName>Priority_Levels</valueSetName>` — **no `__gvs`**.
• If a retrieve shows `Priority_Levels__gvs` in the org or you see a "returned from org but not found in local project" warning, that's the expected org-storage display — keep your local metadata on the bare name.

CORRECT — GlobalValueSet

<?xml version="1.0" encoding="UTF-8"?>
<GlobalValueSet xmlns="http://soap.sforce.com/2006/04/metadata">
    <masterLabel>Priority Levels</masterLabel>
    <sorted>false</sorted>
    <customValue>
        <fullName>Critical</fullName>
        <default>false</default>
        <label>Critical</label>
    </customValue>
    <customValue>
        <fullName>High</fullName>
        <default>false</default>
        <label>High</label>
    </customValue>
    <customValue>
        <fullName>Medium</fullName>
        <default>true</default>
        <label>Medium</label>
    </customValue>
    <customValue>
        <fullName>Low</fullName>
        <default>false</default>
        <label>Low</label>
    </customValue>
</GlobalValueSet>

INCORRECT — GlobalValueSet

<GlobalValueSet xmlns="http://soap.sforce.c