/platform-flexipage-generate

name: platform-flexipage-generate
description: "Use this skill when users need to create, generate, modify, or validate Salesforce Lightning pages (FlexiPages). Trigger when users mention RecordPage, AppPage, HomePage, Lightning pages, page layouts, adding components to pages, or page customization. Also use when users say things like 'create a Lightning page', 'add a component to a page', 'customize the record page', 'generate a FlexiPage', or when they're working with FlexiPage XML files and need help with components, regions, or deployment errors. Always use this skill for any FlexiPage-related work, even if they just mention 'page' in the context of Salesforce. DO NOT TRIGGER when users ask about Visualforce pages, Aura components without FlexiPage context, page layout assignments in the UI, or Lightning Web Component development that does not involve placing components on a FlexiPage."
allowed-tools: Bash Read Write
metadata:
  version: "1.1"
  domains: ["Platform"]
  minApiVersion: "60.0"
  cliTools:
    - tool: ["python3"]
      semver: ">=3.10.0"
    - tool: ["sf"]
      semver: ">=2.126.4"
  mcpTools:
    metadata-experts:
      tools: ["execute_metadata_action"]
      semver: ">=1.0.0"

When to Use This Skill

Use this skill when you need to:

• Create Lightning pages (RecordPage, AppPage, HomePage)
• Generate FlexiPage metadata XML
• Add components to existing FlexiPages
• Troubleshoot FlexiPage deployment errors
• Understand FlexiPage structure and component configuration
• Work with page layouts or Lightning page customization
• Edit or update ANY *.flexipage-meta.xml file

Specification

Overview

**CRITICAL: When creating NEW FlexiPages, you MUST ALWAYS start with the CLI template command.** Never create FlexiPage XML from scratch - the CLI provides valid structure, proper regions, and correct component configuration that prevents deployment errors.

Generate Lightning pages (RecordPage, AppPage, HomePage) using CLI bootstrapping for component discovery and configuration.

---

Quick Start Workflow

Step 1: Bootstrap with CLI

**MANDATORY FOR NEW PAGES: This step is NOT optional.** Always use the CLI template command when creating a new FlexiPage. The CLI generates valid XML structure, proper regions, and correct metadata that prevents common deployment errors. Only skip this step if you're editing an existing FlexiPage file.

**`<packageDirectory>`** = the `path` value from `sfdx-project.json` → `packageDirectories[0]` (e.g., `force-app`). Read it from the project file before running commands.

sf template generate flexipage \
  --name <PageName> \
  --template <RecordPage|AppPage|HomePage> \
  --sobject <SObject> \
  --primary-field <Field1> \
  --secondary-fields <Field2,Field3> \
  --detail-fields <Field4,Field5,Field6,Field7> \
  --output-dir <packageDirectory>/main/default/flexipages

**CRITICAL:** If the `sf template generate flexipage` command fails, **STOP**.

1. Install the templates plugin:

   sf plugins install templates

2. Retry the `sf template generate flexipage` command 3. Verify the FlexiPage XML file was created

Do NOT continue to Step 2 until the template command succeeds. The generated XML is required for the entire workflow.

**Template-specific requirements**

**RecordPage:**

• Requires `--sobject` (e.g., Account, Custom_Object__c)
• Requires field parameters:
• `--primary-field`: Most important identifying field (e.g., Name)
• `--secondary-fields`: Record summary (recommended 4-6, max 12)
• `--detail-fields`: Full record details, including required fields (e.g., Name)

**AppPage:**

• No additional requirements

**HomePage:**

• No additional requirements

**Field Selection Rules**

• **Validate fields exist**: Use MCP tools or describe commands to discover available fields for the object before specifying them in the command
• **Prefer compound fields**: Use `Name` (not `FirstName`/`LastName`), `BillingAddress` (not `BillingStreet`/`BillingCity`/`BillingState`), `MailingAddress`, etc. when available
• **Include required fields in detail-fields**: Always include object required fields (like `Name`) in the `--detail-fields` parameter, even if they're also used in `--primary-field` or `--secondary-fields`

**What you get**

• Valid FlexiPage XML with correct structure
• Pre-configured regions and basic components
• Proper field references and facet structure
• Ready to deploy as-is or enhance further

Step 2: Deploy Base Page

Run a **dry-run** deployment to validate the page and dependencies (use the default package directory from `sfdx-project.json`):

sf project deploy start --dry-run -d "<packageDirectory>/main/default" --test-level NoTestRun --wait 10 --json

**Critical:** Fix any deployment errors before proceeding. The page must validate successfully.

Step 3: Add Components Dynamically (if requested)

After the base page deploys successfully, if the user wants additional components, follow the **Adding Components Dynamically** workflow below. All component additions MUST go through the discovery and inference pipeline — never write component XML from memory alone.

---

Critical XML Rules

**Read `references/xml_rules.md`** for all XML encoding rules, field reference format, region/facet types, fieldInstance structure, unique identifier requirements, and common deployment error resolutions.

**Key rules (quick reminder):**

• Encode HTML in `<value>` tags: `&` first, then `<`, `>`, `"`, `'`
• Field references: `Record.{FieldApiName}` (never `Object.Field`)
• Every `<identifier>` and region `<name>` must be unique across the file
• Multiple components in same facet → combine in ONE region with multiple `<itemInstances>`

---

Identifiers, Regions, and Containers

**Read `references/identifiers_and_regions.md`** for the identifier generation algorithm, facet naming patterns (named vs UUID), region selection rules, and container component facet structur