When to Use This Skill

Use this skill when you need to:

Create custom fields on any object
Generate field metadata for any field type
Set up relationship fields (Lookup or Master-Detail)
Create formula or roll-up summary fields
Troubleshoot deployment errors related to custom fields

Salesforce Custom Field Generator and Validator

Overview

Generate and validate Salesforce Custom Field metadata with mandatory constraints to prevent deployment errors. This skill has special focus on the highest-failure-rate field types: Roll-up Summary and Master-Detail relationships.

Specification

1. Purpose

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

Critical Focus Areas:

Roll-up Summary field format errors
Master-Detail field attribute restrictions
Lookup Filter restrictions

2. Universal Mandatory Attributes

Every generated field must include these tags:

Attribute	Requirement	Notes
`<fullName>`	Required	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`
`<label>`	Required	The UI name (Title Case)
`<description>`	Mandatory	State the business "why" behind the field
`<inlineHelpText>`	Mandatory	Provide actionable guidance for the end-user. Must add value beyond the label (e.g., "Enter the value in USD including tax" instead of just "The amount")

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

3. Technical Interplay: Precision, Scale, and Length

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

For standard TextArea types, the Metadata API requires <length>255</length>, even though it isn't configurable in the UI.

Visible Lines

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

4. Field Data Types

4.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` with `valueSetDefinition` and `restricted`
Text	`Text`	`length` (Max 255)
Text Area	`TextArea`	`<length>255</length>`
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

4.2 Computed & Multi-Value Types

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

4.3 Specialized Types

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

Picklist `restricted` Rule

The <restricted> boolean inside <valueSet> controls whether only admin-defined values are allowed.

IF user does not specify → default to <restricted>true</restricted> (restricted, avoids performance issues with large picklist value sets)
IF user explicitly says the picklist should allow custom/new values, or mentions "unrestricted" or "open" → set <restricted>false</restricted>
Restricted picklists are limited to 1,000 total values (active + inactive)

<valueSet>
  <restricted>true</restricted>
  <valueSetDefinition>
    <sorted>false</sorted>
    <value>
      <fullName>Option_A</fullName>
      <default>false</default>
      <label>Option A</label>
    </value>
  </valueSetDefinition>
</valueSet>

5. Master-Detail Relationship Rules ⭐ CRITICAL

Master-Detail fields have strict attribute restrictions that differ from Lookup fields. Violating these rules causes deployment failures.

Forbidden Attributes on Master-Detail Fields

NEVER include these attributes on Master-Detail fields:

Forbidden Attribute	Why	What Happens
`<required>`	Master-Detail is ALWAYS required by design	Deployment error
`<deleteConstraint>`	Master-Detail ALWAYS cascades deletes	Deployment error
`<lookupFilter>`	Only supported on Lookup fields	Deployment error

Master-Detail vs Lookup Comparison

Attribute	Master-Detail	Lookup
`<required>`	❌ FORBIDDEN	✅ Optional
`<deleteConstraint>`	❌ FORBIDDEN (always CASCADE)	✅ Required (`SetNull`, `Restrict`, `Cascade`)
`<lookupFilter>`	❌ FORBIDDEN	✅ Optional
`<relationshipOrder>`	✅ Required (0 or 1)	❌ Not applicable
`<reparentableMasterDetail>`	✅ Optional	❌ Not applicable
`<writeRequiresMasterRead>`	✅ Optional	❌ Not applicable

❌ INCORRECT — Master-Detail with forbidden attributes:

<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Account__c</fullName>
  <label>Account</label>
  <type>MasterDetail</type>
  <referenceTo>Account</referenceTo>
  <relationshipName>Contacts</relationshipName>
  <relationshipOrder>0</relationshipOrder>
  <required>true</required>           <!-- WRONG: Remove this -->
  <deleteConstraint>Cascade</deleteConstraint>  <!-- WRONG: Remove this -->
  <lookupFilter>                       <!-- WRONG: Remove this entire block -->
    <active>true</active>
    <filterItems>
      <field>Account.Type</field>
      <operation>equals</operation>
      <value>Customer</value>
    </filterItems>
  </lookupFilter>
</CustomField>

Errors:

Master-Detail Relationship Fields Cannot be Optional or Required
Can not specify 'deleteConstraint' for a CustomField of type MasterDetail
Lookup filters are only supported on Lookup Relationship Fields

✅ CORRECT — Master-Detail field:

<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Account__c</fullName>
  <label>Account</label>
  <description>Links this record to its parent Account</description>
  <type>MasterDetail</type>
  <referenceTo>Account</referenceTo>
  <relationshipLabel>Child Records</relationshipLabel>
  <relationshipName>ChildRecords</relationshipName>
  <relationshipOrder>0</relationshipOrder>
  <reparentableMasterDetail>false</reparentableMasterDetail>
  <writeRequiresMasterRead>false</writeRequiresMasterRead>
  <!-- NO required, deleteConstraint, or lookupFilter -->
</CustomField>

✅ CORRECT — Lookup field (with optional attributes):

<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Related_Account__c</fullName>
  <label>Related Account</label>
  <description>Optional link to a related Account</description>
  <type>Lookup</type>
  <referenceTo>Account</referenceTo>
  <relationshipLabel>Related Records</relationshipLabel>
  <relationshipName>RelatedRecords</relationshipName>
  <required>false</required>
  <deleteConstraint>SetNull</deleteConstraint>
  <lookupFilter>
    <active>true</active>
    <filterItems>
      <field>Account.Type</field>
      <operation>equals</operation>
      <value>Customer</value>
    </filterItems>
    <isOptional>false</isOptional>
  </lookupFilter>
</CustomField>

Additional Master-Detail Rules

