/platform-custom-field-generate

name: platform-custom-field-generate
description: "Use when users create, generate, or validate Salesforce Custom Field metadata. Trigger on custom fields, field types, Roll-Up Summary, Master-Detail/Lookup relationships, formula fields, picklists, dependent (controlling) picklists, referencing a value set from a field, or scoping picklist values per record type; also field deployment errors, including a record type that won't deploy without a business process. DO NOT TRIGGER for creating/customizing the value set itself — a new GlobalValueSet or a StandardValueSet catalog like Industry — use platform-value-set-generate; this skill covers the field that references a value set, not the value set definition."
metadata:
  version: "1.0"
  domains: ["Platform"]
  minApiVersion: "60.0"
  relatedSkills:
    - "platform-metadata-api-context-get"
    - "platform-validation-rule-generate"
    - "platform-value-set-generate"
  mcpTools:
    metadata-grounding:
      tools: ["search_metadata"]
      semver: ">=1.0.0"

Salesforce Custom Field Generator and Validator

Overview

Generates and validates Salesforce CustomField metadata XML, with special handling for the **highest-failure-rate types** — Roll-Up Summary and Master-Detail. The agent must verify the constraints below before outputting XML to prevent Metadata API deployment errors.

---

1. Universal Mandatory Attributes

Every generated field must include these tags:

| Attribute | Requirement | Notes | |-----------|-------------|-------| | `<fullName>` | Required | **Field** name only: derive from `<label>` — capitalize each word, replace spaces with `_`, append `__c`. Must start with a letter. E.g., label `Total Contract Value` → `Total_Contract_Value__c`. This rule is for the FIELD name. **Picklist VALUE `<fullName>` is different — keep it exactly as the user spelled it, spaces and all, no `__c`** (e.g. `Closed Won`, NOT `Closed_Won`). See [`references/advanced-picklists.md`](references/advanced-picklists.md) (ref §3). | | `<label>` | Required | The UI name (Title Case) | | `<description>` | Always include | Explain the business reason *why* this field exists. | | `<inlineHelpText>` | Always include | Actionable end-user guidance that adds value beyond the label (e.g., "Enter the value in USD including tax", not "The amount"). |

`<description>` and `<inlineHelpText>` are mandatory even though the Metadata API does not enforce them — omitting them yields low-quality metadata.

**File path (SFDX source format):** save each field as `force-app/main/default/objects/<Object>/fields/<FieldName>__c.field-meta.xml`, where `<Object>` is the object's API name (`Account`, `Opportunity`, or a custom `Inventory_Item__c`). A correct XML at the wrong path is never seen by the Metadata API.

External ID Configuration

**Trigger:** If the user mentions "integration," "importing data," "external system ID," or "unique key from [System Name]," set `<externalId>true</externalId>`.

**Applicable Types:** Text, Number, Email

---

2. Precision, Scale, and Length Rules

To ensure deployment success, follow these mathematical constraints:

Precision vs. Scale Rules

• `precision` is the total digits; `scale` is the decimal digits
• **Rule:** `precision ≤ 18` AND `scale ≤ precision`
• **Calculation:** Digits to the left of decimal = `precision - scale`

The "Fixed 255" Rule

**TextArea: do NOT include `<length>`** — the API fixes it at 255 implicitly and rejects an explicit value ("Can not specify 'length' for a CustomField of type TextArea"). The field needs only `<fullName>`, `<label>`, and `<type>TextArea</type>`.

Visible Lines

Mandatory for Long/Rich text and Multi-select picklists to control UI height.

---

3. Field Data Types

3.1 Simple Attribute Types

| Type | `<type>` Value | Required Attributes | |------|----------------|---------------------| | Auto Number | `AutoNumber` | `displayFormat` (must include `{0}`), `startingNumber` | | Checkbox | `Checkbox` | Default `defaultValue` to `false` for non-formulas only | | Date | `Date` | No precision/length required | | Date/Time | `DateTime` | No precision/length required | | Email | `Email` | Built-in format validation | | Lookup Relationship | `Lookup` | `referenceTo`, `relationshipName`, `deleteConstraint` | | Master-Detail Relationship | `MasterDetail` | `referenceTo`, `relationshipName`, `relationshipOrder` | | Number | `Number` | `precision`, `scale` | | Currency | `Currency` | Default precision: 18, scale: 2 | | Percent | `Percent` | Default precision: 5, scale: 2 | | Phone | `Phone` | Standardizes phone number formatting | | Picklist | `Picklist` | `valueSet` containing EITHER `valueSetDefinition` (inline) OR `valueSetName` (reference); `restricted` (see "Picklist `restricted` default" below; advanced cases in §3.4) | | Text | `Text` | `length` (Max 255) | | Text Area | `TextArea` | None — do NOT include `<length>`; the API fixes length at 255 implicitly | | Text (Long) | `LongTextArea` | `length`, `visibleLines` (default 3) | | Text (Rich) | `Html` | `length`, `visibleLines` (default 25) | | Time | `Time` | Stores time only (no date) | | URL | `Url` | Validates for protocol and format |

3.2 Computed & Multi-Value Types

| Type | `<type>` Value | Required Attributes | |------|----------------|---------------------| | Formula | Result type (e.g., `Number`) | `formula` (see Section 6), `formulaTreatBlanksAs` | | Roll-Up Summary | `Summary` | See Section 5 for complete requirements | | Multi-Select Picklist | `MultiselectPicklist` | `valueSet`, `visibleLines` (default 4) |

3.3 Specialized Types

| Type | `<type>` Value | Required Attributes | |------|----------------|---------------------| | Geolocation | `Location` | `scale`, `displayLocationInDecimal` |

Picklist `restricted` default

**Always set `<restricted>true</restricted>`** inside `<valueSet>` unless the user explicitly says the picklist should accept custom values not in the admin-def