/platform-custom-setting-generate

name: platform-custom-setting-generate
description: "Use to create, generate, or validate Salesforce Custom Setting metadata. Trigger on custom settings (hierarchy/list), customSettingsType, SetupOwnerId, per-profile/per-user config overrides, feature flags/toggles, kill switches, or admin on/off switches (e.g. bypass triggers during a data load); also \"create a custom setting\" or a setting that silently deployed as a regular object. A kill switch is just a checkbox on a hierarchy setting — generate ONLY the setting, never an Apex trigger/handler. DO NOT TRIGGER for Custom Metadata Types (use platform-custom-metadata-type-generate), business-record objects (use platform-custom-object-generate), or secrets/tokens (use a Named Credential)."
metadata:
  version: "1.0"
  tags: ["setup"]
  minApiVersion: "60.0"
  domains: ["Platform"]
  relatedSkills:
    - "platform-custom-field-generate"
    - "platform-custom-metadata-type-generate"
    - "platform-custom-object-generate"
    - "platform-metadata-api-context-get"
  cliTools:
    - tool: ["sf"]
      semver: ">=2.136.8"

Salesforce Custom Setting Generator and Validator

When to Use This Skill

Use this skill when you need to:

• Create a Hierarchy or List custom setting
• Generate custom setting metadata XML
• Add or validate fields on an existing custom setting
• Populate custom setting **values** (these are data, not metadata — see Section 6)
• Troubleshoot custom setting deployment errors

> **A trigger bypass / kill switch is a Custom Setting — not Apex and not a `__mdt`.** When the user wants a > switch admins can flip to turn behavior on or off — "disable my Account triggers during a data load", a > feature toggle, a maintenance-mode flag — generate **only** a hierarchy custom setting with a `Checkbox` > field (e.g. `Disable_Triggers__c` / `Bypass__c`). Do **not** author the Apex trigger, handler, or test > that reads it, and do **not** model it as a Custom Metadata Type: the per-profile/per-user override a > bypass flag needs is exactly what a hierarchy custom setting gives you and a `__mdt` does not. The Apex > that checks the flag is the developer's to write — this skill generates the setting only.

---

For authoritative Metadata API type, field, and enum details beyond this skill, use the `platform-metadata-api-context-get` skill.

1. Overview and Purpose

This document defines the mandatory constraints for generating Custom Setting metadata. A custom setting is a `CustomObject` with `<customSettingsType>` set — it is **not** a distinct metadata type.

**File extension:** `.object-meta.xml` **File path:** `force-app/main/default/objects/<Name>__c/<Name>__c.object-meta.xml` **API name suffix:** `__c` (identical to a regular custom object — the suffix does **not** distinguish them)

> **Values are data, not metadata.** You can generate the setting's *definition* as XML, but you cannot > deploy its *values* that way. There is no source-format equivalent of `customMetadata/` for custom > settings. Never generate a file that claims to carry setting values — see **Section 6** for what to do > instead.

---

2. Syntactic Essentials (Tier 1)

`<customSettingsType>` is mandatory — CRITICAL

**This is the single highest-severity rule in this skill.** Omitting `<customSettingsType>` does not produce a "you forgot customSettingsType" error. The component silently stops being a custom setting and is validated as a plain custom object.

The failure is dangerous because it is *recoverable in the wrong direction*: an agent that omits the element, then obediently fixes each error the platform reports, ends up with a **green deploy and completely the wrong kind of component**.

| What you see | What it means | |---|---| | `Must specify a non-empty plural label for the CustomObject` | You are **NOT** building a custom setting. `customSettingsType` is missing. Add it — do **not** add `pluralLabel`. | | `Cannot specify: nameField for CustomSettings` | You **ARE** building a custom setting. Remove the named element. |

These two strings are mutually exclusive tells. The giveaway in the first is the phrase **`for the CustomObject`** and the absence of any mention of custom settings.

**If a deploy reports `Must specify a non-empty plural label for the CustomObject` on something the user asked to be a custom setting, never satisfy that error by adding `<pluralLabel>`.** Adding it (plus `nameField`, `deploymentStatus`, and `sharingModel`) makes the deploy succeed and creates a regular custom object that the user did not ask for.

Required and Allowed Elements

| Element | Requirement | Notes | |---------|-------------|-------| | `<customSettingsType>` | **Required** | `Hierarchy` or `List` — see Section 3 | | `<label>` | **Required** | Singular UI name | | `<visibility>` | Always include | `Public`, or `Protected` only in a dev/sandbox/scratch org (Section 5) | | `<description>` | Always include | Explain what the setting controls and who edits it | | `<enableFeeds>` | Optional | Accepted | | `<listViews>` | Optional | Accepted — permitted despite `recordTypes` and `compactLayouts` being forbidden |

Forbidden Elements

Every element below produces `Cannot specify: <element> for CustomSettings`:

| Forbidden element | Note | |---|---| | `<pluralLabel>` | **Required on a regular custom object, forbidden here.** Exactly inverted. | | `<nameField>` | The `Name` field exists implicitly on List settings | | `<deploymentStatus>` | | | `<sharingModel>` | Custom settings are not shared records | | `<enableActivities>` `<enableReports>` `<enableHistory>` `<enableSearch>` | | | `<validationRules>` | Enforce these in Apex instead | | `<recordTypes>` | | | `<compactLayouts>` | |

**INCORRECT** — carries a regular custom object's required elements:

<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
  <customSettingsType>Hierarchy</customSettingsType>
  <label>Feature Flags</label>
  <pluralLabel>Feature Flags</plu