Relationship Order: First Master-Detail on object = 0, second = 1
Relationship Name: Must be a plural PascalCase string (e.g., Travel_Bookings)
Junction Objects: Use two Master-Detail fields for standard many-to-many (enables Roll-ups)
Limit: Maximum 2 Master-Detail relationships per object. Use Lookup for additional relationships.

6. Roll-Up Summary Field Rules ⭐ CRITICAL

Roll-up Summary fields have the highest deployment failure rate. Follow these rules exactly.

Required Elements for Roll-Up Summary

Element	Requirement	Format
`<type>`	Required	Always `Summary`
`<summaryOperation>`	Required	`count`, `sum`, `min`, or `max`
`<summaryForeignKey>`	Required	`ChildObject__c.MasterDetailField__c`
`<summarizedField>`	Conditional	Required for `sum`, `min`, `max`. NOT for `count`

Forbidden Elements on Roll-Up Summary

NEVER include these attributes on Roll-Up Summary fields:

Forbidden Attribute	Why
`<precision>`	Summary inherits from summarized field
`<scale>`	Summary inherits from summarized field
`<required>`	Not applicable to Summary fields
`<length>`	Not applicable to Summary fields

Format Rules for summaryForeignKey and summarizedField

CRITICAL: Both summaryForeignKey and summarizedField MUST use the fully qualified format:

ChildObjectAPIName__c.FieldAPIName__c

Decision Logic:

summaryForeignKey = ChildObject__c.MasterDetailFieldOnChild__c
summarizedField = ChildObject__c.FieldToSummarize__c

❌ INCORRECT — Roll-Up Summary with common errors:

<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Total_Amount__c</fullName>
  <label>Total Amount</label>
  <type>Summary</type>
  <precision>18</precision>           <!-- WRONG: Remove - inherited from source -->
  <scale>2</scale>                    <!-- WRONG: Remove - inherited from source -->
  <summaryOperation>sum</summaryOperation>
  <summaryForeignKey>Order__c</summaryForeignKey>        <!-- WRONG: Missing field name -->
  <summarizedField>Amount__c</summarizedField>           <!-- WRONG: Missing object name -->
</CustomField>

Errors:

Can not specify 'precision' for a CustomField of type Summary
Must specify the name in the CustomObject.CustomField format (e.g. Account.MyNewCustomField)

✅ CORRECT — Roll-Up Summary (SUM operation):

<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Total_Amount__c</fullName>
  <label>Total Amount</label>
  <description>Sum of all line item amounts</description>
  <inlineHelpText>Automatically calculated from child line items</inlineHelpText>
  <type>Summary</type>
  <summaryOperation>sum</summaryOperation>
  <summarizedField>Order_Line_Item__c.Amount__c</summarizedField>
  <summaryForeignKey>Order_Line_Item__c.Order__c</summaryForeignKey>
  <!-- NO precision, scale, required, or length -->
</CustomField>

✅ CORRECT — Roll-Up Summary (COUNT operation):

<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Line_Item_Count__c</fullName>
  <label>Line Item Count</label>
  <description>Count of related line items</description>
  <inlineHelpText>Automatically calculated from child records</inlineHelpText>
  <type>Summary</type>
  <summaryOperation>count</summaryOperation>
  <summaryForeignKey>Order_Line_Item__c.Order__c</summaryForeignKey>
  <!-- NO summarizedField needed for COUNT -->
  <!-- NO precision, scale, required, or length -->
</CustomField>

✅ CORRECT — Roll-Up Summary (MIN operation):

<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Earliest_Due_Date__c</fullName>
  <label>Earliest Due Date</label>
  <description>Earliest due date among all line items</description>
  <inlineHelpText>Shows the soonest deadline</inlineHelpText>
  <type>Summary</type>
  <summaryOperation>min</summaryOperation>
  <summarizedField>Order_Line_Item__c.Due_Date__c</summarizedField>
  <summaryForeignKey>Order_Line_Item__c.Order__c</summaryForeignKey>
</CustomField>

✅ CORRECT — Roll-Up Summary (MAX operation):

<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Highest_Price__c</fullName>
  <label>Highest Price</label>
  <description>Maximum unit price among all line items</description>
  <inlineHelpText>Shows the most expensive item</inlineHelpText>
  <type>Summary</type>
  <summaryOperation>max</summaryOperation>
  <summarizedField>Order_Line_Item__c.Unit_Price__c</summarizedField>
  <summaryForeignKey>Order_Line_Item__c.Order__c</summaryForeignKey>
</CustomField>

Roll-Up Summary Quick Reference

Operation	summarizedField Required?	Use Case
`count`	NO	Count number of child records
`sum`	YES	Add up numeric values
`min`	YES	Find smallest value
`max`	YES	Find largest value

Roll-Up Summary Prerequisites

Roll-Up Summary fields can ONLY be created on the parent object in a Master-Detail relationship
The child object MUST have a Master-Detail field pointing to this parent
The summarized field must exist on the child object

7. Formula Field Rules

Formula Result Types

A Formula is not a type itself. The <formula> tag is added to a field whose <type> is set to the result data type:

Checkbox, Currency, Date, DateTime, Number, Percent, Text

Formula XML Generation Rules

The contents of the <formula> tag MUST be wrapped in a <![CDATA[ ... ]]> section. This prevents the XML parser from interpreting formula operators (like &, <, >) as XML markup.
If the formula text itself contains the literal sequence ]]>, escape it by breaking the CDATA block: e.g., <![CDATA[Text_Field__c & "]]]]><![CDATA[>"]]>
NEVER use an attribute or tag named returnType. This does not exist in the Metadata API. The <type> tag defines the return data type of the formula result.

formulaTreatBlanksAs Rule