/platform-custom-field-generate

name: platform-custom-field-generate
description: "Use this skill when users need to create, generate, or validate Salesforce Custom Field metadata. Trigger when users mention custom fields, field types, Roll-up Summary fields, Master-Detail relationships, Lookup relationships, formula fields, picklists, dependent (controlling) picklists, referencing a value set from a field, or scoping/limiting picklist values for a specific record type. Also use when users encounter field deployment errors, especially around Roll-up Summary format, Master-Detail constraints, formula issues, or a record type that won't deploy without a business process. Use this skill for custom field metadata work, field generation, and field troubleshooting. DO NOT TRIGGER for creating or customizing the value set itself — defining a new GlobalValueSet, or modifying a StandardValueSet catalog like Industry or Lead Source — use platform-value-set-generate instead; this skill covers the field that references a value set, not the value set definition."
metadata:
  version: "1.0"
  minApiVersion: "60.0"
  relatedSkills: ["platform-value-set-generate", "platform-validation-rule-generate"]

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 outputs even though the Metadata API does not enforce them — omitting them produces 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 Metadata API fixes the length at 255 implicitly and **rejects an explicit `<length>` value** with "Can not specify 'length' for a CustomField of type TextArea". Omit `<length>` entirely; the field only needs `<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` | | 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`, `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