Goal

Generate Salesforce Flow metadata by running the required 3-step MCP pipeline (fetchGroundedObjectMetadata → flowElementSelection → flowElementGeneration) and return the flow XML.

When to Use This Skill

Use this skill when you need to:

• Create any type of Flow (Screen, Autolaunched, Record-Triggered, Scheduled)
• Generate Flow metadata XML
• Automate business processes without code
• Build user-guided workflows or background automation
• Troubleshoot deployment errors related to Flows

Specification

Flow Metadata Specification

Overview

Salesforce Flows are powerful automation tools that enable complex business process automation without code. Flows can collect and process data through interactive screens, execute logic and calculations, manipulate records, call external services, and trigger based on various events. Flow types include Screen Flows (user-guided), Autolaunched Flows (background processing), Record-Triggered Flows (database events) and Scheduled Flows (time-based).

Purpose

• Automate complex business processes with declarative logic and branching
• Guide users through multi-step data collection and decision workflows via Screen Flows
• Perform CRUD operations on Salesforce records automatically
• Execute background processing and integrations via Autolaunched Flows
• React to record changes in real-time with Record-Triggered Flows
• Schedule recurring tasks and batch operations with Scheduled Flows
• Create reusable, maintainable automation that admins can modify without code

Flow Generation Pipeline

MANDATORY: You MUST follow this exact 3-step pipeline. No exceptions. No shortcuts. No skipping steps. Do NOT manually create flow metadata XML or attempt to generate flow metadata outside of this pipeline. Do NOT attempt to use any other tool, API, or method to generate flow metadata. This pipeline is the ONLY supported way to generate flows. Any deviation will produce invalid or broken metadata.

MCP Connection Details

All 3 pipeline steps MUST be called using this MCP tool:

• MCP Tool Name: execute_metadata_action
• The action parameter selects which pipeline step to run: "fetchGroundedObjectMetadata", "flowElementSelection", or "flowElementGeneration"

Flow generation is a strict 3-step pipeline. ALL steps must be called in order. Every step is required. There is no alternative approach — this is the only way to generate flow metadata:

Step 1 (REQUIRED): Fetch Grounded Object Metadata (fetchGroundedObjectMetadata)

Fetches org schema metadata relevant to the flow generation request. This step is mandatory and must always be called first.

Inputs (all required):

• userPrompt (STRING, REQUIRED): The user's natural language request
• inflightMetadata (ARRAY, REQUIRED): Custom objects/fields from local sfdx project. Use empty array [] if none needed.

Outputs:

• groundingMetadata (STRING): Grounded object metadata for org schema relevant to the request, returned as a JSON string. You must pass this directly to Step 2 — it is already a string and does not need to be serialized again.

Step 2 (REQUIRED): Flow Element Selection (flowElementSelection)

Selects flow elements (assignments, decisions, record ops, etc.) and their connections based on the user prompt and grounded metadata. This step is mandatory and must be called after Step 1.

Inputs (all required):

• userPrompt (STRING, REQUIRED): The user's natural language request (must be the same value as Step 1)
• groundingMetadata (STRING, REQUIRED): Org schema metadata (must be the exact string returned from Step 1 output — pass it directly, do NOT serialize it again)
• operationId (STRING, REQUIRED): Operation ID (use empty string "" for first call)

Outputs:

• operationId (STRING): Operation ID. You must pass this to Step 3.
• userOutput (STRING): Reasoning for next steps. You can show this to the user.

Step 3 (REQUIRED): Flow Element Generation (flowElementGeneration)

Generates flow metadata element by element. This step is mandatory and must be called after Step 2. Must be called repeatedly in a loop until isComplete is true.

Inputs (all required):

• operationId (STRING, REQUIRED): Operation ID from Step 2 output
• requestSource (STRING, REQUIRED): The source of the request. Use "A4V" to get flow metadata in XML format.

Outputs:

• isComplete (BOOLEAN): Indicates if the flow generation is complete. You must check this value.
• result (STRING): Result of the flow element generation. Contains the final flow metadata only when isComplete is true.

MANDATORY: Loop until complete. NEVER pause or ask the user to confirm continuation.

• A flow can have any number of elements (10, 15, or more). Each call generates one element at a time, so you may need many iterations. This is expected and normal.
• Call flowElementGeneration with the operationId from Step 2 and requestSource (use "A4V" for XML output, empty string or other value for JSON).
• Check the isComplete output and the result field after each call.
• If isComplete is false and no errors are returned, you MUST call flowElementGeneration again with the same operationId from Step 2. Do NOT ask the user if they want to continue. Do NOT pause. Do NOT summarize progress mid-loop. Just keep calling.
• Do NOT stop until isComplete is true or the invocable action returns errors. There is no maximum number of iterations — keep going regardless of how many calls it takes.
• When isComplete is true, extract the flow metadata from the result field.
• If errors are returned, stop the loop and surface the error to the user.

STRICT CONSTRAINTS (CRITICAL) — These rules apply to the XML returned by the generation pipeline:

• DO NOT modify the content, values, or child nodes inside any block.
• DO NOT add new nodes, tags, attributes, or text (do not add missing labels, X/Y coordinates, etc.).
• DO NOT remove any existing nodes.

inflightMetadata Format

DATA TYPE: ARRAY (not string)

STRICT NAMING CONVENTION - MUST FOLLOW EXACTLY:

When custom objects are needed (sample format showing multiple field data types):

[
  {
    "type": "CustomObject",
    "apiName": "CustomerRequest__c",
    "label": "Customer Request",
    "fields": [
      {
        "apiName": "Status__c",
        "type": "Picklist",
        "label": "Status",
        "values": ["New", "In Progress", "Completed"]
      },
      {
        "apiName": "Priority__c",
        "type": "Number",
        "label": "Priority"
      },
      {
        "apiName": "AssignedTo__c",
        "type": "Lookup",
        "label": "Assigned To",
        "referenceTo": "User"
      },
      {
        "apiName": "Description__c",
        "type": "Textarea",
        "label": "Description"
      },
      {
        "apiName": "Email__c",
        "type": "Email",
        "label": "Contact Email"
      },
      {
        "apiName": "DueDate__c",
        "type": "Date",
        "label": "Due Date"
      },
      {
        "apiName": "IsUrgent__c",
        "type": "Boolean",
        "label": "Is Urgent"
      },
      {
        "apiName": "Amount__c",
        "type": "Currency",
        "label": "Amount"
      }
    ],
    "relationships": []
  }
]

Supported field types: Text, Textarea, Number, Picklist, Lookup, Email, Phone, URL, Date, Datetime, Boolean, Checkbox, Currency, Percent

When no custom objects needed:

[]

MANDATORY Decision Logic for inflightMetadata (DATA TYPE: ARRAY)

1. REQUIRED - First: Scan the local sfdx project for custom objects and fields that are relevant to the user's flow request.
2. If relevant custom objects ARE found: You MUST extract and pass them as an array of structured objects (see format above)
3. If NO relevant custom objects found: You MUST pass an empty array [] (NOT the string "[]")
4. NEVER: Pass text descriptions, instructions, or string representations in inflightMetadata
5. MANDATORY: The data type MUST be ARRAY, not STRING

Instructions for Vibes when custom objects ARE relevant:

• Extract the object metadata and map to JSON properties:
  • apiName: The object's API name (with __c suffix for custom objects)
  • label: The object's display label
  • type: Set to "CustomObject"
  • fields: Array of field objects, each containing:
    • apiName: The field's API name (with __c suffix for custom fields)
    • type: The field type (Text, Number, Picklist, Lookup, etc.)
    • label: The field's display label
    • values: (Picklist only) Array of picklist values
    • referenceTo: (Lookup only) The target object API name
• Include only objects and fields that are relevant to the flow being generated

Mandatory Enhancement Rules

• userPrompt: REQUIRED.
  • If the user requests a single flow: use the user's prompt as-is.
  • If the user requests multiple flows: you MUST split the request and write a separate, focused userPrompt for each individual flow. Each userPrompt must describe only ONE flow. Do NOT pass the entire multi-flow request as a single userPrompt. See the multiple flows section below for examples.
• inflightMetadata: REQUIRED. Always use ARRAY data type.
  • MUST use [] (empty array) when no custom objects needed
  • MUST use structured array of objects when custom objects are relevant
  • NEVER use string "[]" - this is incorrect
  • NEVER use text descriptions - only structured object metadata

MANDATORY: Multiple Flows = Multiple Separate Pipelines

FIRST: Before calling any pipeline step, check if the user's request contains multiple flows. If it does, you MUST split it into separate single-flow prompts. Each flow gets its own 3-step pipeline with its own userPrompt that describes ONLY that one flow.

NEVER pass a multi-flow request as a single userPrompt field. NEVER club multiple flow descriptions into one userPrompt.

When the user requests multiple flows (e.g., "Create flows for my app: 1) ... 2) ... 3) ..."), you MUST:

1. Split the request into separate individual flow descriptions.
2. Run a separate 3-step pipeline for each flow, using a userPrompt that describes ONLY that one flow.
3. Execute ALL pipelines SEQUENTIALLY — one after another, NEVER in parallel. Do NOT stop after the first flow. Do NOT wait for the user to ask you to continue. Do NOT summarize and stop. Keep going until every requested flow has been fully generated.

WRONG - Multiple flows clubbed into one userPrompt:

{
  "userPrompt": "Create flows for the app: 1) Record-Triggered Flow on ResourceAllocation__c to update Resource__c. 2) Screen Flow to allocate resources. 3) Record-Triggered Flow on Supply__c to auto-flag Low_Stock__c.",
  ...
}

CORRECT - Separate call for EACH flow:

Flow 1 - Step 1 (fetchGroundedObjectMetadata):

{
  "userPrompt": "Create a Screen Flow named Tenant_Onboarding that captures tenant details, selects a Unit__c with Status__c = 'Vacant', creates Lease__c...",
  "inflightMetadata": [...]
}

Then call Step 2 (flowElementSelection) with the groundingMetadata from Step 1, then Step 3 (flowElementGeneration) with the operationId from Step 2.

Flow 2 - Step 1 (fetchGroundedObjectMetadata):

{
  "userPrompt": "Create an Autolaunched Flow named Generate_Onboarding_Checklist that given a Lease__c Id input, queries OnboardingTask__c...",
  "inflightMetadata": [...]
}

Then call Step 2 and Step 3 for this flow.

Flow 3 - Step 1 (fetchGroundedObjectMetadata):

{
  "userPrompt": "Create a Record-Triggered Flow named Sync_Unit_On_Lease_Changes that on insert and update of Lease__c...",
  "inflightMetadata": [...]
}

Then call Step 2 and Step 3 for this flow.

Mandatory Rules:

• If there are N flows to generate, there MUST be N separate 3-step pipelines and ALL N pipelines MUST be executed. No exceptions. Do NOT stop after generating only one flow.
• You MUST fully complete the current flow's 3-step pipeline (including looping Step 3 until isComplete is true or errors are returned) BEFORE starting the next flow's pipeline. Do NOT interleave or parallelize pipelines across flows. Everything is SEQUENTIAL — NEVER parallel.
• After completing a flow's pipeline, immediately start the next flow's pipeline. Do NOT pause, summarize, or wait for user confirmation between flows.
• For each flow, you MUST scan the local sfdx project to populate inflightMetadata with custom objects/fields specific to that flow prompt.
• Each flow pipeline MUST have its own inflightMetadata containing only the objects/fields relevant to that particular flow.

Example Tool Calls

Example 1: Standard objects only (no custom objects)

Step 1 - fetchGroundedObjectMetadata:

{
  "userPrompt": "Create a scheduled-triggered Flow named Daily_Good_Morning that runs daily at 6:00 AM and sends an email to the running user saying good morning.",
  "inflightMetadata": []
}

Step 2 - flowElementSelection:

{
  "userPrompt": "Create a scheduled-triggered Flow named Daily_Good_Morning that runs daily at 6:00 AM and sends an email to the running user saying good morning.",
  "groundingMetadata": "<groundingMetadata string from Step 1 — pass directly, do not serialize again>",
  "operationId": ""
}

Step 3 - flowElementGeneration (call in a loop):

{
  "operationId": "<operationId from Step 2>",
  "requestSource": "A4V"
}

Call repeatedly with the same operationId until isComplete is true or errors are returned. A flow can have any number of elements, so expect multiple iterations. When isComplete is true, extract the flow metadata from the result field. Use "requestSource": "A4V" to get flow metadata in XML format.

Example 2: With custom objects from local sfdx project

Step 1 - fetchGroundedObjectMetadata:

{
  "userPrompt": "Create a flow that updates the status of a Customer Request when it's assigned",
  "inflightMetadata": [
    {
      "type": "CustomObject",
      "apiName": "CustomerRequest__c",
      "label": "Customer Request",
      "fields": [
        {
          "apiName": "Status__c",
          "type": "Picklist",
          "label": "Status",
          "values": ["New", "In Progress", "Completed"]
        },
        {
          "apiName": "AssignedTo__c",
          "type": "Lookup",
          "label": "Assigned To",
          "referenceTo": "User"
        }
      ],
      "relationships": []
    }
  ]
}

Step 2 - flowElementSelection:

{
  "userPrompt": "Create a flow that updates the status of a Customer Request when it's assigned",
  "groundingMetadata": "<groundingMetadata string from Step 1 — pass directly, do not serialize again>",
  "operationId": ""
}

Step 3 - flowElementGeneration (call in a loop):

{
  "operationId": "<operationId from Step 2>",
  "requestSource": "A4V"
}

Call repeatedly with the same operationId until isComplete is true or errors are returned. A flow can have any number of elements, so expect multiple iterations. When isComplete is true, extract the flow metadata from the result field. Use "requestSource": "A4V" to get flow metadata in XML format.

Mandatory Best Practices

• ALWAYS follow the 3-step pipeline: fetchGroundedObjectMetadata → flowElementSelection → flowElementGeneration. This is the ONLY way to generate flow metadata. There are no alternatives.
• Do NOT manually create flow metadata XML, JSON, or any other format outside of this pipeline.
• When the user explicitly requests fixes to validation or deployment errors in an already-generated flow XML, you ARE permitted to make targeted manual edits to the XML to resolve those errors. This is the only exception to the "no manual metadata" rule.
• Do NOT attempt to "optimize" by skipping steps or combining steps. Each step is atomic and required.
• NEVER skip any step in the pipeline. All 3 steps are required.
• NEVER try to generate flow metadata without calling all 3 steps.
• NEVER deviate from this pipeline under any circumstance — even if you think you know the flow structure.
• For single flow requests: you MUST use the user prompt as userPrompt.
• For multiple flow requests: you MUST run a separate 3-step pipeline for each flow SEQUENTIALLY (one after another, NEVER in parallel), and you MUST execute ALL of them — do NOT stop after the first flow.
• You MUST put flow requirements in userPrompt, NOT in inflightMetadata.
• inflightMetadata is ONLY for custom object/field metadata from local project (see above). No exceptions.
• Step 3 MUST be called in a loop with the same operationId from Step 2 until isComplete is true or errors are returned. A flow can have any number of elements — do NOT stop early, do NOT pause to ask the user if they want to continue, regardless of how many iterations it takes.
• You MUST only extract the flow metadata from the result field when isComplete is true.

CRITICAL Verification Checklist (MUST VERIFY BEFORE AND AFTER EVERY FLOW GENERATION)

Failure to follow this checklist exactly will result in broken or missing flow metadata.

• Pipeline: ALL 3 steps are called in strict order (fetchGroundedObjectMetadata → flowElementSelection → flowElementGeneration). No step is skipped.
• No manual metadata: Flow metadata is NOT manually created, modified, or generated outside of this pipeline by any means
• No deviation: No alternative tools, APIs, or methods were used instead of or alongside this pipeline
• userPrompt contains a single flow prompt. If user requested multiple flows, the request was split and each pipeline received a separate userPrompt describing only one flow
• userPrompt is passed consistently to both Step 1 and Step 2 (same value)
• inflightMetadata is ARRAY data type (NOT string)
• inflightMetadata is [] when no custom objects needed
• inflightMetadata contains structured objects extracted by scanning the local sfdx project for relevant custom objects/fields
• inflightMetadata does NOT contain "[]" (string) - must be [] (array)
• inflightMetadata does NOT contain text descriptions or instructions
• groundingMetadata from Step 1 output is passed directly to Step 2 input (it is already a string — do NOT serialize it again)
• operationId from Step 2 output is passed to Step 3 input
• requestSource should be set to "A4V" always
• Step 3 is called in a loop with the same operationId from Step 2 until isComplete is true or errors are returned — no pausing, no asking the user to continue, no matter how many iterations
• Multi-flow: Each flow's full pipeline is completed before starting the next flow's pipeline (no interleaving)
• result field is used to extract the XML flow metadata only when isComplete is true
• No additions to XML: NO elements, attributes, or properties were added that were not present in the original pipeline output. Nothing was inserted (no <label>, <description>, or any other node). The final XML must be identical to what the pipeline returned.
• Error fix exception: If the user explicitly requested fixes to validation/deployment errors, targeted manual edits to the XML are permitted and the "No additions to XML" / "No manual metadata" constraints do not apply to those edits.

When to Use This Skill

Use this skill when you need to:

• Integrate all open source B2B Commerce components into a store
• Add open source components to a new or existing B2B Commerce store
• Make open code components available in Experience Builder

Rules

1. Always explain before executing. Before running any command, you MUST tell the user what the command does and why you are running it. Never just show a raw command and ask for permission. The user should be able to read your explanation and understand the purpose before approving.

Overview

This skill copies all open source B2B Commerce components from the official Salesforce repository (https://github.com/forcedotcom/b2b-commerce-open-source-components) into a B2B Commerce store's site metadata. After integration, the components appear in the Experience Builder component palette.

Startup Flow

When this skill is triggered, perform these checks automatically before copying.

Check 0: Resolve Package Directory

Read sfdx-project.json and pick the active package directory. Extract packageDirectories[] and use the entry with "default": true; if no entry is flagged default, use the first entry. Use this value as <package-dir> everywhere below. If sfdx-project.json is missing or has no packageDirectories, tell the user and abort.

Check 1: Open Source Repository

Verify the repo is cloned at .tmp/b2b-commerce-open-source-components:

1. If directory does not exist: Tell user: "I'm cloning the official B2B Commerce open source components repository from GitHub into a local .tmp/ folder. This gives us access to all the open code components." Then run: git clone https://github.com/forcedotcom/b2b-commerce-open-source-components .tmp/b2b-commerce-open-source-components
2. If directory exists and contains force-app/main/default/sfdc_cms__lwc and sfdc_cms__label, present options:

   "Open source repository is already cloned. How would you like to proceed?"

   1. Reuse existing — Use the already cloned repository
   2. Re-clone — Remove and clone fresh from GitHub

3. If directory exists but structure is invalid: Tell user: "The cloned repository has an unexpected structure. I'll remove it and clone a fresh copy." Then remove and re-clone.
4. If clone fails: inform user and abort

Check 2: Store and Site Metadata

Verify a store is selected and site metadata is available locally:

1. Tell user: "I'm checking if your project already has B2B store metadata locally." Check if <package-dir>/main/default/digitalExperiences/site/ contains any store directories.
2. If store metadata exists: use it. If multiple stores found, ask user to select one.
3. If no store metadata found: Try retrieving from the connected org before delegating:
   1. Run sf org list (or check sf config get target-org) to find a connected org. Ask the user to confirm or pick one if more than one.
   2. List DigitalExperienceBundle site bundles in that org with sf org list metadata --metadata-type DigitalExperienceBundle --target-org <alias>. Filter to site/* entries.
   3. If at least one site bundle exists, ask the user which to use, then run: sf project retrieve start --metadata "DigitalExperienceBundle:site/<storeName>" --target-org <alias> The bundle lands at <package-dir>/main/default/digitalExperiences/site/<storeName>/.
   4. Only if no connected org is available, or no site bundles are found, or retrieve fails: delegate to the commerce-b2b-store-create skill.

Required state after all checks:

• Package dir — the value resolved in Check 0 (e.g., force-app)
• Store name — the selected fullName value (e.g., My_B2B_Store1)
• Site metadata path — <package-dir>/main/default/digitalExperiences/site/<store-name>/
• Repo path — .tmp/b2b-commerce-open-source-components/

Integration Task

Copy all components and labels from cloned repo to site directory:

• Source: .tmp/b2b-commerce-open-source-components/force-app/main/default/sfdc_cms__lwc/* and sfdc_cms__label/* (the open source repo's own layout — always force-app)
• Destination: <package-dir>/main/default/digitalExperiences/site/<store-name>/sfdc_cms__lwc/ and sfdc_cms__label/ (<package-dir> resolved in Check 0)

Steps:

1. Tell user: "I'm checking if open code components already exist in your store's site metadata." Check if destination directories already contain files.
2. If files exist, present options:

   "Components already exist in {store-name}. How would you like to proceed?"

   1. Overwrite all — Replace all existing components with latest from repo
   2. Copy only new — Skip existing components, copy only ones not yet present

3. Tell user: "I'm now copying all open code LWC components from the cloned repository into your store's site metadata directory." Copy all component directories from source to destination.
4. Tell user: "I'm copying the associated label files that these components need." Copy all label directories from source to destination.
5. Report: "Copied X components and Y label sets"

Output:

✅ Integration Complete!

Copied: X components and Y label sets to <store-name>

Next Steps:
1. Deploy: sf project deploy start -d <package-dir>/main/default/digitalExperiences/site/<store-name>
2. Open Experience Builder and use new components from the palette
3. Publish your site when ready

Example Interaction

User: "Integrate open code components to my store"

Agent: "I'm checking if the open source components repository is already cloned locally..."

Agent: (repo exists)

"Open source repository is already cloned. How would you like to proceed?"

1. Reuse existing — Use the already cloned repository
2. Re-clone — Remove and clone fresh from GitHub

User: "1"

Agent: "I'm checking if your project already has B2B store metadata locally..."

• ✓ Found store metadata for My_B2B_Store1

Agent: "I'm checking if open code components already exist in your store's site metadata..."

Agent: (files exist)

"Components already exist in My_B2B_Store1. How would you like to proceed?"

1. Overwrite all — Replace all existing components with latest from repo
2. Copy only new — Skip existing components, copy only ones not yet present

User: "1"

Agent: "I'm now copying all open code LWC components from the cloned repository into your store's site metadata directory..." Agent: "I'm copying the associated label files that these components need..."

• ✓ Copied 45 components and 38 label sets

✅ Integration Complete!

Copied: 45 components and 38 label sets to My_B2B_Store1

Next Steps:
1. Deploy: sf project deploy start -d force-app/main/default/digitalExperiences/site/My_B2B_Store1
2. Open Experience Builder and use new components from the palette
3. Publish your site when ready

Error Handling

Verification Checklist

• Startup Flow completed: repo cloned, store metadata available
• Components copied to correct destination path (sfdc_cms__lwc/)
• Labels copied to correct destination path (sfdc_cms__label/)
• No file permission errors during copy
• Deployment command provided and user informed about testing

Commerce B2B Storefront Creation

Interactive workflow to create a Commerce B2B Store in Salesforce and retrieve the auto-generated storefront metadata to your repository.

Critical Concepts

Commerce B2B = Store (backend data) + Storefront (frontend metadata). Store must be created first in the org to auto-generate the Storefront. Never create storefront metadata manually.

See Store vs Storefront Reference

When to Use This Skill

Trigger when users request:

• "Create a B2B Commerce store"
• "Build a Commerce storefront"
• "Set up Commerce B2B"
• "Create B2B Commerce"
• "Retrieve Commerce storefront metadata"
• "Deploy B2B storefront"

Rules That Always Apply

1. Always follow the interactive flow. Do NOT skip steps. Each step requires user confirmation before proceeding.

2. Never create storefront metadata manually. The Commerce setup wizard generates hundreds of configuration values. Manual creation will fail.

3. Always list sites before retrieval. Store names get underscores and number suffixes (e.g., "My B2B Store" → "My_B2B_Store1"). Let the user select from the actual list.

4. Always use --json flag. Include --json on all Salesforce CLI commands for parseable output.

Interactive Workflow: 7 Steps

Step 1: Explain Commerce B2B Concept

Agent explains: Commerce has Store (data) + Storefront (metadata). Store must be created first.

See: Store vs Storefront Reference

Step 2: Guide User to Create B2B Store

Agent provides these steps:

1. Navigate to Setup → Commerce → Stores

   • Or: App Launcher → Commerce → Create Store

2. Click "Create Store" or "Setup New Store"

3. Select "Commerce Store" as the store type

4. Follow the wizard:

   • Store Name: Choose descriptive name (e.g., "My B2B Store")
     • Important: Spaces become underscores in folder names
   • Site URL: Unique URL name for the site

5. Complete wizard - it creates:

   • WebStore record
   • Default buyer group and entitlement policies
   • Associated Digital Experience (LWR site)

6. Optional: Configure payment gateway, tax provider, shipping

Agent then asks: "Have you completed creating the B2B Store in your org? Reply 'yes' when ready and provide the store name you used."

Step 3: Get User Confirmation

Agent waits for: User confirmation and store name

Agent validates: Store name format (no special characters, spaces will appear as underscores)

Agent acknowledges: "Great! Let me list the available storefronts in your org..."

Step 4: List Available LWR Sites

Agent executes:

sf org list metadata --metadata-type DigitalExperienceConfig --json

Agent should:

• Parse JSON output to extract site names
• Display as numbered list
• Explain naming (underscores, number suffixes)

Example output:

Available Digital Experience sites:
1. My_B2B_Store1
2. Partner_Portal
3. Customer_Community

Step 5: Let User Select Storefront

Agent asks: "Which site corresponds to your B2B Store? Select the site name:"

Agent validates: Selection matches available sites

Agent confirms: "Got it! I'll retrieve metadata for [site-name]..."

Step 6: Retrieve Storefront Metadata

Agent executes:

sf project retrieve start -m DigitalExperienceBundle:site/<selected-store-name> --json

Agent should:

• Show retrieval progress
• Confirm successful retrieval
• List retrieved directory structure

Expected output:

Retrieved: force-app/main/default/digitalExperiences/site/My_B2B_Store1/
├── My_B2B_Store1.digitalExperience-meta.xml
├── sfdc_cms__view/ (home, current_cart, detail_*, list_*, etc.)
├── sfdc_cms__site/
├── sfdc_cms__route/
└── [other sfdc_cms__* directories]

Step 7: Provide Next Steps

Agent provides:

✅ Metadata retrieved successfully!

Next steps:

• Customize with custom LWCs or branding changes
• Deploy: sf project deploy start --source-dir force-app/main/default/digitalExperiences/site/My_B2B_Store1/ --json

Resources: DigitalExperienceBundle Docs, B2B Commerce Guide

Reference

• store-vs-storefront.md - Technical details on Store vs Storefront, source control, and why manual creation fails

Remember

Store first (creates storefront) → Retrieve → Customize

data360-activate: Data Cloud Act Phase

Use this skill when the user needs downstream delivery work: activations, activation targets, data actions, or pushing Data Cloud outputs into other systems.

When This Skill Owns the Task

Use data360-activate when the work involves:

• sf data360 activation *
• sf data360 activation-target *
• sf data360 data-action *
• sf data360 data-action-target *
• verifying downstream delivery setup

Delegate elsewhere when the user is:

• still building the audience or insight → data360-segment
• exploring query/search or search indexes → data360-query
• setting up base connections or ingestion → data360-connect, data360-prepare

Required Context to Gather First

Ask for or infer:

• target org alias
• destination platform or downstream system
• whether the segment already exists and is published
• whether the user needs create, inspect, update, or delete
• whether the task is activation-focused or data-action-focused

Core Operating Rules

• Verify the upstream segment or insight is healthy before creating downstream delivery assets.
• Run the shared readiness classifier before mutating activation assets: node ../data360-orchestrate/scripts/diagnose-org.mjs -o <org> --phase act --json.
• Inspect available platforms and targets before mutating activation setup.
• Keep destination definitions deterministic and reusable where possible.
• Treat downstream credential and platform constraints as separate validation concerns.
• Prefer read-only inspection first when the destination state is unclear.

Recommended Workflow

1. Classify readiness for act work

node ../data360-orchestrate/scripts/diagnose-org.mjs -o <org> --phase act --json

2. Inspect destinations first

sf data360 activation platforms -o <org> 2>/dev/null
sf data360 activation-target list -o <org> 2>/dev/null
sf data360 data-action-target list -o <org> 2>/dev/null

3. Create the destination before the activation

sf data360 activation-target create -o <org> -f target.json 2>/dev/null
sf data360 data-action-target create -o <org> -f target.json 2>/dev/null

4. Create the activation or data action

sf data360 activation create -o <org> -f activation.json 2>/dev/null
sf data360 data-action create -o <org> -f action.json 2>/dev/null

5. Verify downstream readiness

sf data360 activation list -o <org> 2>/dev/null
sf data360 activation data -o <org> --name <activation> 2>/dev/null

High-Signal Gotchas

• Activation design depends on a healthy published upstream segment.
• Destination configuration usually comes before activation creation.
• Downstream credential and platform constraints may live outside the Data Cloud CLI alone.
• Read-only inspection is the safest first move when the destination setup is unclear.
• CdpActivationTarget or CdpActivationExternalPlatform means the activation surface is gated for the current org/user; guide the user toward activation setup, permissions, and destination configuration instead of retrying blindly.

Output Format

Act task: <activation / activation-target / data-action / data-action-target>
Destination: <platform or target>
Target org: <alias>
Artifacts: <definition files / commands>
Verification: <listed / created / blocked>
Next step: <destination validation or downstream testing>

References

• README.md
• ../data360-orchestrate/assets/definitions/activation-target.template.json
• ../data360-orchestrate/assets/definitions/activation.template.json
• ../data360-orchestrate/assets/definitions/data-action-target.template.json
• ../data360-orchestrate/assets/definitions/data-action.template.json
• ../data360-orchestrate/UPSTREAM.md
• ../data360-orchestrate/references/plugin-setup.md
• ../data360-orchestrate/references/feature-readiness.md

data360-code-extension-generate Skill

Overview

This skill provides a complete workflow for developing, testing, and deploying custom Python code extensions to Salesforce Data Cloud. Code extensions allow you to write Python transformations that read from and write to Data Lake Objects (DLOs) and Data Model Objects (DMOs).

When to Use

• User wants to create a new code extension project
• User needs to test a code extension locally
• User wants to scan code for required permissions
• User needs to deploy a code extension to Data Cloud
• User is working with Data Cloud transformations
• User wants to read/write DLO or DMO data programmatically

Prerequisites Check

Before executing any code extension commands, verify prerequisites:

1. SF CLI with plugin installed

   sf plugins --core | grep data-code-extension
   

   If not installed:

   sf plugins install @salesforce/plugin-data-codeextension
   

2. Python 3.11

   python --version  # Should show 3.11.x
   

3. Data Cloud Custom Code SDK

   pip list | grep salesforce-data-customcode
   

   If not installed:

   pip install salesforce-data-customcode
   

4. Docker running (for deploy only)

   docker ps
   

5. Authenticated org

   sf org display --target-org <org_alias> --json
   

Skill Workflow

Phase 1: Initialize Project

Create a new code extension project with scaffolding.

Commands:

For script-based code extensions (batch transformations):

sf data-code-extension script init --package-dir <directory>

For function-based code extensions (real-time):

sf data-code-extension function init --package-dir <directory>

Required Option:

• --package-dir, -p - Directory path where the package will be created

What it creates:

my-transform/              # Project root
├── payload/               # CRITICAL: This is what --package-dir must point to for deploy
│   ├── entrypoint.py      # Main transformation code
│   └── config.json        # Code extension configuration
├── requirements.txt       # Python dependencies
└── README.md

Directory Context During Workflow

IMPORTANT: Understanding the directory structure is critical for successful deployment.

Commands and their directory requirements:

CRITICAL: The --package-dir argument in deploy command MUST point to the payload directory, not the project root.

Phase 2: Develop Transformation

Edit payload/entrypoint.py with transformation logic.

Script Example (Batch):

from datacustomcode import Client

client = Client()

# Read from DLO
df = client.read_dlo('Employee__dll')

# Transform data (uppercase position field)
df['position_upper'] = df['position'].str.upper()

# Write to output DLO
client.write_to_dlo('Employee_Upper__dll', df, 'overwrite')

Function Example (Real-time):

from datacustomcode import FunctionClient

def transform(event, context):
    client = FunctionClient(context)
    input_data = event['data']
    output = {
        'name': input_data['name'].upper(),
        'status': 'processed'
    }
    return output

Common Operations:

• client.read_dlo('DLO_Name__dll') - Read from DLO
• client.read_dmo('DMO_Name') - Read from DMO
• client.write_to_dlo('DLO_Name__dll', df, 'overwrite') - Write to DLO
• client.write_to_dmo('DMO_Name', df, 'upsert') - Write to DMO

Phase 3: Scan for Permissions

Scan the entrypoint file to detect required permissions and generate config.json.

Command:

sf data-code-extension script scan --entrypoint ./payload/entrypoint.py

What it detects:

• Read permissions for DLOs/DMOs
• Write permissions for DLOs/DMOs
• Python package dependencies
• Updates config.json and requirements.txt

Phase 4: Validate DLO Schema (Pre-Test Check)

CRITICAL: Before running tests locally, validate that all DLOs used in your code exist and have the expected fields.

Step 4a: Extract DLOs from config.json

After scanning, review the generated config.json to identify all DLOs:

cat payload/config.json

Step 4b: Validate Each DLO Schema

Use the data360-schema-get skill to verify DLOs exist and check field names.

For each DLO referenced in your code:

1. Verify DLO exists:

   python3 scripts/get_dlo_schema.py <org_alias> <dlo_name>
   

2. Verify field names match — compare fields used in your entrypoint.py against the DLO schema.

3. Check all DLOs:

   • Validate all DLOs in read permissions
   • Validate all DLOs in write permissions
   • Check field names match exactly (case-sensitive)
   • Verify data types are compatible with operations

Step 4c: Validation Checklist

Before proceeding to run, ensure:

• All DLOs in config.json exist in target org
• All field names used in code exist in DLO schemas
• Field data types match your transformation logic
• Primary key fields are correctly identified
• Write target DLOs are created and accessible

Phase 5: Test Locally

After validating DLO schemas, run the code extension locally against your Data Cloud org.

Command:

sf data-code-extension script run --entrypoint <entrypoint_file> --target-org <org_alias> [options]

Options:

• --target-org, -o - SF CLI org alias (required)
• --config-file, -c - Custom config file path

If you get errors:

• Re-validate DLO schemas
• Check field names are exact matches
• Verify data types are compatible
• Review error messages for field/DLO issues

Phase 6: Deploy to Data Cloud

Deploy the code extension to Data Cloud for scheduled or on-demand execution.

CRITICAL: You MUST specify --package-dir ./payload to point to the payload directory created by init.

Command:

sf data-code-extension script deploy --target-org <org_alias> --name <name> --package-dir ./payload --package-version <version> --description <description> [options]

Required Options:

• --target-org, -o - SF CLI org alias
• --name, -n - Name for code extension deployment
• --package-dir - Path to payload directory (REQUIRED - must be ./payload when running from project root)
• --package-version - Version string (default: 0.0.1)
• --description - Description of code extension

Optional Options:

• --cpu-size - CPU size: CPU_L, CPU_XL, CPU_2XL (default), CPU_4XL
• --function-invoke-opt - Function invoke options (for function type)
• --network - Docker network (default: default)

After deployment:

• Navigate to Data Cloud in Salesforce UI
• Go to Data Transforms section
• Find your deployment by name
• Click "Run Now" to execute
• Schedule for recurring execution

Error Handling

Common Issues and Solutions

Best Practices

Development

1. Always scan before testing — run scan after code changes
2. Test locally first — use run command before deploying
3. Use version control — git commit after each successful test
4. Version your deployments — use semantic versioning (1.0.0, 1.1.0, etc.)
5. Deploy from project root with --package-dir ./payload

Performance

• CPU_L: Small datasets (< 1M records)
• CPU_2XL: Medium datasets (1M-10M records)
• CPU_4XL: Large datasets (> 10M records)

Security

1. No hardcoded credentials — use SF CLI authentication only
2. Validate input data — check for nulls and data types
3. Limit write permissions — only grant necessary DLO/DMO access

Integration with Other Skills

Use with data360-schema-get skill (CRITICAL for validation):

The data360-schema-get skill is required for validating DLOs before testing code extensions.

Use with Datakit Workflow:

1. Create DLO via code extension
2. Map DLO to DMO using datakit workflow
3. Use DMO in segments and activations

Command Reference

Resources

• SF CLI Plugin: https://github.com/salesforcecli/plugin-data-code-extension
• Python SDK: https://github.com/forcedotcom/datacloud-customcode-python-sdk
• Data Cloud Docs: https://help.salesforce.com/s/articleView?id=sf.c360_a_intro.htm
• Python SDK PyPI: https://pypi.org/project/salesforce-data-customcode/

Notes

• Code extensions run in isolated Python 3.11 environment
• Docker is required only for deployment, not for local testing
• Use SF CLI authentication only (no separate credential files)
• Scan command auto-detects permissions from code
• Local run uses actual Data Cloud data (not mocked)
• Deployments are versioned and can be rolled back in UI

data360-prepare: Data Cloud Prepare Phase

Use this skill when the user needs ingestion and lake preparation work: data streams, Data Lake Objects (DLOs), transforms, Document AI, unstructured ingestion, or the handoff from connector setup into a live stream.

When This Skill Owns the Task

Use data360-prepare when the work involves:

• sf data360 data-stream *
• sf data360 dlo *
• sf data360 transform *
• sf data360 docai *
• choosing how data should enter Data Cloud
• rerunning or rescanning ingestion after a source update
• preparing Ingestion API-backed streams after connector setup is complete

Delegate elsewhere when the user is:

• still creating/testing source connections → data360-connect
• mapping to DMOs or designing IR/data graphs → data360-harmonize
• querying ingested data → data360-query

Required Context to Gather First

Ask for or infer:

• target org alias
• source connection name
• source object / dataset / document source
• desired stream type
• DLO naming expectations
• whether the user is creating, updating, running, or deleting a stream
• whether the source is CRM, a database connector, an unstructured file source, or an Ingestion API feed

Core Operating Rules

• Verify the external plugin runtime before running Data Cloud commands.
• Run the shared readiness classifier before mutating ingestion assets: node ../data360-orchestrate/scripts/diagnose-org.mjs -o <org> --phase prepare --json.
• Prefer inspecting existing streams and DLOs before creating new ingestion assets.
• Suppress linked-plugin warning noise with 2>/dev/null for normal usage.
• Treat DLO naming and field naming as Data Cloud-specific, not CRM-native.
• Confirm whether each dataset should be treated as Profile, Engagement, or Other before creating the stream.
• Distinguish stream-level refresh from connection-level reruns when working with unstructured sources.
• Use UI setup intentionally when initial stream or unstructured asset creation is platform-gated.
• Hand off to Harmonize only after ingestion assets are clearly healthy.

Recommended Workflow

1. Classify readiness for prepare work

node ../data360-orchestrate/scripts/diagnose-org.mjs -o <org> --phase prepare --json

2. Inspect existing ingestion assets

sf data360 data-stream list -o <org> 2>/dev/null
sf data360 dlo list -o <org> 2>/dev/null

3. Confirm the stream category before creation

Use these rules when suggesting categories:

When the source is ambiguous, ask the user explicitly whether the dataset should be treated as Profile, Engagement, or Other.

4. Create or inspect streams intentionally

sf data360 data-stream get -o <org> --name <stream> 2>/dev/null
sf data360 data-stream create-from-object -o <org> --object Contact --connection SalesforceDotCom_Home 2>/dev/null
sf data360 data-stream create -o <org> -f stream.json 2>/dev/null
sf data360 data-stream run -o <org> --name <stream> 2>/dev/null

5. Check DLO shape

sf data360 dlo get -o <org> --name Contact_Home__dll 2>/dev/null

6. Choose the right refresh mechanism

Use the smaller refresh scope that matches the user goal:

sf data360 data-stream run -o <org> --name <stream> 2>/dev/null
sf data360 connection run-existing -o <org> --name <connection-id> 2>/dev/null

• data-stream run is the closest match to a stream-level refresh or re-scan.
• connection run-existing runs at the connection level and can be useful for some connector workflows, but it is not a reliable replacement for stream refresh on unstructured sources.
• For unstructured document connectors, prefer data-stream run when the goal is to re-scan newly added or changed files.

7. Handle unstructured sources deliberately

For SharePoint-style document ingestion, a minimal unstructured DLO payload can look like:

{
  "name": "my_udlo",
  "label": "My UDLO",
  "category": "Directory_Table",
  "dataSource": {
    "sourceType": "SF_DRIVE",
    "directoryAndFilesDetails": [
      {
        "dirName": "SPUnstructuredDocument/<CONNECTION_ID>/<SITE_ID>",
        "fileName": "*"
      }
    ],
    "sourceConfig": {
      "reservedPrefix": "$dcf_content$"
    }
  }
}

Use the UI for the first-time unstructured setup when the user needs the richer end-to-end pipeline. The UI path can seed additional document metadata fields and downstream assets that a bare CLI DLO create flow may not provision automatically.

8. Use the local Ingestion API example for send-data workflows

For external systems pushing records into Data Cloud:

1. create the connector in data360-connect
2. upload the schema with sf data360 connection schema-upsert
3. create the stream in the UI when required
4. send records with the local example in examples/ingestion-api/

cd examples/ingestion-api
cp .env.example .env
python3 send-data.py

Key details:

• auth is a staged flow: JWT → Salesforce token → Data Cloud token
• the ingestion endpoint uses the tenant URL, not the Salesforce instance URL
• 202 means the payload was accepted for processing, not that records are queryable immediately
• validation failures often surface in the Problem Records DLO family

9. Only then move into harmonization

Once the stream and DLO are healthy, hand off to data360-harmonize.

High-Signal Gotchas

• CRM-backed stream behavior is not the same as fully custom connector-framework ingestion.
• sf data360 data-stream run and sf data360 connection run-existing are not interchangeable; prefer stream-level refresh for unstructured rescans.
• SFDC streams sync on a platform-managed schedule; data-stream run is not the general control path for CRM connector refresh.
• Some external database connectors can be created via API while stream creation still requires UI flow or org-specific browser automation. Do not promise a pure CLI stream-creation path for every connector type.
• Initial SharePoint-style unstructured setup can be richer in the UI than in a minimal CLI DLO create flow.
• Stream deletion can also delete the associated DLO unless the delete mode says otherwise.
• DLO field naming differs from CRM field naming, including __c → _c transformations.
• Query DLO record counts with Data Cloud SQL instead of assuming list output is sufficient.
• CdpDataStreams means the stream module is gated for the current org/user; guide the user to provisioning/permissions review instead of retrying blindly.

Output Format

Prepare task: <stream / dlo / transform / docai>
Source: <connection + object>
Target org: <alias>
Artifacts: <stream names / dlo names / json definitions>
Verification: <passed / partial / blocked>
Next step: <harmonize or retrieve>

References

• README.md
• examples/ingestion-api/README.md
• ../data360-orchestrate/assets/definitions/data-stream.template.json
• ../data360-orchestrate/references/plugin-setup.md
• ../data360-orchestrate/references/feature-readiness.md

data360-schema-get Skill

Overview

This skill retrieves Data Lake Object (DLO) and Data Model Object (DMO) schema information from Salesforce Data Cloud using the SSOT REST API. It can list all DLOs or DMOs in an org, or retrieve detailed schema for a specific DLO or DMO.

When to Use

• User wants to see all DLOs or DMOs in a Data Cloud org
• User needs field schema for a specific DLO or DMO
• User is exploring Data Cloud data structures
• User needs to understand DLO or DMO field types and metadata

Prerequisites

• SF CLI installed and authenticated to target org
• Org has Data Cloud enabled
• User has appropriate Data Cloud permissions

Skill Execution

Parameters

1. org_alias (required): The SF CLI org alias (e.g., 'afvibe', 'myorg')
2. dlo_name (optional): Specific DLO developer name (e.g., 'Employee__dll')
3. dmo_name (optional): Specific DMO developer name (e.g., 'Individual__dlm')

Step 1: Discover Connected Org

First, run sf org list to find out which org is connected and extract the alias to use for all subsequent calls:

sf org list

Example output:

┌────┬───────┬──────────────────────────┬────────────────────┬───────────┐
│    │ Alias │ Username                 │ Org Id             │ Status    │
├────┼───────┼──────────────────────────┼────────────────────┼───────────┤
│ 🍁 │ myorg │ chandresh@afvidedemo.org │ 00DKZ00000b80NT2AY │ Connected │
└────┴───────┴──────────────────────────┴────────────────────┴───────────┘

Extract the Alias value (e.g., myorg) from the output and use it as the <org_alias> for all subsequent calls. Use --all to see expired and deleted scratch orgs as well.

Step 2: Validate SF CLI Authentication

Before making API calls, verify the org is connected:

sf org display --target-org <org_alias> --json

If not connected, inform user to run:

sf org login web --alias <org_alias>

Step 3a: Execute DLO Schema Script

The Python scripts are bundled with this skill in the scripts/ subdirectory.

To list all DLOs:

python3 ./scripts/get_dlo_schema.py <org_alias>

To get specific DLO schema:

python3 ./scripts/get_dlo_schema.py <org_alias> <dlo_name>

Step 3b: Execute DMO Schema Script

To list all DMOs:

python3 ./scripts/get_dmo_schema.py <org_alias>

To get specific DMO schema:

python3 ./scripts/get_dmo_schema.py <org_alias> <dmo_name>

Step 4: Present Results

Parse and present the results in a user-friendly format:

For DLO List:

• Show DLO name, label, category, and ID
• Indicate total count
• Highlight DLOs with data (totalRecords > 0)

For DLO Schema:

• Show basic info (name, label, category, status)
• List all fields with:
  • Field name
  • Data type
  • Primary key indicator
  • Nullable status
• Highlight custom fields (exclude system fields like DataSource__c, cdp_sys_*)
• Show record count if available

For DMO List:

• Show DMO name, label, category, and ID
• Indicate total count

For DMO Schema:

• Show basic info (name, label, category, description)
• List all fields with:
  • Field name
  • Data type
  • Primary key indicator
  • Nullable status
• Show dataspace information if available

Step 5: Offer Next Steps

After displaying results, suggest relevant follow-up actions:

• Query data from the DLO
• Create calculated insights
• Build segments
• Set up data streams
• Create DMO mappings

API Endpoints Used

List All DLOs

GET /services/data/v64.0/ssot/data-lake-objects

Response structure:

{
  "dataLakeObjects": [
    {
      "name": "Employee__dll",
      "label": "Employee",
      "category": "Profile",
      "id": "1dlXXXXXXXXXXXXXXX",
      "status": "ACTIVE",
      "totalRecords": 12,
      "fields": [...]
    }
  ],
  "totalSize": 5
}

Get DLO Schema

GET /services/data/v64.0/ssot/data-lake-objects/{dlo_name}

Response structure (same as individual object in list response, but wrapped in paginated format).

List All DMOs

GET /services/data/v64.0/ssot/data-model-objects

Response structure:

{
  "dataModelObjects": [
    {
      "name": "Individual__dlm",
      "label": "Individual",
      "category": "Profile",
      "id": "0dmXXXXXXXXXXXXXXX",
      "fields": [...]
    }
  ],
  "totalSize": 10
}

Get DMO Schema

GET /services/data/v64.0/ssot/data-model-objects/{dmo_name}

Response structure (same as individual object in list response, but wrapped in paginated format).

Error Handling

Common Issues:

1. Org not connected

   • Message: "Org not connected"
   • Solution: Ask user to authenticate via SF CLI

2. DLO not found

   • Message: "DLO 'XYZ__dll' not found"
   • Solution: List all DLOs first to verify name

3. DMO not found

   • Message: "DMO 'XYZ__dlm' not found"
   • Solution: List all DMOs first to verify name

4. Permission issues

   • Message: HTTP 403 errors
   • Solution: Verify user has Data Cloud permissions

5. API version mismatch

   • Current: v64.0
   • Solution: Script can be updated for newer API versions

Example Usage

Example 1: List all DLOs

User: "Show me all DLOs in afvibe org"

Response:
1. Run sf org list to discover connected org alias
2. Authenticate to afvibe
3. Run: python3 ./scripts/get_dlo_schema.py afvibe
4. Display formatted list of DLOs

Example 2: Get specific DLO schema

User: "Get the schema for Employee__dll in afvibe"

Response:
1. Run sf org list to discover connected org alias
2. Authenticate to afvibe
3. Run: python3 ./scripts/get_dlo_schema.py afvibe Employee__dll
4. Display field schema with types and metadata

Example 3: Explore DLOs then get schema

User: "What DLOs exist in myorg and show me the schema for the Employee one"

Response:
1. Run sf org list to discover connected org alias
2. List all DLOs in myorg
3. Identify Employee__dll
4. Get detailed schema for Employee__dll
5. Present both results

Example 4: List all DMOs

User: "Show me all DMOs in afvibe org"

Response:
1. Run sf org list to discover connected org alias
2. Authenticate to afvibe
3. Run: python3 ./scripts/get_dmo_schema.py afvibe
4. Display formatted list of DMOs

Example 5: Get specific DMO schema

User: "Get the schema for Individual__dlm in afvibe"

Response:
1. Run sf org list to discover connected org alias
2. Authenticate to afvibe
3. Run: python3 ./scripts/get_dmo_schema.py afvibe Individual__dlm
4. Display field schema with types and metadata

Example 6: Explore DMOs then get schema

User: "What DMOs exist in myorg and show me the schema for the Individual one"

Response:
1. Run sf org list to discover connected org alias
2. List all DMOs in myorg
3. Identify Individual__dlm
4. Get detailed schema for Individual__dlm
5. Present both results

Output Format

DLO List Output

Found 5 DLOs in org 'afvibe':

1. DataCustomCodeLogs__dll
   Label: DataCustomCodeLogs
   Category: Engagement
   Records: 233

2. Employee__dll
   Label: Employee
   Category: Profile
   Records: 12

[...]

DLO Schema Output

DLO: Employee__dll
Label: Employee
Category: Profile
Status: ACTIVE
Records: 12

Custom Fields:
  • id__c (Text) - Primary Key
  • name__c (Text)
  • position__c (Text)
  • manager_id__c (Number)

System Fields:
  • DataSource__c (Text)
  • InternalOrganization__c (Text)
  • cdp_sys_SourceVersion__c (Text)

Next steps:
- Query data: SELECT * FROM Employee__dll LIMIT 10
- Create segment based on position field
- Set up data stream for real-time updates

DMO List Output

Found 10 DMOs in org 'afvibe':

1. Individual__dlm
   Label: Individual
   Category: Profile

2. ContactPointEmail__dlm
   Label: Contact Point Email
   Category: Profile

[...]

DMO Schema Output

DMO: Individual__dlm
Label: Individual
Category: Profile
Description: Represents an individual person

Fields:
  • Id__c (Text) - Primary Key
  • FirstName__c (Text)
  • LastName__c (Text)
  • BirthDate__c (DateTime)

Next steps:
- Query data: SELECT * FROM Individual__dlm LIMIT 10
- View DLO mappings to this DMO
- Create calculated insights

Notes

• DLO names always end with __dll suffix
• DMO names always end with __dlm suffix
• Field names always end with __c suffix
• System fields (DataSource__c, KQ_, cdp_sys_) are automatically added
• Primary key fields are required for DLO and DMO queries
• API supports pagination (limit/offset) for large result sets

Related Skills

• datakit_workflow: For DMO mapping operations
• datakit_validation: For validating datakit configurations
• Use this skill before creating DMO mappings to understand source DLO structure

Applying SLDS

The Salesforce Lightning Design System (SLDS) is a CSS framework with thousands of artifacts. This skill teaches agents how to find and correctly use them.

Version: This skill targets SLDS v2. Legacy --lwc-* tokens and slds-*--modifier syntax are deprecated.

Audit scope: The companion design-systems-slds-validate skill analyzer only scans .css, .html, and .js files. Use it directly for LWC and similar HTML/CSS/JS components; treat it as a partial signal for JSX/TSX or other framework-specific template formats and supplement with manual review.

What is SLDS?

Scope

This skill covers:

• Which blueprint to use for a given UI pattern
• How to style with hooks (color, spacing, typography, shadows, borders)
• Which utility classes to use for layout, spacing, visibility
• Which icon to use and from which category
• SLDS naming conventions, class structure, hook syntax

This skill includes basic accessibility reminders (icon alt text, focus outlines, color-not-sole-indicator) in the validation checklists. Full WCAG compliance requires a dedicated accessibility review.

This skill does NOT cover (use companion skills):

• Design decisions -- visual hierarchy, composition, interaction patterns
• LWC mechanics -- component structure, @wire, @api, lifecycle, events (not yet available)
• Full accessibility -- WCAG conformance, ARIA patterns, keyboard navigation, focus management, contrast ratios (not yet available)

Component Selection Hierarchy

Always follow this order:

1. Lightning Base Components (LWC only)    ← Check first
2. SLDS Blueprints (any framework)         ← Use exact SLDS classes
3. Custom with Styling Hooks               ← Use var(--slds-g-*)
4. Custom CSS (last resort)                ← Still use hooks for values

If building in LWC, check for an LBC first: Lightning Component Library

If no LBC exists (or not using LWC), select an SLDS Blueprint. See references/component-selection.md.

Core Rules

Do

• Follow the selection hierarchy: LBC > Blueprint > Hooks > Custom CSS
• Use var(--slds-g-*, fallback) for all themeable values
• Create custom classes (my-*, c-*) instead of overriding .slds-*
• Verify every hook, class, and utility exists before using it — run the search scripts; never assume an artifact exists based on naming patterns (see Verify Before You Use)
• Pair surface colors with on-surface colors for text
• Provide alternative-text on every <lightning-icon>

Don't

• Hard-code colors, spacing, or typography values
• Override .slds-* classes directly
• Use deprecated --lwc-* tokens as primary values
• Use --slds-s-* (shared) hooks -- they are private/internal
• Reassign hook values -- only reference them with var()
• Use color alone to convey meaning
• Invent hook names by interpolating patterns from other families (see Naming Traps below)

Hook Naming Traps

SLDS hook families do NOT all follow the same naming pattern. Agents frequently invent hooks that don't exist by assuming {prefix}-{number} works universally. Always verify a hook exists via the bundled search-hooks.cjs script or assets/hooks-index.json before using it.

Trap 1: Font size hooks are NOT numbered

Rule: For font sizes, use --slds-g-font-size-base (the one base size) or --slds-g-font-scale-* (the numbered scale). Never --slds-g-font-size-N.

Trap 2: Color hooks always require a number

Rule: Every --slds-g-color-* hook ends in a number. Pick by emphasis: -1 (low), -2 (medium), -3 (high).

Trap 3: Not all values have hook equivalents

Some CSS values (e.g., min-width: 7rem for label alignment) have no SLDS hook. This is acceptable:

.c-field-label {
  /* No SLDS hook exists for this width; intentional custom value */
  min-width: 7rem;
}

Rule: When no hook exists, use the value directly with a comment explaining it's intentional. Prefer SLDS grid utilities (slds-size_*) as alternatives to hardcoded widths where possible.

Verify Before You Use

Rule: Never include an SLDS hook, utility class, blueprint class, or icon in generated code without first confirming it exists in the metadata. Guessing based on naming patterns is the primary source of invented artifacts.

Run the appropriate search command before emitting any SLDS artifact:

If the search returns no match: do not use the artifact. Find an alternative from the search results or build custom with verified hooks.

Naming Conventions

Use a consistent prefix for custom classes to avoid collision with SLDS:

Avoid: generic names (container, wrapper), SLDS-like names (custom-slds-button), BEM on SLDS classes (slds-card__custom-header).

Custom hook namespacing:

:root {
  --my-app-primary: var(--slds-g-color-accent-1);
  --my-app-card-padding: var(--slds-g-spacing-4);
}

Knowledge Map

This skill bundles comprehensive SLDS knowledge. Read files as needed -- don't read everything upfront.

Decision Guides (start here for each task)

Search Scripts (find specific artifacts)

Deep-Dive Guidance (read for detailed rules)

Raw Metadata (structured data for lookup)

Do not read metadata JSON files directly — they are too large for agent context (hooks-index.json is 6,000+ lines; icon-metadata.json is 38,000+ lines). Use the search scripts above to query them.

Authoring Workflow

Phase 1: Understand the Need

Identify:

• What UI pattern is needed? (form, table, modal, card, etc.)
• What framework? (LWC, React, Vue, Angular, vanilla)
• What data will it display?
• What states does it need? (loading, empty, error, success)

Phase 2: Select the Artifact

1. If LWC: Check the Lightning Component Library for an LBC
2. Search blueprints: node scripts/search-blueprints.cjs --search "<pattern>"
3. Read the blueprint YAML: assets/blueprints/components/<name>.yaml for exact classes, modifiers, states, and accessibility requirements
4. No match? Build custom with hooks (see Phase 3)

Details: references/component-selection.md

Phase 3: Apply Styling

1. Read: references/styling-decision-guide.md
2. Colors: Classify role (surface, accent, feedback, border) then pick hook
3. Spacing: Use utility classes (slds-p-*, slds-m-*) or hooks (--slds-g-spacing-*)
4. Layout: Use grid utilities (slds-grid, slds-col, slds-size_*)
5. Custom CSS: Use var(--slds-g-*, fallback), custom class prefixes only

Phase 4: Add Icons

1. Read: references/icons-decision-guide.md
2. Search: node scripts/search-icons.cjs --query "<description>"
3. In LWC: Use <lightning-icon> with alternative-text
4. In non-LWC: Use SVG with slds-icon classes and slds-assistive-text

Phase 5: Validate (Mandatory — Do Not Skip)

Step 1: Run the SLDS linter. This is required. Zero violations is the target.

npx @salesforce-ux/slds-linter@latest lint <component-path>

The linter catches hardcoded values, class overrides, and deprecated tokens. Fix all violations before proceeding. Do not rationalize violations as acceptable.

Step 2: Verify no invented hooks. Confirm every --slds-g-* hook in the output exists in assets/hooks-index.json. Cross-reference against the T051 check in checklists.md.

Step 3: Run through checklists.md for the checks the linter cannot automate:

• All var(--slds-g-*) have fallback values (T002)
• Surface/accent/feedback color hooks are properly paired (T010–T013)
• Spacing uses hooks or utility classes — no magic px values (T020–T021)
• Font sizes use --slds-g-font-scale-*, not --slds-g-font-size-N (T031)
• All icons have accessibility text (A004)
• Custom classes use my-* or c-* prefix (Q010)

Step 4 (optional): Run the full quality audit using the design-systems-slds-validate skill for a scored report before code review or deployment. Use it directly for LWC / HTML-CSS-JS components; for JSX/TSX outputs, treat the result as partial coverage only. Target a B grade (≥80) or higher before marking work complete.

Quick Reference

Common Hook Patterns

/* Surface + text pairing (always use numbered variants) */
background: var(--slds-g-color-surface-1, #ffffff);
color: var(--slds-g-color-on-surface-2, #181818);

/* Standard padding */
padding: var(--slds-g-spacing-4, 1rem);

/* Card-like container */
border-radius: var(--slds-g-radius-border-2, 0.25rem);
box-shadow: var(--slds-g-shadow-1, 0 2px 4px rgba(0,0,0,0.1));

/* Accent for primary actions */
background: var(--slds-g-color-accent-1, #0176d3);
color: var(--slds-g-color-on-accent-1, #ffffff);

/* Typography -- use font-scale-*, NOT font-size-* (only font-size-base exists) */
font-size: var(--slds-g-font-scale-2, 0.875rem);

Common Utility Patterns

<!-- Responsive grid -->
<div class="slds-grid slds-wrap slds-gutters">
  <div class="slds-col slds-size_1-of-1 slds-medium-size_1-of-2">...</div>
</div>

<!-- Spacing -->
<div class="slds-p-around_medium slds-m-bottom_small">...</div>

<!-- Truncation -->
<p class="slds-truncate" title="Full text here">Full text here</p>

Examples

See examples.md for worked examples demonstrating the full workflow from intent to SLDS artifact selection.

Validation

See checklists.md for validation checklists aligned with the design-systems-slds-validate skill.

Resources

dx-org-permission-set-assign

Assigns one or more permission sets to org users using sf org assign permset. Handles all variants: default admin user, specific org targets, multiple permission sets, and assignment to specific users.

Tool Restrictions

Use ONLY the Bash tool to execute sf org assign permset. Do NOT use MCP tools like assign_permission_set — ignore them completely.

Scope

• In scope: Assigning permission sets to users via sf org assign permset
• Out of scope: Creating permission sets (use platform-permission-set-generate), listing permission sets, checking user permissions

Required Inputs

Infer from the user's request:

• Permission set name(s): Extract from user message (can be multiple)
• Target org: Use default unless specific alias/username mentioned
• Target user(s): Default is org's default admin user; use --on-behalf-of if specific users mentioned

Workflow

1. Match user request to command in table below
2. Execute via Bash tool: sf org assign permset with appropriate flags and --json flag
3. Return result

If error occurs, check the failures array in JSON output for details.

Command Decision Table

Rules / Constraints

Gotchas

Output Expectations

The command returns JSON output with status code and result details.

See examples/success_output.json and examples/error_output.json for response structures.

Reference File Index

Steps

1. Identify the org: the user provides a username or alias (orgIdentifier). If not provided, run sf org list to show authenticated orgs and ask the user which one to use.
2. Set the default org:
   • Local (default): sf config set target-org <orgIdentifier>
     • Applies only within the current project directory. Use this for normal project work.
   • Global (only if user explicitly requests): sf config set target-org <orgIdentifier> --global
     • Applies system-wide across all directories. Use when working outside a project or when the user asks for global scope.
   • If this fails, report the error and suggest running sf org login web if the org may not be authorized.
3. Verify:
   • sf config get target-org --json
   • Note: the JSON output does not include a scope/location field — it cannot confirm whether the value is local or global. Confirm the value only, e.g.: target-org is now set to: <value>
   • If it fails, report the error and advise running sf config get target-org.

Notes

• Unified CLI uses keys like target-org and target-dev-hub. Legacy sfdx keys (defaultusername, defaultdevhubusername) are deprecated in this context.
• The sf CLI does not have --local or --scope flags for config set. Local scope is the default behavior.
• If the org does not change after setting the config, check whether SF_TARGET_ORG is set — environment variables override config values.
• Salesforce CLI config (unified) reference: https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_config_commands_unified.htm#cli_reference_config_set_unified

experience-lwc-generate: Lightning Web Components Development

Use this skill when the user needs Lightning Web Components: LWC bundles, wire patterns, Apex/GraphQL integration, SLDS 2 styling, accessibility, performance work, or Jest unit tests.

When This Skill Owns the Task

Use experience-lwc-generate when the work involves:

• lwc/**/*.js, .html, .css, .js-meta.xml
• component scaffolding and bundle design
• wire service, Apex integration, GraphQL integration
• SLDS 2, dark mode, and accessibility work
• Jest unit tests for LWC

Delegate elsewhere when the user is:

• writing Apex controllers or business logic first → platform-apex-generate
• building Flow XML rather than an LWC screen component → automation-flow-generate
• deploying metadata → platform-metadata-deploy

Required Context to Gather First

Ask for or infer:

• component purpose and target surface
• data source: LDS, Apex, GraphQL, LMS, or external system via Apex
• whether the user needs tests
• whether the component must run in Flow, App Builder, Experience Cloud, or dashboard contexts
• accessibility and styling expectations

Recommended Workflow

1. Choose the right architecture

Use the PICKLES mindset:

• prototype
• integrate the right data source
• compose component boundaries
• define interaction model
• use platform libraries
• optimize execution
• enforce security

2. Choose the right data access pattern

3. Start from an asset when useful

Use provided assets for:

• basic component bundles
• datatables
• modal patterns
• Flow screen components
• GraphQL components
• LMS message channels
• Jest tests
• TypeScript-enabled components

4. Validate for frontend quality

Check:

• accessibility
• SLDS 2 / dark mode compliance
• event contracts
• performance / rerender safety
• Jest coverage when required

5. Hand off supporting backend or deploy work

Use:

• platform-apex-generate for controllers / services
• platform-metadata-deploy for deployment
• platform-apex-test-run only for Apex-side test loops, not Jest

High-Signal Rules

• prefer platform base components over reinventing controls
• use @wire for reactive read-only use cases; imperative calls for explicit actions and DML paths
• do not introduce inaccessible custom UI
• avoid hardcoded colors; use SLDS 2-compatible styling hooks / variables
• avoid rerender loops in renderedCallback()
• keep component communication patterns explicit and minimal

Output Format

When finishing, report in this order:

1. Component(s) created or updated
2. Data access pattern chosen
3. Files changed
4. Accessibility / styling / testing notes
5. Next implementation or deploy step

Suggested shape:

LWC work: <summary>
Pattern: <wire / apex / graphql / lms / flow-screen>
Files: <paths>
Quality: <a11y, SLDS2, dark mode, Jest>
Next step: <deploy, add controller, or run tests>

Local Development Server

Preview LWC components locally with hot reload — no deployment needed. Run the commands in scripts/local-dev-preview.sh to start a local dev session for a component, app, or Experience Cloud site.

Local Dev commands install just-in-time on first run. They are long-running processes that open a browser with live preview. Changes to .js, .html, and .css files auto-reload instantly. Requires an active org connection for data and Apex callouts.

Cross-Skill Integration

Reference File Index

Start here

• references/component-patterns.md — component architecture patterns and bundle design
• references/slds-design-guide.md — SLDS 2 styling, dark mode, CSS hooks
• references/lwc-best-practices.md — high-signal rules and anti-patterns
• references/scoring-and-testing.md — 165-point scoring rubric across 8 categories
• references/jest-testing.md — Jest unit test patterns and async rendering helpers
• references/slds-blueprints.json — machine-readable SLDS component blueprints
• references/cli-commands.md — SF CLI commands for LWC development

Accessibility / performance / state

• references/accessibility-guide.md — WCAG, ARIA, keyboard navigation patterns
• references/performance-guide.md — lazy loading, debouncing, rerender safety
• references/state-management.md — reactive state patterns and LMS
• references/template-anti-patterns.md — common HTML template mistakes to avoid

Integration / advanced features

• references/lms-guide.md — Lightning Message Service patterns
• references/flow-integration-guide.md — Flow screen component design
• references/advanced-features.md — Spring '26 features: TypeScript, lwc:on, GraphQL mutations
• references/async-notification-patterns.md — toast, notifications, async flows
• references/triangle-pattern.md — parent-child-sibling communication triangle

Asset templates

• assets/basic-component/basicComponent.js — wire service, error/loading states, event dispatching
• assets/datatable-component/datatableComponent.js — datatable with inline editing
• assets/flow-screen-component/flowScreenComponent.js — Flow screen with input/output properties
• assets/form-component/formComponent.js — form validation and DML patterns
• assets/graphql-component/graphqlComponent.js — GraphQL wire adapter with cursor-based pagination
• assets/jest-test/componentName.test.js.example — Jest test template (copy and rename, remove .example suffix)
• assets/message-channel/lmsPublisher.js — LMS publisher pattern
• assets/message-channel/lmsSubscriber.js — LMS subscriber pattern
• assets/modal-component/modalComponent.js — modal with focus trap and ESC handling
• assets/record-picker/recordPicker.js — record picker with search
• assets/state-store/store.js — reactive state store for cross-component state
• assets/typescript-component/typescriptComponent.ts — TypeScript-enabled component (Spring '26)
• assets/workspace-api/workspaceComponent.js — workspace API for tab and focus management
• assets/apex-controller/LwcController.cls — Apex controller with @AuraEnabled(cacheable=true) patterns

Scripts

• scripts/local-dev-preview.sh — local dev server commands for component, app, and site preview

Score Guide

UI Bundle Features

Installing Pre-built Features

Always check for an existing feature before building something from scratch. The features CLI installs pre-built, tested packages into Salesforce UI bundles — from foundational UI libraries (shadcn/ui) to full-stack capabilities (authentication, search, navigation, GraphQL, Agentforce AI).

Workflow

1. Search project code first — check src/ for existing implementations before installing anything. Scope searches to src/ to avoid matching node_modules/ or dist/.

2. Search available features — use npx @salesforce/ui-bundle-features list with --search <query> to filter by keyword. Use --verbose for full descriptions.

3. Describe a feature — use npx @salesforce/ui-bundle-features describe <feature> to see components, dependencies, copy operations, and example files.

4. Install — use npx @salesforce/ui-bundle-features install <feature> --ui-bundle-dir <name>. Key options:

   • --dry-run to preview changes
   • --yes for non-interactive mode (skips conflicts)
   • --on-conflict error to detect conflicts, then --conflict-resolution <file> to resolve them

If no matching feature is found, ask the user before building a custom implementation — a relevant feature may exist under a different name.

Conflict Handling

In non-interactive environments, use the two-pass approach: first run with --on-conflict error to detect conflicts, then create a resolution JSON file ({ "path": "skip" | "overwrite" }) and re-run with --conflict-resolution.

Post-install: Integrating Example Files

Features may include __example__ files showing integration patterns. For each:

1. Read the example file to understand the pattern
2. Read the target file (shown in describe output)
3. Apply the pattern from the example into the target
4. Delete the example file after successful integration

Hint Placeholders

Some copy paths use <descriptive-name> placeholders (e.g., <desired-page-with-search-input>) that the CLI does not resolve. After installation, rename or relocate these files to the intended target, or integrate their patterns into an existing file.

File Upload API (workflow)

When the user wants file upload functionality in a React UI bundle, follow this workflow. This feature provides APIs only — you must build the UI components yourself using the provided APIs.

CRITICAL: This is an API-only package

The package exports programmatic APIs, not React components or hooks. You will:

• Use the upload() function to handle file uploads with progress tracking
• Build your own custom UI (file input, dropzone, progress bars, etc.)
• Track upload progress through the onProgress callback

Do NOT:

• Expect pre-built components like <FileUpload /> — they are not exported
• Try to import React hooks like useFileUpload — they are not exported
• Look for dropzone components — they are not exported

The source code contains reference components for demonstration, but they are not available as imports. Use them as examples to build your own UI.

1. Install the package

npm install @salesforce/ui-bundle-template-feature-react-file-upload

Dependencies are automatically installed:

• @salesforce/ui-bundle (API client)
• @salesforce/platform-sdk (data SDK; the old @salesforce/sdk-data name is dead — see the experience-ui-bundle-salesforce-data-access skill)

2. Understand the three upload patterns

Pattern A: Basic upload (no record linking)

Upload files to Salesforce and get back contentBodyId for each file. No ContentVersion record is created.

When to use:

• User wants to upload files first, then create/link them to a record later
• Building a multi-step form where the record doesn't exist yet
• Deferred record linking scenarios

import { upload } from "@salesforce/ui-bundle-template-feature-react-file-upload";

const results = await upload({
  files: [file1, file2],
  onProgress: (progress) => {
    console.log(`${progress.fileName}: ${progress.status} - ${progress.progress}%`);
  },
});

// results[0].contentBodyId: "069..." (always available)
// results[0].contentVersionId: undefined (no record linked)

Pattern B: Upload with immediate record linking

Upload files and immediately link them to an existing Salesforce record by creating ContentVersion records.

When to use:

• Record already exists (Account, Opportunity, Case, etc.)
• User wants files immediately attached to the record
• Direct upload-and-attach scenarios

import { upload } from "@salesforce/ui-bundle-template-feature-react-file-upload";

const results = await upload({
  files: [file1, file2],
  recordId: "001xx000000yyyy", // Existing record ID
  onProgress: (progress) => {
    console.log(`${progress.fileName}: ${progress.status} - ${progress.progress}%`);
  },
});

// results[0].contentBodyId: "069..." (always available)
// results[0].contentVersionId: "068..." (linked to record)

Pattern C: Deferred record linking (record creation flow)

Upload files without a record, then link them after the record is created.

When to use:

• Building a "create record with attachments" form
• Record doesn't exist until form submission
• Need to upload files before knowing the final record ID

import {
  upload,
  createContentVersion,
} from "@salesforce/ui-bundle-template-feature-react-file-upload";

// Step 1: Upload files (no recordId)
const uploadResults = await upload({
  files: [file1, file2],
  onProgress: (progress) => console.log(progress),
});

// Step 2: Create the record
const newRecordId = await createRecord(formData);

// Step 3: Link uploaded files to the new record
for (const file of uploadResults) {
  const contentVersionId = await createContentVersion(
    new File([""], file.fileName),
    file.contentBodyId,
    newRecordId,
  );
}

3. Build your custom UI

The package provides the backend — you build the frontend. Here's a minimal example:

import {
  upload,
  type FileUploadProgress,
} from "@salesforce/ui-bundle-template-feature-react-file-upload";
import { useState } from "react";

function CustomFileUpload({ recordId }: { recordId?: string }) {
  const [progress, setProgress] = useState<Map<string, FileUploadProgress>>(new Map());

  const handleFileSelect = async (event: React.ChangeEvent<HTMLInputElement>) => {
    const files = Array.from(event.target.files || []);

    await upload({
      files,
      recordId,
      onProgress: (fileProgress) => {
        setProgress((prev) => new Map(prev).set(fileProgress.fileName, fileProgress));
      },
    });
  };

  return (
    <div>
      <input type="file" multiple onChange={handleFileSelect} />

      {Array.from(progress.entries()).map(([fileName, fileProgress]) => (
        <div key={fileName}>
          {fileName}: {fileProgress.status} - {fileProgress.progress}%
          {fileProgress.error && <span>Error: {fileProgress.error}</span>}
        </div>
      ))}
    </div>
  );
}

4. Track upload progress

The onProgress callback fires multiple times for each file as it moves through stages:

Always provide visual feedback:

• Show file name
• Display current status
• Render progress bar for "uploading" status
• Show error message if status is "error"

5. Cancel uploads (optional)

Use an AbortController to allow users to cancel uploads:

const abortController = new AbortController();

const handleUpload = async (files: File[]) => {
  try {
    await upload({
      files,
      signal: abortController.signal,
      onProgress: (progress) => console.log(progress),
    });
  } catch (error) {
    console.error("Upload cancelled or failed:", error);
  }
};

const cancelUpload = () => {
  abortController.abort();
};

6. Link to current user (special case)

If the user wants to upload files to their own profile or personal library:

import {
  upload,
  getCurrentUserId,
} from "@salesforce/ui-bundle-template-feature-react-file-upload";

const userId = await getCurrentUserId();
await upload({ files, recordId: userId });

API Reference

upload(options)

Main upload API that handles complete flow with progress tracking.

interface UploadOptions {
  files: File[];
  recordId?: string | null; // If provided, creates ContentVersion
  onProgress?: (progress: FileUploadProgress) => void;
  signal?: AbortSignal; // Optional cancellation
}

interface FileUploadProgress {
  fileName: string;
  status: "pending" | "uploading" | "processing" | "success" | "error";
  progress: number; // 0-100 for uploading, 0 for other states
  error?: string;
}

interface FileUploadResult {
  fileName: string;
  size: number;
  contentBodyId: string; // Always available
  contentVersionId?: string; // Only if recordId was provided
}

Returns: Promise<FileUploadResult[]>

createContentVersion(file, contentBodyId, recordId)

Manually create a ContentVersion record from a previously uploaded file.

async function createContentVersion(
  file: File,
  contentBodyId: string,
  recordId: string,
): Promise<string | undefined>;

Parameters:

• file — File object (used for metadata like name)
• contentBodyId — ContentBody ID from previous upload
• recordId — Record ID for FirstPublishLocationId

Returns: ContentVersion ID if successful

getCurrentUserId()

Get the current user's Salesforce ID.

async function getCurrentUserId(): Promise<string>;

Returns: Current user ID

Common UI patterns

File input with button

<input type="file" multiple accept=".pdf,.doc,.docx,.jpg,.png" onChange={handleFileSelect} />

Drag-and-drop zone

Build your own dropzone using native events:

function DropZone({ onDrop }: { onDrop: (files: File[]) => void }) {
  const handleDrop = (e: React.DragEvent) => {
    e.preventDefault();
    const files = Array.from(e.dataTransfer.files);
    onDrop(files);
  };

  return (
    <div
      onDrop={handleDrop}
      onDragOver={(e) => e.preventDefault()}
      style={{ border: "2px dashed #ccc", padding: "2rem" }}
    >
      Drop files here
    </div>
  );
}

Progress bar

{
  progress.status === "uploading" && (
    <div style={{ width: "100%", background: "#eee" }}>
      <div
        style={{
          width: `${progress.progress}%`,
          background: "#0176d3",
          height: "8px",
        }}
      />
    </div>
  );
}

Decision tree for agents

User asks for file upload functionality:

1. Ask about record context:

   • "Do you want to link uploaded files to a specific record, or upload them first and link later?"

2. Based on response:

   • Link to existing record → Use Pattern B with recordId
   • Upload first, link later → Use Pattern A (no recordId), then Pattern C for linking
   • Link to current user → Use Pattern B with getCurrentUserId()

3. Build the UI:

   • Create file input or dropzone (not provided by package)
   • Add progress display for each file (status + progress bar)
   • Handle errors in the UI

4. Test the implementation:

   • Verify progress callbacks fire correctly
   • Check that contentBodyId is returned
   • If recordId was provided, verify contentVersionId is returned

Reference implementation

The package includes a reference implementation in src/features/fileupload/ with:

• FileUpload.tsx — Complete component with dropzone and dialog
• FileUploadDialog.tsx — Progress tracking dialog
• FileUploadDropZone.tsx — Drag-and-drop zone
• useFileUpload.ts — React hook for state management

These are NOT exported but can be viewed as examples. Read the source files to understand patterns for building your own UI.

Troubleshooting

Upload fails with CORS error:

• Ensure the UI bundle is properly deployed to Salesforce or running on localhost
• Check that the org allows the origin in CORS settings

No progress updates:

• Verify onProgress callback is provided
• Check that the callback function updates React state correctly

ContentVersion not created:

• Verify recordId is provided to upload() function
• Check that the record ID is valid and exists in the org
• Ensure user has permissions to create ContentVersion records

Files upload but don't appear in record:

• Verify recordId is correct
• Check that ContentVersion was created (look for contentVersionId in results)
• Confirm user has access to view files on the record

DO NOT do these things

• ❌ Build XHR/fetch upload logic from scratch — use the upload() API
• ❌ Try to import <FileUpload /> component — it's not exported
• ❌ Try to import useFileUpload hook — it's not exported
• ❌ Use third-party file upload libraries when this feature exists
• ❌ Skip progress tracking — always provide user feedback
• ❌ Ignore errors — always handle and display error messages

UI Bundle Metadata

Scaffolding a New UI Bundle

Use sf template generate ui-bundle to create new apps — not create-react-app, Vite, or other generic scaffolds.

Always pass --template reactbasic to scaffold a React-based bundle.

UI bundle name (-n): Alphanumerical only — no spaces, hyphens, underscores, or special characters.

Example:

sf template generate ui-bundle -n CoffeeBoutique --template reactbasic

After generation:

1. Replace all default boilerplate — "React App", "Vite + React", default <title>, placeholder text
2. Populate the home page with real content (landing section, banners, hero, navigation)
3. Update navigation and placeholders (see the experience-ui-bundle-frontend-generate skill)
4. Configure a hosting target — a UI bundle without a <target> in its meta XML will not be visible in the org. Use experience-ui-bundle-custom-app-generate for internal (App Launcher) apps or experience-ui-bundle-site-generate for external (Experience Site) apps.

Always install dependencies before running any scripts in the UI bundle directory.

UIBundle Bundle

A UIBundle bundle lives under uiBundles/<AppName>/ and must contain:

• <AppName>.uibundle-meta.xml — filename must exactly match the folder name
• A build output directory (default: dist/) with at least one file

Meta XML

Required fields: masterLabel, version (max 20 chars), isActive (boolean). Optional: description (max 255 chars), target.

Target Field

The <target> element specifies where the UI bundle is hosted:

A <target> is required for the app to be accessible in a Salesforce org. A UI bundle deployed without a target will not appear anywhere — no App Launcher entry, no Experience Site URL. Always pair the bundle with one of:

• experience-ui-bundle-site-generate (for Experience target)
• experience-ui-bundle-custom-app-generate (for CustomApplication target)

Example with Experience target:

<?xml version="1.0" encoding="UTF-8"?>
<UIBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <masterLabel>propertyrentalapp</masterLabel>
    <description>A Salesforce UI Bundle.</description>
    <isActive>true</isActive>
    <version>1</version>
    <target>Experience</target>
</UIBundle>

Example with CustomApplication target:

<?xml version="1.0" encoding="UTF-8"?>
<UIBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <masterLabel>propertymanagementapp</masterLabel>
    <description>A Salesforce UI Bundle.</description>
    <isActive>true</isActive>
    <version>1</version>
    <target>CustomApplication</target>
</UIBundle>

ui-bundle.json

Optional file. Allowed top-level keys: outputDir, routing, headers.

Constraints:

• Valid UTF-8 JSON, max 100 KB
• Root must be a non-empty object (never {}, arrays, or primitives)

Path safety (applies to outputDir and routing.fallback): Reject backslashes, leading / or \, .. segments, null/control characters, globs (*, ?, **), and %. All resolved paths must stay within the bundle.

outputDir

Non-empty string referencing a subdirectory (not . or ./). Directory must exist and contain at least one file.

routing

If present, must be a non-empty object. Allowed keys: rewrites, redirects, fallback, trailingSlash, fileBasedRouting.

• trailingSlash: "always", "never", or "auto"
• fileBasedRouting: boolean
• fallback: non-empty string satisfying path safety; target file must exist
• rewrites: non-empty array of { route?, rewrite } objects — e.g., { "route": "/app/:path*", "rewrite": "/index.html" }
• redirects: non-empty array of { route?, redirect, statusCode? } objects — statusCode must be 301, 302, 307, or 308

headers

Non-empty array of { source, headers: [{ key, value }] } objects.

Example:

{
  "routing": {
    "rewrites": [{ "route": "/app/:path*", "rewrite": "/index.html" }],
    "trailingSlash": "never"
  },
  "headers": [
    {
      "source": "/assets/**",
      "headers": [{ "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }]
    }
  ]
}

Never suggest: {} as root, empty "routing": {}, empty arrays, [{}], "outputDir": ".", "outputDir": "./".

CSP Trusted Sites

Salesforce enforces Content Security Policy headers. Any external domain not registered as a CSP Trusted Site will be blocked (images won't load, API calls fail, fonts missing).

When to Create

Whenever the app references a new external domain: CDN images, external fonts, third-party APIs, map tiles, iframes, external stylesheets.

Steps

1. Identify external domains — extract the origin (scheme + host) from each external URL in the code
2. Check existing registrations — look in force-app/main/default/cspTrustedSites/
3. Map resource type to CSP directive:

Always also set isApplicableToConnectSrc to true for preflight/redirect handling.

4. Create the metadata file — follow references/csp-metadata-format.md for the .cspTrustedSite-meta.xml format. Place in force-app/main/default/cspTrustedSites/.

Digital Experience Site for React UI Bundles

Create and configure Digital Experience Sites that host React UI bundles on Salesforce. This skill generates the minimum necessary site infrastructure — Network, CustomSite, DigitalExperienceConfig, DigitalExperienceBundle, and the sfdc_cms__site content type — so a React app can be served from Salesforce.

React sites differ from standard LWR sites: they don't need routes, views, theme layouts, or branding sets. The site acts as a thin container (appContainer: true) that delegates rendering to the React UI bundle referenced by appSpace.

Required Properties

Resolve all five properties before generating any metadata. Each has a fallback chain — work through each option in order until a value is found.

The appNamespace and appDevName properties connect the site to the correct React application. Getting these wrong means the site deploys but shows a blank page, so take care to resolve them from real project data.

Generation Workflow

Step 1: Resolve All Required Properties

Determine values for all five properties before constructing anything. Use the resolution strategies in the table above, falling through each option until a value is found.

Step 2: Create the Project Structure

Use available Salesforce metadata schema and field context for Network, CustomSite, DigitalExperienceConfig, and DigitalExperienceBundle to ensure each file uses valid structure.

Create any files and directories that don't already exist, using these paths:

The DigitalExperience directory contains only _meta.json and content.json. Do not create any directories other than sfdc_cms__site inside the bundle.

Step 3: Populate All Metadata Fields

Use the default templates in the docs below. Values in {braces} are resolved property references — substitute them with the actual values from Step 1.

For URL updates, see update-site-urls.md.

Execution Note for Step 3: Load and use the docs

• Agents MUST read the full contents of each references/*.md file referenced in Step 3 before attempting to populate metadata fields.
• Use your platform's file-read tool (for example, read_file) to load these files in full, then perform placeholder substitution for values in {braces} using the resolved properties from Step 1.
• Files to load:
  • references/configure-metadata-network.md
  • references/configure-metadata-custom-site.md
  • references/configure-metadata-digital-experience-config.md
  • references/configure-metadata-digital-experience-bundle.md
  • references/configure-metadata-digital-experience.md
• Read entire file contents, replace placeholders (e.g. {siteName}) with the resolved values, then use the expanded templates to populate the metadata XML/JSON content.

Step 4: Do Not Modify Non-Templated Properties

Do not modify any default property values for Network, CustomSite, DigitalExperience, DigitalExperienceConfig, or DigitalExperienceBundle metadata that are not expressed as variables wrapped in {braces}.

Verification Checklist

Before deploying, confirm:

• All five required properties are resolved
• All metadata directories and files exist per the project structure
• All metadata fields match the Step 3 templates with {braces} substituted only; no other default property values were added or changed
• appSpace in content.json matches an existing UIBundle metadata record
• Deployment validates successfully:

sf project deploy validate --metadata Network CustomSite DigitalExperienceConfig DigitalExperienceBundle DigitalExperience --target-org ${usernameOrAlias}

Common Workflows

Updating Experience Site URLs

Use when user wants to update or change site URLs (urlPathPrefix).

Steps:

• Read update-site-urls.md to understand the three-component architecture and URL update workflow
• Follow the step-by-step workflow in the doc to update URLs consistently across all three components (DigitalExperienceConfig, Network, CustomSite)

external-diagram-visual-generate: Salesforce Visual AI Skill

Use this skill when the user needs rendered visuals, not text diagrams: ERDs, UI mockups, architecture illustrations, slide-ready images, or image edits using Nano Banana Pro.

Scope

In scope:

• PNG / SVG-style rendered image output
• Visual ERDs and architecture diagrams
• LWC or Experience Cloud mockups / wireframes
• Image edits on previously generated visuals

Out of scope — delegate instead:

• Mermaid or text-only diagrams → external-diagram-mermaid-generate
• Object / field metadata discovery for ERDs → platform-custom-object-generate or platform-custom-field-generate
• LWC implementation after the mockup is approved → experience-lwc-generate
• Apex review / implementation → platform-apex-generate

Hard Gate: Prerequisites First

Run the prerequisites check before using the skill:

scripts/check-prerequisites.sh

If prerequisites fail, stop and route the user to setup guidance in:

• references/gemini-cli-setup.md

Required Inputs

Ask for or infer before generating:

Interview-First Workflow

Unless the user asks for quick / simple / just generate, ask clarifying questions first using the question bank in references/interview-questions.md.

Quick mode defaults (triggered by "quick", "simple", "just generate", "fast"):

• professional style, 1K draft, legend included, one image first then iterate

Recommended Workflow

1. Run prerequisites check

Run scripts/check-prerequisites.sh and confirm all required tools pass before proceeding.

2. Gather inputs

• object list / metadata (delegate to platform-custom-object-generate / platform-custom-field-generate if needed)
• purpose: draft vs presentation vs documentation
• desired aesthetic — read references/architect-aesthetic-guide.md for ERDs
• aspect ratio / resolution

3. Run interview or use quick-mode defaults

Load references/interview-questions.md for the matching question set (ERD, LWC, architecture, code review).

4. Build a concrete prompt

Good prompts specify subject, composition, color treatment, labels/legends, and output quality goal.

5. Generate a fast draft at 1K

gemini --yolo "/generate 'Your prompt here'"

Open the result and review layout before spending on higher resolution.

6. Iterate using edits

gemini --yolo "/edit 'Specific change instruction'"

Use /edit for small adjustments — cheaper than regenerating. See references/iteration-workflow.md.

7. Generate final at 2K/4K using the Python script

Run scripts/generate_image.py when layout is confirmed:

uv run scripts/generate_image.py -p "Refined prompt" -f "output.png" -r 4K

8. Error recovery

• If gemini --yolo returns no image: re-run once; if it fails again, fall back to the Python script path.
• If the Python script fails with GEMINI_API_KEY not found: verify the key is exported in your shell profile (~/.zshrc on macOS/zsh, ~/.bashrc on Linux) and the terminal session is refreshed.
• If the extension is missing: run gemini extensions install nanobanana and re-run the prerequisites check.

Default Style Guidance

For ERDs, default to the architect.salesforce.com aesthetic unless the user asks otherwise:

• dark border + light fill cards
• cloud-specific accent colors
• clean labels and relationship lines
• presentation-ready whitespace and hierarchy

Full style specification: references/architect-aesthetic-guide.md

Common Patterns

Output Expectations

Deliverables produced by this skill:

• Draft image (<name>.png) — 1K resolution rendered via gemini --yolo "/generate ..." for layout review
• Final image (<name>.png) — 2K or 4K resolution rendered via scripts/generate_image.py once composition is approved
• Edit iteration (<name>.png) — incremental refinement via gemini --yolo "/edit ..." without full regeneration

After delivering each image:

• Open the file in Preview or attach it in the session for multimodal review
• Ask the user whether to iterate on layout, labeling, or color before finalizing
• Only proceed to high-res output after draft composition is confirmed

Rules / Constraints

Gotchas

Cross-Skill Integration

Reference File Index

platform-apex-logs-debug: Salesforce Debug Log Analysis & Troubleshooting

Use this skill when the user needs root-cause analysis from debug logs: governor-limit diagnosis, stack-trace interpretation, slow-query investigation, heap / CPU pressure analysis, or a reproduction-to-fix loop based on log evidence.

When This Skill Owns the Task

Use platform-apex-logs-debug when the work involves:

• .log files from Salesforce
• stack traces and exception analysis
• governor limits
• SOQL / DML / CPU / heap troubleshooting
• query-plan or performance evidence extracted from logs

Delegate elsewhere when the user is:

• running or repairing Apex tests → platform-apex-test-run
• generating or implementing the code fix → platform-apex-generate
• debugging Agentforce session traces / parquet telemetry → agentforce-observe

Required Context to Gather First

Ask for or infer:

• org alias
• failing transaction / user flow / test name
• approximate timestamp or transaction window
• user / record / request ID if known
• whether the goal is diagnosis only or diagnosis + fix loop

Recommended Workflow

1. Retrieve logs

Use the commands in references/cli-commands.md to list, download, or stream logs for the target org.

2. Analyze in this order

1. entry point and transaction type
2. exceptions / fatal errors
3. governor limits
4. repeated SOQL / DML patterns
5. CPU / heap hotspots
6. callout timing and external failures

3. Classify severity

• Critical — runtime failure, hard limit, corruption risk
• Warning — near-limit, non-selective query, slow path
• Info — optimization opportunity or hygiene issue

4. Recommend the smallest correct fix

Prefer fixes that are:

• root-cause oriented
• bulk-safe
• testable
• easy to verify with a rerun

Expanded workflow: references/analysis-playbook.md

High-Signal Issue Patterns

Expanded examples: references/common-issues.md

Output Format

When finishing analysis, report in this order:

1. What failed
2. Where it failed (class / method / line / transaction stage)
3. Why it failed (root cause, not just symptom)
4. How severe it is
5. Recommended fix
6. Verification step

Suggested shape:

Issue: <summary>
Location: <class / line / transaction>
Root cause: <explanation>
Severity: Critical | Warning | Info
Fix: <specific action>
Verify: <test or rerun step>

Rules / Constraints

Gotchas

Cross-Skill Integration

Reference File Index

Score Guide

When to Use This Skill

Use this skill when you need to:

• Create Lightning applications
• Organize tabs and features into focused apps
• Configure application navigation and branding
• Set up custom page layouts for objects
• Troubleshoot deployment errors related to custom applications

CustomApplication (Lightning App) Metadata Specification

Overview

Custom applications (Lightning Apps) that group tabs and functionality to provide a focused user experience for specific business processes. Always configured for Lightning Experience.

Purpose

• Organize related functionality into focused applications
• Group tabs and components for specific user roles
• Provide tailored user experiences
• Control access to specific features and data
• Use Standard navigation for general business applications or Console navigation for specialized service/support workflows requiring multi-tab workspaces
• Create professional, branded application identity with custom colors and branding
• Override standard actions with custom Lightning pages for enhanced user experience
• Enable profile-specific experiences through profile action overrides

Required Properties

Core Application Properties

• fullName: API name of the application
• label: Display name of the application
• uiType: Always "Lightning" for modern apps
• navType: CRITICAL - Choose based on user requirements and workflow patterns
  • "Standard": DEFAULT for general business applications (e.g., sales, marketing, operations)
  • "Console": ONLY when workflow requires managing multiple records simultaneously with split-view or multi-tab workspace (e.g., customer service, call centers, support operations)
• formFactors: Array of form factors (["LARGE"] for desktop, ["SMALL"] for mobile, or both)

Optional Properties

• description: Brief description of the application's purpose
• tabs: Array of tab names to include
• utilityBar: API name of the Utility Bar configuration
• brand: ⚠️ HIGHLY RECOMMENDED - Branding configuration object (headerColor, shouldOverrideOrgTheme, footerColor)
• actionOverrides: ⚠️ REQUIRED when custom record pages exist - Action override configuration (actionName, content, formFactor, type, pageOrSobjectType)
• profileActionOverrides: Profile-specific action overrides (actionName, content, formFactor, pageOrSobjectType, type, profile)
• isNavAutoTempTabsDisabled: Navigation behavior setting (default: false)
• isNavPersonalizationDisabled: Personalization setting (default: false)
• isNavTabPersistenceDisabled: Tab persistence setting (default: false)

Application Configuration

Navigation Type Selection (CRITICAL)

Decision Criteria for navType:

Choose "Standard" (DEFAULT) for:

• General business applications and most workflows
• Single-record focus or linear navigation patterns
• Standard tab-based navigation is sufficient

Choose "Console" ONLY when workflow requires:

• Managing multiple related records simultaneously in split-view
• Multi-tab workspace for handling complex, interconnected data
• Contextual information from multiple sources visible at once
• Examples: customer service operations, support desks, call centers

When in doubt: Default to "Standard" for most general business use cases

Navigation Settings

• isNavAutoTempTabsDisabled: Controls automatic temporary tab creation
• isNavPersonalizationDisabled: Controls user personalization features
• isNavTabPersistenceDisabled: Controls tab persistence across sessions

Tab Management

• tabs: Array of tab names to include in the application
• formFactors: Device-specific configurations (Large for desktop, Small for mobile)

Utility Bar

• utilityBar: Reference to Lightning utility bar (appears at bottom of Lightning Experience)

Branding (HIGHLY RECOMMENDED - DO NOT SKIP)

IMPORTANT: Provide branding configuration to create a professional, visually distinct application identity.

• brand.headerColor: Header bar color in hex format (e.g., "#0070D2") - RECOMMENDED
• brand.shouldOverrideOrgTheme: Override organization theme (true/false) - Default: false
• brand.footerColor: Footer color in hex format

Action Overrides (CRITICAL - DO NOT SKIP)

IMPORTANT: Action overrides MUST be created for every custom object tab that has a record page generated by flexipage expert.

• actionOverrides.actionName: Action to override ("View" or "Tab")
• actionOverrides.content: Page/component name (FlexiPage, Visualforce, Lightning component)
  • For "View" action: Reference record pages generated by flexipage expert
  • For "Tab" action: Reference home/app pages generated by flexipage expert
• actionOverrides.formFactor: Device type ("Large" or "Small")
• actionOverrides.type: Override type ("Default", "Visualforce", "Flexipage", "LightningComponent", "Scontrol")
  • Recommended: Use "Flexipage" for Lightning record/home pages generated by flexipage expert
• actionOverrides.pageOrSobjectType: Object API name the override applies to
• actionOverrides.comment: Optional description (max 1000 characters)
  • Auto-generated comment: "Action override created by Lightning App Builder during activation."
• actionOverrides.skipRecordTypeSelect: Skip record type selection (default: false)

Profile Action Overrides

• profileActionOverrides.actionName: Action to override ("View" or "Tab")
• profileActionOverrides.content: Page/component name
  • For "View" action: Reference profile-specific record pages generated by flexipage expert
  • For "Tab" action: Reference profile-specific home pages generated by flexipage expert
  • Can reference same or different FlexiPages than actionOverrides for profile-specific experiences
• profileActionOverrides.formFactor: Device type ("Large" or "Small")
• profileActionOverrides.pageOrSobjectType: Object API name
• profileActionOverrides.type: Override type
  • Recommended: Use "Flexipage" for Lightning pages generated by flexipage expert
• profileActionOverrides.profile: Profile API name (e.g., "Admin", "Standard User")
  • Enables different page layouts for different user profiles

Device Support

Desktop Configuration

• formFactor: "Large"
• tabs: Full list of application tabs

Phone Configuration

• formFactor: "Small"
• tabs: Mobile-optimized tab selection

Tablet Configuration

• formFactor: "Medium"
• tabs: Tablet-appropriate tab selection

User Experience Features

Navigation Behavior

• Auto Temporary Tabs: Can be enabled/disabled
• Personalization: User customization options
• Tab Persistence: Remember user's tab selections

Accessibility

• Keyboard Navigation: Full keyboard support
• Screen Reader: Compatible with assistive technologies
• High Contrast: Support for high contrast modes

Integration Points

• Custom Tabs: Include custom object and web tabs
• Standard Tabs: Include standard Salesforce tabs
• Lightning Pages: Integrate with Lightning page layouts
• Components: Include custom Lightning components

Best Practices

• Always use Lightning UI: Set uiType to "Lightning" for modern apps
• Choose appropriate navigation: CRITICAL - Analyze requirements carefully for navType selection
  • Use "Standard" (DEFAULT) for general business applications
  • Use "Console" ONLY when workflow requires multi-tab workspace, split-view, or managing multiple related records simultaneously
  • Examples for Console: customer service, call centers, support operations
  • Default to "Standard" for most general business use cases
• Include Standard Tabs: Add common Salesforce tabs (Home, Accounts, Contacts, etc.)
• Use clear, descriptive application names
• Group related functionality logically
• Consider different user roles and needs
• Test across different device types
• Ensure proper permissions and access control
• Provide meaningful descriptions for users
• Follow consistent naming conventions
• Always configure branding: Set headerColor to create professional application identity
• Use accessible brand colors: Ensure hex colors have sufficient contrast (WCAG AA compliant)
• Configure utility bars: Add useful quick-access tools for users
• Leverage action overrides: Customize page layouts for specific objects using FlexiPages from flexipage expert
• Use profile overrides: Provide role-specific experiences by referencing different flexipage expert generated pages per profile

Enhancement Rules

• uiType: Always set to "Lightning" for modern app experience
• navType: CRITICAL DECISION - Analyze user requirements carefully
  • Set to "Standard" (DEFAULT) for general business applications
  • Set to "Console" ONLY when workflow requires:
    • Managing multiple related records simultaneously with split-view capability
    • Multi-tab workspace for handling complex, interconnected data
    • Contextual information from multiple sources visible at once
  • Console examples: customer service operations, call centers, support desks
  • When in doubt between Standard and Console, choose "Standard" for most business use cases
• formFactors: Always set to ["LARGE"] for desktop Lightning Experience
• Standard Tabs: Automatically add Home, Accounts, Contacts, Opportunities, Leads, Cases
• Navigation Settings: Set all navigation flags to false for best user experience
• Branding: ALWAYS include brand configuration for professional application identity
  • MANDATORY: Set brand.headerColor to appropriate color (e.g., "#0070D2" for Salesforce Blue)
  • Set brand.shouldOverrideOrgTheme based on requirements
• Action Overrides: ALWAYS create action overrides when custom record pages exist
  • MANDATORY: Add actionOverrides for "View" action pointing to flexipage expert generated record pages
  • Use "Flexipage" type and reference the exact FlexiPage name
  • Set formFactor to "Large" for desktop
  • Include pageOrSobjectType with the object API name
• Profile Action Overrides: Reference flexipage expert generated pages for role-based customization
• Form Factors: Use "Large" for desktop, "Small" for mobile in overrides

CRITICAL Verification Checklist (MUST VERIFY)

• All tabs are included in the application
• navType IS CORRECTLY SET - Verify Console vs Standard selection
• Default to "Standard" for most general business applications
• Set to "Console" ONLY if workflow requires managing multiple records simultaneously, split-view, or multi-tab workspace
• If requirements are general/ambiguous → navType should be "Standard"
• BRANDING IS CONFIGURED - This is HIGHLY RECOMMENDED for professional applications
• brand.headerColor is set with valid hex color (e.g., "#0070D2")
• brand.shouldOverrideOrgTheme is set (default: false)
• ACTION OVERRIDES ARE CREATED - This is MANDATORY for every custom object with a record page
• Action overrides are defined for EACH custom object tab pointing to the correct record page
• actionOverrides.content matches the exact FlexiPage name generated by flexipage expert
• actionOverrides.pageOrSobjectType is set to the correct object API name
• actionOverrides.type is set to "Flexipage"
• actionOverrides.actionName is set to "View"
• actionOverrides.formFactor is set to "Large"
• All required fields are populated (fullName, label, uiType, navType, formFactors)

When to Use This Skill

Use this skill when you need to:

• Create tabs for objects, web pages, or Visualforce pages
• Add navigation tabs to applications
• Configure tab visibility and access
• Troubleshoot deployment errors related to custom tabs

Specification

CustomTab Metadata Specification

Overview

Custom tabs for navigating to objects, web content, or Visualforce pages within Salesforce applications.

Purpose

• Provide navigation to custom objects
• Link to external web content
• Access Visualforce pages
• Organize application navigation

Required Properties

Core Tab Properties

• customObject: true for custom object tabs, false for all others.
• motif: Tab icon style — choose a motif that semantically matches the object's purpose. Do NOT reuse the same motif for every tab.
• label: Display name (required for non-object tabs ONLY; object tabs inherit label from the object)
• url: Web URL (for web tabs)
• page: Visualforce page name (for Visualforce tabs)

STRICT ELEMENT ALLOWLIST — READ THIS FIRST

The root element MUST always be <CustomTab> (NOT <Tab>). The XML namespace must be xmlns="http://soap.sforce.com/2006/04/metadata".

Only the elements listed below are valid. Any element not on this list WILL cause a deployment error.

FORBIDDEN ELEMENTS (every one of these causes a deployment error)

<sobjectName>, <name>, <fullName>, <apiVersion>, <isHidden>, <tabVisibility>, <type>, <mobileReady>, <urlFrameHeight>, <urlType>, <urlRedirect>, <encodingKey>, <height>, <auraComponent>

Also forbidden:

• <label> on object tabs (object tabs inherit their label from the custom object)
• <page> on web tabs (only for Visualforce tabs)
• Empty elements like <page></page> or <description></description>
• Any element not in the allowlist table above

Tab Types

Object Tabs

• Purpose: Navigate to custom or standard objects
• File name determines the object: {ObjectApiName}.tab-meta.xml (e.g., Space_Station__c.tab-meta.xml)
• Required elements: <customObject>true</customObject> and <motif>
• Correct example (for a Space_Station__c.tab-meta.xml):

<?xml version="1.0" encoding="UTF-8"?>
<CustomTab xmlns="http://soap.sforce.com/2006/04/metadata">
    <customObject>true</customObject>
    <motif>Custom39: Telescope</motif>
</CustomTab>

• Correct example (for a Supply__c.tab-meta.xml — note different motif):

<?xml version="1.0" encoding="UTF-8"?>
<CustomTab xmlns="http://soap.sforce.com/2006/04/metadata">
    <customObject>true</customObject>
    <motif>Custom98: Truck</motif>
</CustomTab>

• ❌ WRONG — do NOT add <sobjectName>, <name>, <fullName>, or <label>:

<CustomTab xmlns="http://soap.sforce.com/2006/04/metadata">
    <sobjectName>Space_Station__c</sobjectName>  <!-- DEPLOYMENT ERROR -->
    <label>Space Station</label>                  <!-- DEPLOYMENT ERROR on object tabs -->
    <customObject>true</customObject>
    <motif>Custom57: Desert</motif>
</CustomTab>

Web Tabs

• Purpose: Link to external websites or web applications
• File name: Use a descriptive name: {TabName}.tab-meta.xml (e.g., Knowledge_Base.tab-meta.xml)
• COPY THIS EXACT TEMPLATE — only replace the placeholder values. Do NOT add, remove, or rename any XML elements:

<?xml version="1.0" encoding="UTF-8"?>
<CustomTab xmlns="http://soap.sforce.com/2006/04/metadata">
    <customObject>false</customObject>
    <description>REPLACE_WITH_DESCRIPTION</description>
    <frameHeight>600</frameHeight>
    <label>REPLACE_WITH_LABEL</label>
    <motif>REPLACE_WITH_MOTIF</motif>
    <url>REPLACE_WITH_URL</url>
    <urlEncodingKey>UTF-8</urlEncodingKey>
</CustomTab>

• These 7 elements above are the ONLY elements allowed in a web tab file. Do not add ANY other elements.
• The <description> element is optional — you may remove it if not needed, but do not add anything else.

Visualforce Tabs

• Purpose: Access custom Visualforce pages
• File name: {TabName}.tab-meta.xml (e.g., Custom_Page_Tab.tab-meta.xml)
• Required elements: <customObject>false</customObject>, <label>, <motif>, <page>
• Correct example:

<?xml version="1.0" encoding="UTF-8"?>
<CustomTab xmlns="http://soap.sforce.com/2006/04/metadata">
    <customObject>false</customObject>
    <label>Custom Page</label>
    <motif>Custom46: Computer</motif>
    <page>CustomPage</page>
</CustomTab>

Tab Configuration

Tab Style

• Default: Use standard tab styling
• Custom: Can specify custom tab styles if needed

Tab Visibility

• Default: Visible to all users with access
• Custom: Can be configured for specific user profiles

Supported Applications

• Standard Apps: Available in standard Salesforce applications
• Custom Apps: Can be included in custom applications
• Community Apps: Available in community applications

Integration Points

• Object Relationships: Links to related object records
• Web Content: External website integration
• Visualforce Pages: Custom page functionality
• Lightning Components: Modern component integration

Best Practices

• Use clear, descriptive tab labels
• Choose appropriate tab types for functionality
• Select a unique, contextually relevant motif for each tab — do not default every tab to the same icon
• Consider user experience and navigation flow
• Test tab functionality across different applications
• Ensure proper permissions and visibility settings
• Follow consistent naming conventions
• Object tab files MUST only contain <customObject>true</customObject> and <motif> — nothing else
• Web tab files MUST only contain: <customObject>false</customObject>, <label>, <motif>, <url>, <urlEncodingKey>, and optionally <description>, <frameHeight> — nothing else
• Never include <isHidden>, <tabVisibility>, <type>, <mobileReady>, or empty elements

Generating Lightning App

Overview

Build a complete, deployable Salesforce Lightning Experience application from a natural language description by defining a Lightning Custom Application and orchestrating its dependent metadata types in correct dependency order. Invoke specialized metadata skills when available; generate metadata directly when no skill exists.

When to Use This Skill

Use when:

• User requests a "Lightning app", or "end-to-end solution"
• User says "build an app", "create an application", "build a [type] app" (project management, tracking, etc.)
• The work produces a custom app (CustomApplication) plus supporting metadata, not a lone object, page, or tab in isolation

Examples that should trigger this skill:

• "Build a project management lightning app with Tasks, Resources, and Supplies objects"
• "Create a LEX app to track vehicles with Lightning pages and permission sets"
• "I need a Space Station management system with multiple objects and relationships"
• "Build an employee onboarding lightning app with custom Lightning Record Pages"

Do NOT use when:

• Creating a single metadata component (use specific metadata skill instead)
• Troubleshooting or debugging existing metadata
• Building Salesforce Classic apps (not Lightning Experience)
• User asks for just one object, or just one page, or just one permission set (without others)
• User only needs to create or configure an app container (grouping existing tabs) without other metadata; use platform-custom-application-generate instead

Metadata Type Registry

This table shows which metadata types are commonly needed for Lightning Experience apps, their skill availability, and API context requirement.

Usage Rules

SKILL RULE: When a skill exists for a metadata type, you MUST load that skill. Do NOT generate metadata directly without loading the skill first.

API CONTEXT RULE: For every metadata type (except Flow), you MUST call salesforce-api-context tools before generating. Do NOT generate metadata without calling API context first. The skill provides structure and rules; API context confirms what is valid for the current API version. Both are essential.

FALLBACK RULE: When no skill exists for a metadata type you need, generate the metadata directly using your knowledge of Salesforce Metadata API and best practices. API context is still required.

RATIONALE: Skills contain validated patterns and constraints. API context provides version-specific accuracy. Together they prevent deployment failures.

Dependency Graph & Build Order

Phase 1: Data Model (Foundation)

Custom Objects (no dependencies)
    ↓
Custom Fields (depends on: Objects exist)
    ↓
Relationships (depends on: Both parent and child objects + fields exist)

Metadata types in this phase:

1. platform-custom-object-generate - once, with all objects
2. platform-custom-field-generate - once, with all fields (including Master-Detail, Lookup, Roll-up Summary)

Phase 2: Business Logic (Optional - only if requested)

Validation Rules (depends on: Fields exist)
    ↓
Flows (depends on: Objects, Fields exist)

Metadata types in this phase (only if user requested):

1. platform-validation-rule-generate - once, if validation requirements mentioned
2. automation-flow-generate - once, if automation/workflow requirements mentioned

Phase 3: User Interface

List Views (depends on: Objects, Fields exist)
    ↓
Custom Tabs (depends on: Objects exist)
    ↓
FlexiPages (depends on: Objects, Tabs exist)

Metadata types in this phase:

1. platform-list-view-generate - once, for filtered record views (if requested)
2. platform-custom-tab-generate - once, with all object tabs
3. platform-flexipage-generate - once, with all record/home/app pages

Phase 4: Application Assembly

Custom Application (depends on: Tabs exist)

Metadata types in this phase:

1. platform-custom-application-generate - once, to create the Lightning App container

Phase 5: Security & Access

Permission Sets (depends on: Objects, Fields, Tabs, App exist)

Metadata types in this phase:

1. platform-permission-set-generate - once, with all permission sets and access to:
   • Objects (Read, Create, Edit, Delete)
   • Fields (Read, Edit)
   • Tabs (Visible)
   • Custom Application (Visible)

Execution Workflow

STEP 1: Requirements Analysis & Planning

Actions:

1. Parse user's natural language request
2. Extract business entities (become Custom Objects)
3. Extract attributes/properties (become Custom Fields)
4. Identify relationships (Master-Detail, Lookup)
5. Detect validation requirements (become Validation Rules)
6. Detect automation requirements (become Flows)
7. Identify user personas (inform Permission Sets)

Output: Build Plan

Generate a structured plan listing:

Lightning App Build Plan: [App Name]

DATA MODEL:
- Custom Objects: [list with object names]
- Custom Fields: [list grouped by object]
- Relationships: [list M-D and Lookup relationships]

BUSINESS LOGIC (if applicable):
- Validation Rules: [list with object and rule name]
- Flows: [list with flow name and type]

USER INTERFACE:
- List Views (if requested): [list with object and view name]
- Custom Tabs: [list with object]
- FlexiPages: [list with page name and type]
- Custom Application: [app name]

SECURITY:
- Permission Sets: [list with purpose]

PER-TYPE EXECUTION (skill + API context for each):
- CustomObject: load platform-custom-object-generate + call salesforce-api-context
- CustomField: load platform-custom-field-generate + call salesforce-api-context
- ValidationRule: load platform-validation-rule-generate + call salesforce-api-context (if requested)
- Flow: load automation-flow-generate + run metadata-experts pipeline (if requested)
- ListView: load platform-list-view-generate + call salesforce-api-context (if requested)
- CustomTab: load platform-custom-tab-generate + call salesforce-api-context
- FlexiPage: load platform-flexipage-generate + call salesforce-api-context
- CustomApplication: load platform-custom-application-generate + call salesforce-api-context
- PermissionSet: load platform-permission-set-generate + call salesforce-api-context

STATUS LINES TO EMIT BEFORE FILE WRITES:
- `type=<Type> skill=complete mcp=complete|unavailable mcp_tools=<tool-list|none>`
- Flow exception: `type=Flow skill=complete pipeline=complete`

DEPENDENCY ORDER:
1. Phase 1: Data Model (Objects -> Fields)
2. Phase 2: Business Logic (Validation Rules -> Flows)
3. Phase 3: User Interface (List Views -> Tabs -> Pages)
4. Phase 4: App Assembly (Application)
5. Phase 5: Security (Permission Sets)

STEP 2: Per-Type Execution

Execute these four steps for each metadata type, one type at a time. Complete all four steps for the current type before moving to the next type. Do NOT skip any step.

Do NOT combine ① and ② into a single action or skip ② after completing ①. They are separate steps that serve different purposes. After loading the skill you may feel ready to generate — stop and do ② first.

If salesforce-api-context is unavailable after a real attempt, record mcp=unavailable and generate using skill knowledge alone. Not attempting ② at all is a bug.

1. Custom Objects

• ① Load skill: Read platform-custom-object-generate SKILL.md
• ② API context: Call salesforce-api-context for CustomObject
• ③ Status: type=CustomObject skill=complete mcp=complete|unavailable mcp_tools=<tool-list|none>
• ④ Generate + Checkpoint: Generate all Custom Object files, then proceed to #2

2. Custom Fields

• ① Load skill: Read platform-custom-field-generate SKILL.md
• ② API context: Call salesforce-api-context for CustomField
• ③ Status: type=CustomField skill=complete mcp=complete|unavailable mcp_tools=<tool-list|none>
• ④ Generate + Checkpoint: Generate all Custom Field files, then proceed to #3

3. Validation Rules (only if requested)

• ① Load skill: Read platform-validation-rule-generate SKILL.md
• ② API context: Call salesforce-api-context for ValidationRule
• ③ Status: type=ValidationRule skill=complete mcp=complete|unavailable mcp_tools=<tool-list|none>
• ④ Generate + Checkpoint: Generate all Validation Rule files, then proceed to #4

4. Flows (only if requested)

• ① Load skill: Read automation-flow-generate SKILL.md
• ② Pipeline: Run metadata-experts/execute_metadata_action 3-step pipeline (exempt from salesforce-api-context)
• ③ Status: type=Flow skill=complete pipeline=complete
• ④ Generate + Checkpoint: Generate all Flow files via the pipeline, then proceed to #5

5. List Views (only if requested)

• ① Load skill: Read platform-list-view-generate SKILL.md
• ② API context: Call salesforce-api-context for ListView
• ③ Status: type=ListView skill=complete mcp=complete|unavailable mcp_tools=<tool-list|none>
• ④ Generate + Checkpoint: Generate all List View files, then proceed to #6

6. Custom Tabs

• ① Load skill: Read platform-custom-tab-generate SKILL.md
• ② API context: Call salesforce-api-context for CustomTab
• ③ Status: type=CustomTab skill=complete mcp=complete|unavailable mcp_tools=<tool-list|none>
• ④ Generate + Checkpoint: Generate all Custom Tab files, then proceed to #7

7. FlexiPages

• ① Load skill: Read platform-flexipage-generate SKILL.md
• ② API context: Call salesforce-api-context for FlexiPage
• ③ Status: type=FlexiPage skill=complete mcp=complete|unavailable mcp_tools=<tool-list|none>
• ④ Generate + Checkpoint: Generate all FlexiPage files, then proceed to #8

8. Custom Application

• ① Load skill: Read platform-custom-application-generate SKILL.md
• ② API context: Call salesforce-api-context for CustomApplication
• ③ Status: type=CustomApplication skill=complete mcp=complete|unavailable mcp_tools=<tool-list|none>
• ④ Generate + Checkpoint: Generate the Custom Application file, then proceed to #9

9. Permission Sets

• ① Load skill: Read platform-permission-set-generate SKILL.md
• ② API context: Call salesforce-api-context for PermissionSet
• ③ Status: type=PermissionSet skill=complete mcp=complete|unavailable mcp_tools=<tool-list|none>
• ④ Generate + Checkpoint: Generate all Permission Set files — all types complete

STEP 3: Final Artifact Assembly

After all phases complete, consolidate outputs into deployment-ready structure.

Output

The completed build produces:

1. Salesforce DX Project Directory containing all generated metadata

   • Organized by standard SFDX structure: force-app/main/default/

2. Metadata Files - One file per component, organized by type:

   force-app/main/default/
   ├── objects/              # Custom Objects (.object-meta.xml)
   ├── fields/               # Custom Fields (.field-meta.xml)
   ├── tabs/                 # Custom Tabs (.tab-meta.xml)
   ├── flexipages/           # Lightning Pages (.flexipage-meta.xml)
   ├── applications/         # Custom Applications (.app-meta.xml)
   ├── permissionsets/       # Permission Sets (.permissionset-meta.xml)
   ├── flows/                # Flows (.flow-meta.xml) - if applicable
   └── objects/.../validationRules/  # Validation Rules (.validationRule-meta.xml) - if applicable
   

3. Deployment Manifest (package.xml)

   • Lists all components with proper API version
   • Organized by metadata type in dependency order
   • Ready for Salesforce CLI deployment or Metadata API deployment

4. Build Summary Report - A markdown file listing:

   • Every component created
   • Component type and API name
   • File path location
   • Dependency relationships
   • Any warnings or recommendations

Example Summary Structure:

Lightning App Build Complete: Project Management App

METADATA GENERATED:
1 Custom Objects
   - Project__c -> force-app/main/default/objects/Project__c/Project__c.object-meta.xml
   - Task__c -> force-app/main/default/objects/Task__c/Task__c.object-meta.xml
   - Resource__c -> force-app/main/default/objects/Resource__c/Resource__c.object-meta.xml

2 Custom Fields
   - Project__c.Name -> force-app/main/default/objects/Project__c/fields/Name.field-meta.xml
   - Project__c.Status__c -> force-app/main/default/objects/Project__c/fields/Status__c.field-meta.xml
   [... etc ...]

3 Custom Tabs
   - Project__c -> force-app/main/default/tabs/Project__c.tab-meta.xml
   [... etc ...]

4 Lightning Record Pages
   - Project_Record_Page -> force-app/main/default/flexipages/Project_Record_Page.flexipage-meta.xml
   [... etc ...]

5 Custom Application
   - Project_Management -> force-app/main/default/applications/Project_Management.app-meta.xml

6 Permission Sets
   - Project_Manager -> force-app/main/default/permissionsets/Project_Manager.permissionset-meta.xml
   - Project_User -> force-app/main/default/permissionsets/Project_User.permissionset-meta.xml

WARNINGS: None

Validation

Before presenting the completed build to the user, verify cross-component integrity:

• Object-Tab Coverage: Every Custom Object has at least one Custom Tab
• Relationship Integrity: Every Custom Object referenced in a relationship (parent or child) exists in the build
• Field References in Pages: Every field referenced in a FlexiPage exists on the corresponding object
• Tab References in App: Every tab referenced in the Custom Application was successfully created
• Permission Set Completeness: Permission Sets grant access to all generated objects, fields, tabs, and the application
• No Orphaned Components: No tabs without objects, no pages without corresponding tabs, no app without tabs
• Deployment Manifest Completeness: package.xml includes all generated components in proper dependency order

Validation Failure Handling (Category 2):

• If validation fails, include failed checks in the Build Summary Report under a VALIDATION WARNINGS section
• These are post-generation issues — do NOT block delivery of the build, but clearly communicate what needs manual review or correction
• Provide specific remediation steps for each failed validation check

Note: Individual component validations (reserved words, name lengths, field types, etc.) are handled by specialized metadata skills and do not need to be re-validated here.

Error Handling

Category 1: Stop and Ask User

Stop execution and ask for clarification if:

• User request is too vague to extract any objects or fields
• Conflicting requirements detected (e.g., "make it private" + "everyone should see it")
• Invalid Salesforce naming detected (reserved words like Order, Group)

Category 2: Post-Generation Warnings (Log Warning, Continue)

Log warning and continue if:

• Cross-component validation check fails (e.g., field referenced in FlexiPage doesn't exist on object)
• Optional component generation fails (e.g., List View generation has minor issues)
• Validation Rule or Flow has minor output issues

Warning Pattern:

Warning: [Component Type] generation encountered issue
    Component: [Name]
    Issue: [Description]
    Impact: [What won't work]
    Recommendation: [How to fix manually]
    Continuing with remaining components...

Best Practices

1. Always Follow Dependency Order

Never invoke skills out of sequence. Fields need objects, pages need tabs, apps need tabs.

2. Use Skills When Available

Don't reinvent the wheel. Specialized skills have field-specific validation that prevents deployment errors.

3. Generate Thoughtful Defaults

When user doesn't specify details:

• Use Text name fields for human entities
• Use AutoNumber for transactions
• Enable Search and Reports for user-facing objects
• Set sharingModel based on relationships

4. Validate Before Building

Check for:

• Reserved words in API names
• Relationship limits (max 2 M-D per object)
• Name length limits
• Duplicate names

When to Use This Skill

Use this skill when you need to:

• Create list views for objects
• Generate filtered, column-based record listings
• Configure list view visibility and sharing
• Troubleshoot deployment errors related to List Views

Specification

Salesforce List View Metadata Knowledge

Overview

Salesforce List Views define filtered, column-based record listings on an object's tab.

Purpose

• Provide curated, role- or task-specific subsets of records
• Standardize commonly used filters and visible fields across teams

Configuration

Unless specifically requested to be generated inline, List Views are stored at:

• force-app/main/default/objects/<ObjectName>/listViews/<fullName>.listView-meta.xml Only if the user requests are they to be included in the object's metadata file:
• fore-app/main/default/objects/<ObjectName>/<ObjectName>.object-meta.xml

Key elements:

• label: Human-friendly name shown in UI (must be under 40 characters in length)
• fullName (fullName): API identifier used in metadata and file name
• filterScope: Everything | Mine | Queue
• filters: field/operation/value triples
• booleanFilterLogic: Combine multiple filters logically with AND/OR (e.g., "1 AND (2 OR 3)")
• columns: Ordered list of field API names to display

References:

• listViews appear on the entity's tab
• listViews can be referenced by flexipages using the "filterListCard" component

Critical Decision: Visibility Strategy

Choose how broadly the view should appear in the org.

Choose "Visible to all users" when:

• The view is useful across profiles/roles
• It's a governed, shared artifact to be managed via source control
• Data contained is appropriate for broad visibility

Choose "Owner-only/Restricted" when:

• It is experimental or niche during iteration
• It is specifically requested to be limited to Users, Groups or Roles
• There are governance/security reviews pending

When in doubt: Default to "Visible to all users".

Critical Decision: Columns Density

Choose minimal, high-signal columns when:

• Users need at-a-glance scanning
• Mobile/responsive performance matters

Choose richer column sets when:

• Desktop heavy workflows need more context without opening records
• It serves as a work queue and extra fields reduce clicks

When in doubt: Start with 4–6 columns that directly support the primary task.

Critical Rules (Read First)

Rule 1: Custom Field API Names

For custom fields, use exact API names (e.g., Status__c), not labels.

Wrong:

• Status (label)

Right:

• Status__c (API name)

Rule 2: Standard Field Names

For standard fields on Custom Objects, use already defined names:

Wrong:

• Name (API Name)

Right:

• NAME

The standard fields on Custom Objects are:

• NAME
• RECORDTYPE
• OWNER.ALIAS
• OWNER.FIRST_NAME
• OWNER.LAST_NAME
• CREATEDBY_USER.ALIAS
• CREATEDBY_USER
• CREATED_DATE
• UPDATEDBY_USER.ALIAS
• UPDATEDBY_USER
• LAST_UPDATE
• LAST_ACTIVITY

Rule 3: Operations Must Match Field Types

Picklists require equals/notEqual; date fields require date operators; boolean values are 0 and 1; do not mix text-only operators with non-text fields.

Wrong:

• operation="contains" on a picklist
• value=True on a boolean

Right:

• operation="equals" with a valid picklist value
• value=1 on a boolean

Rule 4: Name and Path Alignment

File name, fullName (also sometimes referred to as DeveloperName), and uniqueness must align.

Wrong:

• File: My_List.listView-meta.xml
• fullName: MyList

Right:

• File: MyList.listView-meta.xml
• fullName: MyList

Rule 5: Folder Placement

Place files under the object's listViews directory or deployments will fail to resolve components. Only if a user requests it, may the listView may be included inline in force-app/main/default/objects/<ObjectName>/<ObjectName>.object-meta.xml

Path:

• force-app/main/default/objects/<ObjectName>/listViews/<fullName>.listView-meta.xml

Generation Workflow

Step 1: Get Metadata Information

• Identify the target object API name (e.g., Object__c).
• Gather business requirements: purpose, audience, fields, filters.
• Validate values and operator compatibility with field types.

Step 2: Examine Existing Examples

• Repo: force-app/main/default/objects/<Object>/listViews/ (unless otherwise required by end user)
• Org: retrieve existing list views for proven patterns (filters, logic, columns).
• Note what passed review/deployment and delivered expected UX.

Step 3: Create Specification

Document before implementation:

• Name: fullName and Label
• Audience: Visibility scope ("all users" vs. shared)
• Filter scope: Everything | Mine | Queue
• Filter items: filter, operator, value; plus booleanFilterLogic if multiple
• Columns: Ordered list of field API names
• Acceptance criteria: Which records appear, paging behavior, key scenarios

Step 4: Author Metadata File

Use a Lightning-compatible template and ensure valid XML:

<?xml version="1.0" encoding="UTF-8"?>
<ListView xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>OpenMine</fullName>
    <label>Open - My Records</label>
    <filterScope>Mine</filterScope>
    <columns>NAME</columns>
    <columns>Status__c</columns>
    <columns>OWNER.ALIAS</columns>
    <columns>LAST_UPDATE</columns>
    <filters>
        <field>Status__c</field>
        <operation>equals</operation>
        <value>Open</value>
    </filters>
    <sharedTo>
        <role>CEO</role>
        <roleAndSubordinatesInternal>COO</roleAndSubordinatesInternal>
    </sharedTo>
</ListView>

Notes:

• For "My" views, use filterScope="Mine".
• Keep columns tight and purposeful.
• If intended for all users, omit the "sharedTo" section.

Step 5: Validate Locally

• Well-formed XML; correct namespace
• Field names exist on the object; operators and values match field types
• Path and fullName alignment
• If multiple filters: set booleanFilterLogic correctly (e.g., "1 AND (2 OR 3)")

Step 6: Deploy and Verify in Org

• Deploy the component path or the whole object.
• In the UI, open the object tab and:
  • Confirm records match filters
  • Confirm columns render correctly
  • Confirm visibility matches audience

Common Deployment Errors

Verification Checklist

• All required fields populated (fullName, label, filterScope, columns)
• Property values are XML-encoded where needed
• Custom Field references use API names (e.g., Status__c)
• Standard Field references use defined names (e.g., NAME)
• Operations match field types; picklist values are valid
• booleanFilterLogic (if used) matches filters ordering and count
• File path and fullName/developerName are aligned
• No deprecated or Classic-only properties included
• Deployed successfully and visible as intended
• Records, columns, and filtering behave as specified

platform-metadata-deploy: Comprehensive Salesforce DevOps Automation

Use this skill when the user needs deployment orchestration: dry-run validation, targeted or manifest-based deploys, CI/CD workflow advice, scratch-org management, failure triage, or safe rollout sequencing for Salesforce metadata.

When This Skill Owns the Task

Use platform-metadata-deploy when the work involves:

• sf project deploy start, quick, report, or retrieval workflows
• release sequencing across objects, permission sets, Apex, and Flows
• CI/CD gates, test-level selection, or deployment reports
• troubleshooting deployment failures and dependency ordering

Delegate elsewhere when the user is:

• authoring Apex code → platform-apex-generate
• authoring LWC components → experience-lwc-generate
• creating custom objects or fields → platform-custom-object-generate, platform-custom-field-generate
• building Flows → automation-flow-generate
• doing org data operations → platform-data-manage
• authoring or testing Agentforce agents → agentforce-generate

Critical Operating Rules

• Use sf CLI v2 only.
• On non-source-tracking orgs, deploy/retrieve commands require an explicit scope such as --source-dir, --metadata, or --manifest.
• Prefer --dry-run first before real deploys.
• For Flows, deploy safely and activate only after validation.
• Keep test-data creation guidance delegated to platform-data-manage after metadata is validated or deployed.

Default deployment order

This ordering prevents many dependency and FLS failures.

Required Context to Gather First

Ask for or infer:

• target org alias and environment type
• deployment scope: source-dir, metadata list, or manifest
• whether this is validate-only, deploy, quick deploy, retrieve, or CI/CD guidance
• required test level and rollback expectations
• whether special metadata types are involved (Flow, permission sets, agents, packages)

Preflight checks:

sf --version
sf org list
sf org display --target-org <alias> --json
test -f sfdx-project.json

Recommended Workflow

1. Preflight

Confirm auth, repo shape, package directories, and target scope.

2. Validate first

sf project deploy start --dry-run --source-dir force-app --target-org <alias> --wait 30 --json

Use manifest- or metadata-scoped validation when the change set is targeted.

3. If validation succeeds, offer the next safe workflow

After a successful validation, guide the user to the correct next action:

1. deploy now
2. assign permission sets
3. create test data via platform-data-manage
4. run tests / smoke checks
5. orchestrate multiple post-deploy steps in order

4. Deploy the smallest correct scope

# source-dir deploy
sf project deploy start --source-dir force-app --target-org <alias> --wait 30 --json

# manifest deploy
sf project deploy start --manifest manifest/package.xml --target-org <alias> --test-level RunLocalTests --wait 30 --json

# manifest deploy with Spring '26 relevant-test selection
sf project deploy start --manifest manifest/package.xml --target-org <alias> --test-level RunRelevantTests --wait 30 --json

# quick deploy after successful validation
sf project deploy quick --job-id <validation-job-id> --target-org <alias> --json

5. Verify

sf project deploy report --job-id <job-id> --target-org <alias> --json

Then verify tests, Flow state, permission assignments, and smoke-test behavior.

6. Report clearly

Summarize what deployed, what failed, what was skipped, and what the next safe action is.

Output template: references/deployment-report-template.md

High-Signal Failure Patterns

Full workflows: references/orchestration.md, references/trigger-deployment-safety.md

CI/CD Guidance

Default pipeline shape:

1. authenticate
2. validate repo / org state
3. static analysis
4. dry-run deploy
5. tests + coverage gates
6. deploy
7. verify + notify

• When org policy and release risk allow it, consider --test-level RunRelevantTests for Apex-heavy deployments.
• Pair this with modern Apex test annotations such as @IsTest(testFor=...) and @IsTest(isCritical=true) — see platform-apex-generate for authoring guidance.

Static analysis now uses Code Analyzer v5 (sf code-analyzer), not retired sf scanner.

Deep reference: references/deployment-workflows.md

Agentforce Deployment Note

Use this skill to orchestrate deployment/publish sequencing around agents, but use the agent-specific skill for authoring decisions:

• agentforce-generate for .agent authoring, Agent Builder, Prompt Builder, and metadata config

For full agent DevOps details, including Agent: pseudo metadata, publish/activate, and sync-between-orgs, see:

• references/agent-deployment-guide.md

Cross-Skill Integration

Reference Map

Start here

• references/orchestration.md
• references/deployment-workflows.md
• references/deployment-report-template.md

Specialized deployment safety

• references/trigger-deployment-safety.md
• references/agent-deployment-guide.md
• references/deploy.sh

Asset templates

• assets/package.xml — manifest template covering common metadata types
• assets/destructiveChanges.xml — template for removing metadata from target orgs

Score Guide

Completion Format

Deployment goal: <validate / deploy / retrieve / pipeline>
Target org: <alias>
Scope: <source-dir / metadata / manifest>
Result: <passed / failed / partial>
Key findings: <errors, ordering, tests, skipped items>
Next step: <safe follow-up action>

When to Use This Skill

Use when generating or editing permission set metadata, or when granting object, field, user, and app permissions.

Step 1: Define Core Properties

Start by defining the required permission set properties:

<PermissionSet xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>YourPermissionSetName</fullName>
    <label>Display Name for Administrators</label>
    <description>Clear description of purpose and intended audience</description>
</PermissionSet>

Naming conventions:

• Use descriptive API names (e.g., Sales_Manager_Access)

Step 2: Configure Object Permissions

Add CRUD permissions for standard and custom objects:

<objectPermissions>
    <allowCreate>true</allowCreate>
    <allowRead>true</allowRead>
    <allowEdit>true</allowEdit>
    <allowDelete>false</allowDelete>
    <modifyAllRecords>false</modifyAllRecords>
    <viewAllRecords>false</viewAllRecords>
    <viewAllFields>false</viewAllFields>
    <object>Account</object>
</objectPermissions>

Step 3: Set Field-Level Security

Define field permissions for sensitive or custom fields:

<fieldPermissions>
    <editable>true</editable>
    <readable>true</readable>
    <field>Account.SSN__c</field>
</fieldPermissions>

Important:

• Required fields must NEVER appear in list of field permissions. Granting field-level security on required fields is not allowed by the platform and will cause deployment failure.
• Before adding any field, confirm from the object metadata that the field exists and is not required
• A field is required when its metadata contains <required>true</required>:
• Formula fields cannot be editable
• Master-detail fields are required fields on the child (detail) object

<fields>
    <fullName>FieldName__c</fullName>
    <required>true</required>
</fields>

• Use format ObjectName.FieldName for field references
• Set both readable and editable to true when the user needs edit access; editable implies readable
• If all fields should be visible, can alternatively enable the "viewAllFields" object permission

Step 4: Grant User Permissions

Add system-level permissions for features and capabilities:

<userPermissions>
    <enabled>true</enabled>
    <name>ApiEnabled</name>
</userPermissions>
<userPermissions>
    <enabled>true</enabled>
    <name>RunReports</name>
</userPermissions>

Common permissions:

• ApiEnabled: API access
• ViewSetup: View Setup menu
• ManageUsers: User management
• RunReports: Report execution

Security review required for:

• ViewAllData: Read all records
• ModifyAllData: Edit all records
• ManageUsers: User administration

Step 5: Configure App and Tab Visibility

Make applications and tabs visible to users:

<applicationVisibilities>
    <application>Sales_Console</application>
    <visible>true</visible>
</applicationVisibilities>
<tabSettings>
    <tab>CustomTab__c</tab>
    <visibility>Visible</visibility>
</tabSettings>

Application visibility options:

• can be true or false

Tab visibility options:

• Visible: The tab is available on the All Tabs page and appears in the visible tabs for its associated app. Can be customized.
• Available: The tab is available on the All Tabs page. Individual users can customize their display to make the tab visible in any app
• None: Not visible

CRITICAL - Tab Naming:

• Custom object tabs: MUST include the __c suffix (e.g., MyCustomObject__c)
• Standard object tabs: Use the object name with "standard-" prefix (e.g., standard-Account, standard-Contact)
• The tab name matches the object's API name exactly

Step 6: Add Apex and Visualforce Access (Optional)

Grant access to custom code:

<classAccesses>
    <apexClass>CustomController</apexClass>
    <enabled>true</enabled>
</classAccesses>
<pageAccesses>
    <apexPage>CustomPage</apexPage>
    <enabled>true</enabled>
</pageAccesses>

Step 7: Set License and Record Type Settings (Optional)

Specify license requirements and record type visibility:

<license>Salesforce</license>
<hasActivationRequired>false</hasActivationRequired>
<recordTypeVisibilities>
    <recordType>Account.Business</recordType>
    <visible>true</visible>
    <default>true</default>
</recordTypeVisibilities>

Step 8: Set Agent Access (Optional)

Enable access to Agentforce Employee Agents for users assigned to this permission set:

Field requirements:

• agentName (Required): The developer name of the employee agent
• enabled (Required): Set to true to grant access, false to deny

Important:

• Agent names must match existing Agentforce Employee Agent developer names

Validation Checklist

Before deploying, verify:

• fullName, label, description set
• Permissions follow least privilege
• No required fields in <fieldPermissions>
• No duplicate permissions
• No lengthy comments

What Causes Deployment Failure

• Field permissions on required fields: Any required field in <fieldPermissions> fails deployment. Required fields cannot have FLS; omit them entirely. Always confirm from object/field metadata that a field exists and is not required—never assume.
• Incorrect API names: Using the wrong name or missing suffixes (e.g. missing __c for custom objects, fields, tabs) cause failure.

Deployment

Deploy using Salesforce CLI

When to Use This Skill

Use this skill when you need to:

• Create validation rules to enforce data quality
• Prevent invalid records from being saved
• Generate validation rule metadata with formulas
• Add business logic validation to objects
• Troubleshoot deployment errors related to validation rules

Specification

ValidationRule Metadata Specification

Overview

Validation Rules are declarative metadata components used to enforce data quality and business logic in Salesforce. They evaluate a formula expression when a record is saved and prevent the save operation if the expression returns TRUE.

Purpose

-Enforce business rules at the data layer -Prevent invalid or incomplete records from being saved -Display meaningful error messages to guide users

Required Properties

Core Validation Rule Properties

• fullName

  • The unique API name of the validation rule
  • Must start with a letter
    • Can contain letters, numbers, and underscores
  • Cannot end with an underscore
  • Cannot contain consecutive underscores
  • Cannot exceed 40 character.

• active -Indicates whether the validation rule is enabled true → Rule is enforced false → Rule is inactive

• errorConditionFormula

• The logical formula that evaluates record data

• Must return TRUE or FALSE

• If TRUE, the validation rule triggers an error

• errorMessage

  • The message displayed to the user when validation fails

• Maximum length: 255 characters

Specific Function Guidelines

• TEXT - TEXT() function MUST NOT be used with Text fields, to fix this you can just remove the TEXT() function.
• CASE - In salesforce CASE() function, last parameter is the default value. Admins often miss to provide this and number of parameters to CASE() function are always even.
• VALUE - VALUE() function should only be used with Text fields. If a number is being used as a parameter to the VALUE() function, remove the VALUE() function.
• DAY - DAY() function should only be used with Date fields. If a Datetime field is being used as a parameter to the DAY() function, convert it into a Date first.
• MONTH - MONTH() function should only be used with Date fields. If a Datetime field is being used as a parameter to the MONTH() function, convert it into a Date first.
• DATEVALUE - DATEVALUE() function should only be used with DateTime fields. If a Date is being used as a parameter to the DATEVALUE() function, remove the DATEVALUE() function.
• ISPICKVAL - If checking equality of a picklist type field, the function ISPICKVAL() MUST be used.
• ISCHANGE - Use ISCHANGE() function to check the value of a record has changed.

Critical Rules

1. Formula XML Handling(MOST COMMON ERROR)

   • ANY errorConditionFormula containing XML tags MUST be inside a CDATA section in the metadata XML.

2. Interpretation of "Update" Instructions. When receiving instructions to modify a formula, distinguish between a replacement and an addition:

   • "Update the formula to [Action]": Completely replace the existing formula logic with the new requirement.
   • "Update the formula to also [Action]": Keep the existing logic and append the new requirement (usually by wrapping the logic in an AND() or OR() function).

3. File Format Requirement

   • Validation rule files MUST always use the .validationRule-meta.xml extension.

agentforce-architecture-analyze — declared architecture snapshot

Design-time metadata tree for one Agentforce agent: planner → topics → actions → flows → Apex → prompts → NGA plugins. Reads declared metadata only — BotDefinition, GenAiPlanner*, GenAiPlugin*, GenAiFunction*, Flow, ApexClass, GenAiPromptTemplate. Does not read runtime audit rows.

Runtime budget: 30–45s typical, ≤60s hard cap on reference fixtures. Sequential baseline would be 90–220s; parallel Tooling SOQL fan-out delivers a 3–5× speedup. Large bots with many flows scale approximately linearly — each flow metadata retrieve is one round-trip.

Runs inline — no subagent. Every phase is deterministic file processing.

If the user hasn't given enough to proceed

When invoked with no agent_api_name AND no org alias, print the following block verbatim — do not paraphrase, do not pre-run any script. Trigger condition: $ARGUMENTS is empty OR names no agent (no --agent flag and no known agent API name in the prose) OR names no org (no --org flag and no known alias).

Which agent should I document, and in which org?

I need:

• Agent API name — the DeveloperName of the BotDefinition (e.g. MyAgent, MySalesAgent). Not the label.
• Org alias — for sf CLI auth (the alias you configured with sf org login)

Optional:

• Version — an agent_version_api_name like v5. If omitted, I'll resolve the active BotVersion.
• --force — ignore cached tree; re-fetch everything.
• --reprobe — re-run the 7-day channel-probe cache (only needed after a Salesforce release).

I'll run the metadata pipeline inline. Artifacts land under ~/.vibe/data/agentforce-architecture-analyze/<org_id15>/<agent_api_name>__<agent_version>/ (overridable with --data-dir).

Pipeline invocation

When the user has supplied --org <alias> + --agent <api_name> (plus any optional flags), run this block. One python3 invocation drives the full pipeline. main.py writes .emit_ctx.json; emit_result.py reads it and prints the final === RESULT === block last to stdout.

set -euo pipefail

# zsh arrays are 1-indexed by default; bash arrays are 0-indexed.
# This block uses 0-indexed semantics throughout (_args[$i] starting at i=0),
# so under zsh + `set -u` the very first read of `_args[0]` would trip
# `parameter not set`. KSH_ARRAYS makes zsh treat arrays as 0-indexed,
# matching the bash shebang's expectation. No-op under bash.
[ -n "${ZSH_VERSION:-}" ] && setopt KSH_ARRAYS

SKILL_ROOT="${SKILL_ROOT:-${PLUGIN_ROOT:-$HOME/.vibe/skills}/agentforce-architecture-analyze}"

# Argument parser. Accepts both `--org foo` and `--org=foo`.
# `$ARGUMENTS` is the raw user input Claude Code substitutes.
ARG_ORG=""
ARG_AGENT=""
ARG_VERSION=""
ARG_FORCE=""
ARG_REPROBE=""
ARG_PARALLELISM=""
ARG_MAX_MERMAID=""

# shellcheck disable=SC2206
_args=($ARGUMENTS)
i=0
while [ $i -lt ${#_args[@]} ]; do
 tok="${_args[$i]}"
 case "$tok" in
 --org=*) ARG_ORG="${tok#--org=}" ;;
 --org) i=$((i+1)); ARG_ORG="${_args[$i]:-}" ;;
 --agent=*) ARG_AGENT="${tok#--agent=}" ;;
 --agent) i=$((i+1)); ARG_AGENT="${_args[$i]:-}" ;;
 --version=*) ARG_VERSION="${tok#--version=}" ;;
 --version) i=$((i+1)); ARG_VERSION="${_args[$i]:-}" ;;
 --parallelism=*) ARG_PARALLELISM="${tok#--parallelism=}" ;;
 --parallelism) i=$((i+1)); ARG_PARALLELISM="${_args[$i]:-}" ;;
 --max-mermaid-nodes=*) ARG_MAX_MERMAID="${tok#--max-mermaid-nodes=}" ;;
 --max-mermaid-nodes) i=$((i+1)); ARG_MAX_MERMAID="${_args[$i]:-}" ;;
 --force) ARG_FORCE="1" ;;
 --reprobe) ARG_REPROBE="1" ;;
 esac
 i=$((i+1))
done

# Usage block if required flags missing. Agent reads stderr,
# prints verbatim, and stops — does NOT pre-run main.py.
if [ -z "$ARG_ORG" ] || [ -z "$ARG_AGENT" ]; then
 cat >&2 <<'USAGE'
> Which agent should I document, and in which org?
>
> I need:
> - **Agent API name** — the BotDefinition.DeveloperName (e.g. `MyAgent`)
> - **Org alias** — for `sf` CLI auth (the alias you configured with `sf org login`)
>
> Optional flags:
> - `--version v5` — pin a specific BotVersion (default: Active+highest)
> - `--force` — bypass cache
> - `--reprobe` — force channel-probe refresh
> - `--parallelism N` — ThreadPoolExecutor size (default 5)
> - `--max-mermaid-nodes N` — cap Mermaid node count (default 80)
USAGE
 exit 2
fi

# Fresh work dir per invocation. Epoch + random suffix avoids collisions
# between concurrent runs on the same host.
WORK_DIR="/tmp/agentforce-architecture-analyze-$(date +%s)-$RANDOM"
mkdir -p "$WORK_DIR"

# Input validation at the boundary, BEFORE any python3 call.
# fs_guard exits 1 and prints an INVALID_INPUT RESULT block on failure;
# `|| exit 1` is mandatory — bare calls silently continue past failures.
python3 "$SKILL_ROOT/scripts/_shared/fs_guard.py" "$ARG_AGENT" agent_api_name api_name || exit 1
python3 "$SKILL_ROOT/scripts/_shared/fs_guard.py" "$ARG_ORG" org_alias not_empty || exit 1
python3 "$SKILL_ROOT/scripts/_shared/fs_guard.py" "$WORK_DIR" WORK_DIR symlink || exit 1
python3 "$SKILL_ROOT/scripts/_shared/fs_guard.py" "$WORK_DIR" WORK_DIR owned || exit 1
if [ -n "$ARG_VERSION" ]; then
 python3 "$SKILL_ROOT/scripts/_shared/fs_guard.py" "$ARG_VERSION" agent_version api_name || exit 1
fi

# Single python3 call drives all pipeline phases. main.py writes
# `.emit_ctx.json` into $WORK_DIR — emit_result.py then renders the
# RESULT block from that ctx. No subprocess-per-phase.
_main_args=(--org-alias "$ARG_ORG" --agent "$ARG_AGENT" --work-dir "$WORK_DIR")
[ -n "$ARG_VERSION" ] && _main_args+=(--version "$ARG_VERSION")
[ -n "$ARG_FORCE" ] && _main_args+=(--force)
[ -n "$ARG_REPROBE" ] && _main_args+=(--reprobe)
[ -n "$ARG_PARALLELISM" ] && _main_args+=(--parallelism "$ARG_PARALLELISM")
[ -n "$ARG_MAX_MERMAID" ] && _main_args+=(--max-mermaid-nodes "$ARG_MAX_MERMAID")

# main.py returns nonzero on terminal failures; we DON'T short-circuit —
# emit_result still publishes the failure RESULT block. `set -e` is
# temporarily relaxed around this single call.
set +e
python3 "$SKILL_ROOT/scripts/main.py" "${_main_args[@]}"
_rc=$?
set -e

# Final RESULT block is emit_result.py's stdout — MUST be the last thing
# stdout sees. emit_result exits 0 on render success; the bash harness
# propagates main.py's rc for the agent's exit status.
WORK_DIR="$WORK_DIR" python3 "$SKILL_ROOT/scripts/emit_result.py"
exit "$_rc"

Inputs

Outputs

All artifacts under ~/.vibe/data/agentforce-architecture-analyze/<org_id15>/<agent_api_name>__<agent_version>/ (default; override with --data-dir <path>):

<agent>_<ver>_metadata_tree.json   primary artifact — normalized planner/topic/action/flow/apex/prompt/plugin tree
<agent>_<ver>_architecture.md      human-readable section-by-section rendering (H1 + 7 numbered sections, plus a conditional Dependency graph appendix). Mermaid diagrams are embedded inside the relevant sections (Action tree, Data flow, and Dependency graph)

Pipeline — inline, no subagent

resolve_bot.py        → BotDefinition + BotVersion + planner name lookup
retrieve_planner.py   → Metadata API zip retrieve for GenAiPlannerBundle (+ NGA plugins if present)
parallel_retrieve.py  → 6 parallel Tooling SOQL channels fan out from the planner id
                          (resolved by the `planner_definition_by_agent_chain` seed query):
                          - plugins_by_planner (GenAiPluginDefinition)
                          - planner_bundle_functions (GenAiPlannerFunctionDef join)
                          - functions_by_plugins (GenAiFunctionDefinition)
                          - planner_attrs_by_parent_ids (GenAiPlannerAttrDefinition)
                          - plugin_functions_by_plugin_ids (GenAiPluginFunctionDef join)
                          - plugin_instructions_by_plugin_ids (GenAiPluginInstructionDef)
parse_bundle.py       → parse retrieved XML into normalized node shapes
parse_wave.py         → BFS expansion: flow/apex/prompt refs discovered in nodes
                          → SOQL for Flow/Apex bodies (batched by id list)
                          → Metadata retrieve ONLY for GenAiPromptTemplate (+ NGA external plugins conditionally)
finalize.py           → merge waves into metadata_tree.json
render_architecture.py → <agent>_<ver>_architecture.md + Mermaid invocation graph (capped at --max-mermaid-nodes)

Channel strategy — SOQL-first.

• Tooling SOQL for every normalized tree node (planner, plugins, functions, plugin-functions, plugin-instructions, planner-functions, planner-attrs) — 6 parallel channels keyed on planner id, plus the planner_definition_by_agent_chain seed query that resolves the planner id from the agent chain.
• Data API SOQL for Flow (by id) and Apex (by id or name) bodies — batched.
• Metadata retrieve only for two cases: (a) GenAiPromptTemplate (prompt bodies aren't cleanly exposed via Tooling SOQL), and (b) NGA external plugins when the planner is Native Generative Agent shape (skipped for classic ReAct).

This is where the 3–5× speedup comes from. A naive implementation would retrieve everything via Metadata API zips sequentially; parallel Tooling SOQL covers ~80% of the tree in a single fan-out.

Planner shapes — classic ReAct vs NGA

The skill normalizes two planner families into a single tree shape:

The ID-prefix router in resolve_invocation_target.py distinguishes the two: NGA InvocationTargets that look like ids (01p… = ApexClass, 301… = Flow, etc.) get resolved via id-scoped SOQL; DeveloperName targets go through name-scoped SOQL. Unknown prefixes surface as _unresolved[] with reason="unknown-id-prefix:<prefix>" — never silently dropped.

Caching

• Tree cache: metadata_tree.json is reused unless --force is passed. Cache key includes the asset-hash of every .soql / .yaml / .mmd template bundled with the skill — bump a template, the cache busts automatically.
• Channel probe cache: 7-day TTL on the per-org sf sobject describe results that validate every field name the SOQL assets reference. A Salesforce quarterly release that renames / removes a field triggers status: PROBE_FAILED; --reprobe forces a refresh.

Prerequisites

Reference docs to load when needed

Do NOT load eagerly. Load when the user's question requires it:

• references/soql_fields.md — per-sObject field reference for the 13 sObjects this skill touches (2 Data API + 11 Tooling), with [mandatory] vs [optional] tags. Load when the user asks about a specific field, or when debugging an INVALID_FIELD SOQL error.
• references/contract.json — machine-readable schema for metadata_tree.json. Load when writing downstream tooling that consumes the tree.
• references/architecture_sections.md — section-by-section structure of the rendered <agent>_<ver>_architecture.md.

Invariants worth knowing upfront

• Pipeline is deterministic. Same (org, agent, version) + static org metadata → byte-identical <agent>_<ver>_metadata_tree.json and <agent>_<ver>_architecture.md. Only manifest timestamps drift across re-runs.
• Forward-only traversal. Every discovered ref goes forward from planner → children. No backward lookups.
• Partial results are surfaced, not silenced. Any unresolved reference lands in _unresolved[] with reason=.... STATUS=PARTIAL_OK if any channel failed; STATUS=OK only on a clean run.
• Cycle detection is per-branch. Same flow visited along its own ancestor chain emits _cycle_back_to:<path> instead of recursing. A defensive MAX_BFS_DEPTH=20 guard backs the per-branch ancestor set; real-world agents bottom out well before either limit fires. (Earlier docs claimed a hard cap of 5; that was the historical limit and was abandoned because shared utility flows like handleFlowFault tripped it on every nested tree — see config.MAX_BFS_DEPTH for the rationale.)
• Child ordering is alphabetical by api_name (case-insensitive). Topics come before non-topic plannerActions at the root level. Flow-actionCall order is NOT sorted — that's the flow author's execution sequence.

agentforce-d360-analyze — Data Cloud 360° session view

Hierarchical session reconstruction from Data Cloud STDM + GenAI DMOs for one Agentforce session. Three stages — fetch → assemble → render. Typical wall-clock: ~10–30s for a ~15-turn session.

The pipeline is DC-only: it reads runtime audit rows that Data Cloud has materialized. It is not a runtime-availability tool — see "DC-only blind spot" below for what this skill cannot answer.

If the user hasn't given enough to proceed

When invoked with no session id AND no discovery criteria, print this block verbatim — do not paraphrase, do not pre-run any script. Trigger condition: the input is empty OR contains no session-id shape (neither a UUID nor a 0Mw… messaging id) AND no discovery expression (no time phrase / --agent / --channel / --outcome / --grep / verbs like "find" / "list").

Which session should I pull from Data Cloud, and in which org?

I need:

• Session id — either an Agent Session UUID (019db7f6-…) or a MessagingSession id (0Mw…, 15/18 chars).
  • No session id? — Tell me what you remember and I'll find it: how recent (e.g. "last 2 hours", "today", a date), which agent, which channel (Messaging / Builder / Voice), how it ended (escalated, user ended, transferred, timed out), or a phrase from the conversation. I'll show matching sessions as a numbered list — you pick one, I pull it.
• Org alias — for sf CLI auth (the alias you configured with sf org login).

Artifacts land in ~/.vibe/data/agentforce-d360-analyze/<org_id15>/<agent>__<ver>/<session_id>/ (override per-script with --data-dir <path>).

Session id forms — UUID or MessagingSession id

Both forms are accepted on --session:

Multi-match is real. One MessagingSession id can map to multiple Agent Session UUIDs. On multi-match the resolver prints every candidate and exits non-zero; the user re-invokes with a specific UUID.

Artifacts always land under ~/.vibe/data/agentforce-d360-analyze/<org_id15>/<agent>__<ver>/<session_id>/ (default; overridable per-script with --data-dir <path>) — the messaging id is a lookup key only, never a directory name. The dominant agent (first in sorted(agents_observed)) names the <agent>__<ver>/ segment.

Resolving the script prefix

The default install puts the skill under the runtime's plugin root. If the skill was cloned somewhere else (e.g. directly from the forcedotcom/sf-skills repo into a custom path), set PLUGIN_ROOT to point at the runtime's skills directory.

prefix="${SKILL_ROOT:-${PLUGIN_ROOT:-$HOME/.vibe/skills}/agentforce-d360-analyze}/scripts"

Every subsequent invocation in this doc uses "$prefix/...".

Session discovery (no id yet)

When the user doesn't have a session id, run discover_sessions.py against the STDM session DMO. Prints a numbered picker; user picks one; proceed with the chosen UUID.

python3 "$prefix/discover_sessions.py" --org <alias> [filters...]

Filters (all optional except --org): --since <expr> (default last 24h; accepts "last 2 hours", "today", ISO dates), --agent <api-name>, --channel <Messaging|Builder|Voice>, --outcome <USER_ENDED|ESCALATED|TRANSFERRED|TIMEOUT|NOT_SET>, --grep <substring> (conversation text), --tz <IANA>, --limit <N> (default 20).

Output: markdown table with #, UUID, Start (UTC), Agent, Channel, Duration, Outcome. User replies with a number; proceed with that UUID.

Pipeline — three stages

fetch_dc.py     →  24 dc.<name>.json + dc._session_manifest.json     (DC Query REST waterfall, 5 waves)
assemble_dc.py  →  dc._session_tree.json                             (pure in-memory hierarchical join)
render_dc.py    →  dc._session_summary.md                            (human summary, multi-section)

Each stage is independently runnable. fetch_dc.py --session <sid> --org <alias> chains all three by default.

Invocation

python3 "$prefix/fetch_dc.py" --session <session-id-or-messaging-id> --org <alias>

Flags: --verbose for per-DMO row counts; --no-assemble / --no-render to stop early. All entry scripts (fetch_dc.py, assemble_dc.py, render_dc.py, resolve_session.py, discover_sessions.py) accept --data-dir <path> and --cache-dir <path> to override the default ~/.vibe/{data,cache}/agentforce-d360-analyze/ roots — pass these when the host runtime needs artifacts under a different distribution layout.

Output artifacts

Everything lands under ~/.vibe/data/agentforce-d360-analyze/<org_id15>/<agent>__<ver>/<session_id>/ (default; override with --data-dir <path>):

dc.sessions.json              dc.steps.json                dc.gateway_requests.json
dc.interactions.json          dc.messages.json             dc.gateway_responses.json
dc.participants.json          dc.generations.json          dc.gateway_request_llm.json
dc.content_quality.json       dc.content_category.json     dc.gateway_request_metadata.json
dc.tags.json                  dc.tag_definitions.json      dc.gateway_request_tags.json
dc.tag_associations.json      dc.tag_definition_associations.json
dc.feedback.json              dc.feedback_details.json     dc.gateway_records.json
dc.moments.json               dc.moment_interactions.json
dc.telemetry_spans.json       dc.app_generation.json

dc._session_manifest.json     (per-DMO row counts + empties)
dc._session_tree.json         (hierarchical join — session → interactions → steps → messages → generations → gateway)
dc._session_summary.md        (rendered human summary)

Zero-row queries are recorded in the manifest with status: empty; no file is written. assemble_dc tolerates missing files. See references/artifacts.md for the full read order.

The DC-only blind spot — read before committing to a root cause

DC alone answers what happened — steps that ran, generations that fired, gateway requests that were logged. It does NOT answer what could have happened but didn't:

• Which topics were eligible for the classifier on a given turn (this lives in runtime planner telemetry, not DC).
• Which actions were declared on a topic vs. which survived rule expressions and were actually offered to the LLM.
• Why the LLM picked one topic/action over another (the full prompt + response text only lives in the planner runtime telemetry).

If the user's question is about why a particular topic or action was or wasn't used, DC-only is almost never sufficient. Tell the user: "Availability questions need the runtime planner trace for that turn — which is outside this skill's Data Cloud surface. Check the platform telemetry that mirrors the planner's logged decisions." Don't fabricate a root cause from runtime-only evidence.

What DC IS good at

• What ran — every step, every LLM call, every gateway request + response, in order, with timestamps and durations. Good for "walk me through the session".
• What the user saw — full message transcript (user + agent), ordered.
• What the LLM produced — generations, token counts, trust scores (toxicity, instruction adherence, content-category breakdown from content_quality + content_category).
• Tool invocations — action calls, inputs, outputs, errors (from gateway_request_metadata + gateway_records).
• Feedback + flags — user feedback, escalation markers, session-end type.
• Audit integrity — the 1:1 invariant between GatewayRequest and GatewayResponse is checked; drift is flagged in counts.audit_chain_1to1_ok.

Prerequisites

Typical prompts — what they map to

What comes back to the user

After the pipeline completes, the rendered dc._session_summary.md carries these top-level sections:

1. Session identity — UUID, start/end, duration, agent, channel, end type, participant counts
2. Session bootstrap — channel mode + bootstrap variables (identity.mode, identity.bootstrap_variables)
3. ID reference — full UUIDs for everything truncated in the hierarchical trace
4. Transcript — USER ↔ AGENT narrative per TURN interaction
5. Complete hierarchical trace — Interaction → Step → Generation → GatewayRequest, with +start + duration = +end math
6. Per-turn summary — one row per interaction
7. Planner LLM calls (full prompts + responses) — opt-in via --show-prompts; suppressed by default
8. Visual analysis — gantt + LLM-call overlay
9. Session counts — engineer-facing table of manifest counts
10. Empties diagnostics — one row per DMO with rows == 0 and a populated _unavailable_reason
11. Catalog (session-filtered) — TagDefinitions / TagDefinitionAssociations / Tags filtered to agents observed in the session

For deep-dive, open dc._session_tree.json — the single source of truth the summary was rendered from. See references/dc_pipeline_contract.md for the full pipeline contract and references/dc_dmo_fields.md for per-DMO field reference.

Caveats

• gateway_requests_dropped_by_stdm — when DC reports zero gateway_requests rows but runtime telemetry would show LLM calls did fire, this skill cannot definitively distinguish "STDM exporter dropped writes" from "logging genuinely disabled at the source". The session is reported as planner_ran_no_gateway_logs; the operator can check platform telemetry to disambiguate. See references/dc_pipeline_contract.md §2.8.
• Latency — Generation and GatewayRequest carry single-write timestamps, not start/end pairs. The renderer does not compute "latencies" between them — that delta reflects DC's serialization order, not how long the LLM call took.
• Data Cloud materialization lag — fresh sessions may show interactions_not_materialized_yet if STDM hasn't caught up. Re-run after a minute or two.

Agent Script Skill

What This Skill Is For

Agent Script is Salesforce's scripting language for authoring next-generation AI agents on the Atlas Reasoning Engine. Introduced in 2025 with zero training data in any AI model. Everything needed to write, modify, diagnose, or deploy Agent Script agents is in this skill's reference files.

⚠️CRITICAL: Agent Script is NOT AppleScript, JavaScript, Python, or any other language. Do NOT confuse Agent Script syntax or semantics with any other language you have been trained on.

Agent Script agents are defined by AiAuthoringBundle metadata — a directory with a .agent file containing Agent Script source that describes actions, instructions, subagents, flow control, and configuration; and a bundle-meta.xml file containing bundle metadata. Agents process utterances by routing through subagents, each with instructions and actions backed by Apex, Flows, Prompt Templates, and other types of backing logic.

This skill covers the full Agent Script lifecycle: designing agents, writing Agent Script code, validating and debugging, deploying and publishing, and testing.

How to Use This Skill

This file maps user intent to task domains and relevant reference files in references/. Detailed knowledge includes syntax rules, design patterns, CLI commands, debugging workflows, and more.

Identify user intent from task descriptions. ALWAYS read indicated reference files BEFORE starting work.

Rules That Always Apply

1. Always --json. ALWAYS include --json on EVERY sf CLI command. Do NOT pipe CLI output through jq or 2>/dev/null. Read the full JSON response directly — LLMs parse JSON natively.

2. Verify target org. Before any org interaction, run sf config get target-org --json to confirm a target org is set. If none configured, ask the user to set one with sf config set target-org <alias>.

3. Diagnose before you fix. When validating/debugging agent behavior, ALWAYS --use-live-actions to preview authoring bundles. Send utterances then read resulting session traces to ground your understanding of the agent's behavior. Trace files reveal subagent selection, action I/O, and LLM reasoning. DO NOT modify .agent files or backing logic without this grounding. See Validation & Debugging for trace file locations and diagnostic patterns.

4. Spec approval is a hard gate. Never proceed past Agent Spec creation without explicit user approval.

Task Domains

Every task domain below has Required Steps. Follow verbatim, in order. Do not substitute your own plan or skip steps.

Create an Agent

User wants to build new agent from scratch. ALWAYS use Agent Script. Work with User to understand the agent's purpose, subagents, and actions using plain language without Salesforce-specific terminology.

Required Steps

Read CLI for Agents for exact command syntax.

1. Design — Read Design & Agent Spec to draft an Agent Spec. Always ask if you should scan for existing backing logic. Unless instructed otherwise, scan by reading sfdx-project.json to identify package directories, then search each for @InvocableMethod in classes/, AutoLaunchedFlow in flows/, and template metadata in promptTemplates/. Mark matches EXISTS; unmatched actions NEEDS STUB. Also scan objects/ for .object-meta.xml to discover custom objects — related objects often contain data the agent should expose even when not mentioned in the prompt. Always save Agent Spec as file.
2. STOP for user approval of Agent Spec. Present to user. Ask for approval or feedback. Do not proceed without approval. Once approved, proceed without stopping unless a step fails.
3. Validate environment prerequisites — Read Design & Agent Spec, Section 3 (Environment Prerequisites). Based on agent type from design, validate org environment:
   • Employee agent: Confirm config block does NOT include default_agent_user, connection messaging:, or MessagingSession linked variables. Remove if present. See Examples for a complete employee agent example.
   • Service agent: Query org for Einstein Agent User. If one exists, confirm username with user. If none, guide user through creation. See CLI for Agents, Section 12 for creation steps and Agent User Setup for required permissions. Do not proceed to code generation until environment is validated.
4. Generate authoring bundle — sf agent generate authoring-bundle --json --no-spec --name "<Label>" --api-name <Developer_Name>
5. Write code — Read Core Language for syntax, block structure, and anti-patterns. Edit generated .agent file using reference files and templates. Do not create .agent or bundle-meta.xml files manually.
6. Validate compilation — sf agent validate authoring-bundle --json --api-name <Developer_Name> If validation fails, read Validation & Debugging to diagnose and fix, then re-validate. ALWAYS fix syntax and structural errors before generating backing logic.
7. Generate backing logic — For each action marked NEEDS STUB: sf template generate apex class --name <ClassName> --output-dir <PACKAGE_DIR>/main/default/classes Replace class body with invocable pattern from Design & Agent Spec. ALWAYS deploy: sf project deploy start --json --metadata ApexClass:<ClassName> ALWAYS fix deploy errors BEFORE generating and deploying next stub.
8. Validate behavior — Read Validation & Debugging for preview workflow and session trace analysis. sf agent preview start --json --use-live-actions --authoring-bundle <Developer_Name> If actions query data, ground test utterances with: sf data query --json -q "SELECT <Relevant_Fields> FROM <SObject> LIMIT 100" Send test utterances with: sf agent preview send --json --authoring-bundle <Developer_Name> --session-id <ID> -u "<message>" Confirm subagent routing, gating, and action invocations match Agent Spec. If behavior diverges, switch to Diagnose Behavioral Issues workflow. Return AFTER correcting issues. CHECKPOINT — Do NOT proceed to Publish unless ALL are true:
   • validate authoring-bundle passes with zero errors
   • Live preview (--use-live-actions) tested with representative utterances per subagent
   • Traces confirm correct subagent routing and action invocation
   • User explicitly approves deployment
9. Publish — Publish validates metadata structure, not agent behavior. Every publish creates permanent version number. sf agent publish authoring-bundle --json --api-name <Developer_Name> If publish fails, follow troubleshooting checklist in Metadata & Lifecycle, Section 5 before retrying.
10. Activate — Makes new version available to users. sf agent activate --json --api-name <Developer_Name>
11. Verify published agent — Preview user-facing behavior AFTER activation with sf agent preview start --json --api-name <Developer_Name> Use --api-name, not --authoring-bundle.
12. Configure end-user access — ONLY for employee agents. Read Agent Access Guide to configure perms and assign access.

Reference Files

1. CLI for Agents — exact command syntax for generate, validate, deploy, publish, activate; Section 12 for Einstein Agent User creation
2. Core Language — execution model, syntax, block structure, anti-patterns
3. Design & Agent Spec — subagent graph design, flow control patterns, Agent Spec production, backing logic analysis; Section 3 for environment prerequisites
4. Subagent Map Diagrams — Mermaid diagram conventions for visualizing the agent's subagent graph
5. Agent User Setup & Permissions — permission set assignment, object permissions, cross-subagent validation
6. Metadata & Lifecycle — directory structure, bundle metadata; publish troubleshooting
7. Validation & Debugging — validate the agent compiles, preview to confirm behavior
8. Agent Access Guide — end-user access permissions, visibility troubleshooting
9. Known Issues — only load when errors persist after code fixes
10. Architecture Patterns — hub-and-spoke, verification gate, post-action loop
11. Complex Data Types — type mapping decision tree
12. Safety Review — 7-category safety review
13. Discover Reference — target discovery CLI
14. Scaffold Reference — stub generation CLI
15. Deploy Reference — deployment lifecycle, error recovery

Comprehend an Existing Agent

User wants to understand Agent Script agent they didn't write or need to revisit. May point to AiAuthoringBundle directory or ask "what does this agent do?" or "I need to fix this agent but I don't understand how it works.".

Required Steps

1. Locate agent — Read sfdx-project.json to identify package directories. Find AiAuthoringBundle directory within them. Read .agent file and bundle-meta.xml.
2. Read code — Read Core Language for syntax and execution model BEFORE parsing .agent file.
3. Map backing logic — For each action with target, locate backing implementation (Apex class, Flow, Prompt Template) in project. Note input/output contracts.
4. Reverse-engineer Agent Spec — Read Design & Agent Spec for Agent Spec structure. Produce Agent Spec from code and save as file.
5. Produce Subagent Map diagram — Read Subagent Map Diagrams for Mermaid conventions. Generate flowchart of subagent graph showing transitions, gates, and action associations.
6. Annotate source — Ask if user wants Agent Script source annotated with explanations. If requested, add inline comments to .agent file explaining flow control decisions, gating rationale, and subagent relationships.
7. Present to user — Share Agent Spec, Subagent Map, and annotated source if produced. Check Anti-Patterns section in Core Language reference and flag any matches found in code.

Reference Files

1. Core Language — syntax, execution model, anti-patterns
2. Design & Agent Spec — Agent Spec structure, flow control pattern recognition
3. Subagent Map Diagrams — Mermaid conventions for subagent graph visualization
4. Metadata & Lifecycle — directory conventions, bundle metadata
5. Known Issues — only load when code contains unexplained workaround patterns

Modify an Existing Agent

User wants to add, remove, or change subagents, actions, instructions, or flow control on existing agent. May describe change in plain language ("add a billing subagent") or reference specific Agent Script constructs.

Required Steps

Read CLI for Agents for exact command syntax.

1. Comprehend — If no Agent Spec exists, reverse-engineer first by following "Comprehend an Existing Agent" workflow above.
2. Update Agent Spec — Read Design & Agent Spec for flow control patterns and backing logic analysis. Modify Agent Spec to reflect intended changes. For new actions, always ask if you should scan for existing backing logic. Unless instructed otherwise, scan by reading sfdx-project.json to identify package directories, then search each for @InvocableMethod in classes/, AutoLaunchedFlow in flows/, and template metadata in promptTemplates/. Mark matches EXISTS; unmatched actions NEEDS STUB. Always save updated Agent Spec as file.
3. STOP for user approval of updated Agent Spec. Present to user. Ask for approval or feedback. Do not proceed without approval. Once approved, proceed without stopping unless a step fails.
4. Edit code — Read Core Language for syntax and anti-patterns. Edit .agent file to implement approved changes.
5. Validate compilation — sf agent validate authoring-bundle --json --api-name <Developer_Name> If validation fails, read Validation & Debugging to diagnose and fix, then re-validate.
6. Generate new backing logic — For each new action marked NEEDS STUB: sf template generate apex class --name <ClassName> --output-dir <PACKAGE_DIR>/main/default/classes Replace class body with invocable pattern from Design & Agent Spec. ALWAYS deploy: sf project deploy start --json --metadata ApexClass:<ClassName> ALWAYS fix deploy errors BEFORE generating and deploying next stub. Skip if no new actions added.
7. Validate behavior — Read Validation & Debugging for preview workflow and session trace analysis. sf agent preview start --json --use-live-actions --authoring-bundle <Developer_Name> If actions query data, ground test utterances with: sf data query --json -q "SELECT <Relevant_Fields> FROM <SObject> LIMIT 100" Send test utterances with: sf agent preview send --json --authoring-bundle <Developer_Name> --session-id <ID> -u "<message>" Test changed paths first, then adjacent paths to catch regressions in existing behavior. CHECKPOINT — Do NOT proceed to Publish unless ALL are true:
   • validate authoring-bundle passes with zero errors
   • Live preview (--use-live-actions) tested with representative utterances per subagent
   • Traces confirm correct subagent routing and action invocation
   • User explicitly approves deployment
8. Publish — Publish validates metadata structure, not agent behavior. Every publish creates permanent version number. sf agent publish authoring-bundle --json --api-name <Developer_Name> If publish fails, follow troubleshooting checklist in Metadata & Lifecycle, Section 5 before retrying.
9. Activate — Makes new version available to users. sf agent activate --json --api-name <Developer_Name>
10. Verify published agent — Preview user-facing behavior AFTER activation with sf agent preview start --json --api-name <Developer_Name> Use --api-name, not --authoring-bundle.

Reference Files

1. CLI for Agents — exact command syntax for validate, deploy, preview, publish, activate
2. Core Language — syntax, anti-patterns
3. Design & Agent Spec — Agent Spec updates, backing logic analysis
4. Validation & Debugging — compilation diagnosis, preview workflow, session trace analysis
5. Known Issues — only load when errors persist after code fixes

Diagnose Compilation Errors

User has Agent Script that won't compile. Errors surface from sf agent validate or sf agent preview start, or User describes symptoms like "I'm getting a validation error."

Required Steps

Read CLI for Agents for exact command syntax.

1. Reproduce error — Run sf agent validate authoring-bundle --json --api-name <Developer_Name> to capture basic compile errors. If no errors, run sf agent preview start --json --use-live-actions --authoring-bundle <Developer_Name> to capture complex compile errors. If user provides specific error output, ALWAYS reproduce to confirm.
2. Classify error — Read Validation & Debugging for error taxonomy. Map each error message to root cause category.
3. Locate fault — Read Core Language to understand correct syntax. Find specific line(s) in .agent file that cause each error.
4. Fix code — Apply targeted fixes. Check Anti-Patterns section in Core Language reference to ensure you're not introducing known bad pattern.
5. Re-validate — Run sf agent validate authoring-bundle --json --api-name <Developer_Name> then run sf agent preview start --json --use-live-actions --authoring-bundle <Developer_Name> Repeat steps 2–5 if errors persist.
6. Explain fix — Tell user what was wrong and what you changed. Explain root cause in terms of Core Language agent execution model.

Reference Files

1. Core Language — syntax, block structure, anti-patterns
2. Validation & Debugging — error taxonomy, error-to-root-cause mapping
3. Known Issues — only load when error doesn't match user code; may be a platform bug
4. Production Gotchas — only load when error involves reserved keywords or lifecycle hook syntax

Diagnose Behavioral Issues

Agent compiles, preview can start and --use-live-actions, but agent does not behave as expected. User describes symptoms like "the agent keeps going to the wrong subagent" or "the action isn't being called." Fundamentally different from validate or preview start errors — code is valid but behavior is wrong.

Required Steps

Read CLI for Agents for exact command syntax.

1. Establish baseline — Read Agent Spec. If no Agent Spec exists, follow Comprehend an Existing Agent workflow to reverse-engineer one, then continue.
2. Form hypotheses — Read Core Language for execution model. Based on user's description, list candidate root causes. Think through: subagent routing, gating conditions, action availability, instruction clarity, variable state, and transition timing.
3. Reproduce in preview — Read Validation & Debugging for preview workflow and session trace analysis. Start preview session: sf agent preview start --json --use-live-actions --authoring-bundle <Developer_Name> then send test messages covering EACH subagent with sf agent preview send. One message is not enough — confirm behavior per subagent before proceeding.
4. Analyze session traces — Examine trace output to confirm subagent selection, action availability/execution, LLM reasoning, and where behavior diverges from Agent Spec. Do NOT skip this step — preview output alone is insufficient for diagnosis.
5. Identify root cause — Match trace evidence to hypotheses. Consult Core Language reference and Gating Patterns in Design & Agent Spec reference to confirm absence of anti-patterns.
6. Fix code — Apply targeted fix. If fix involves flow control changes, update Agent Spec to match.
7. Re-validate and re-preview — Repeat steps 3–6 until behavior matches Agent Spec or you confirm a platform limitation. Run validate authoring-bundle, then preview start --use-live-actions to verify fix using same utterances. Then test adjacent paths that might be affected by your changes.
8. Explain fix — Tell user what was wrong and what you changed. Explain root cause in terms of Core Language agent execution model.

Reference Files

1. Core Language — execution model, anti-patterns
2. Design & Agent Spec — Agent Spec as behavioral baseline, gating patterns
3. Validation & Debugging — preview workflow, session trace analysis
4. Known Issues — only load when behavior is wrong but code logic is correct

Deploy, Publish, and Activate

User wants to take working agent from local development to running state in Salesforce org. Involves deploying AiAuthoringBundle and its dependencies, publishing to commit version, then activating to make it live.

Required Steps

Read CLI for Agents for exact command syntax.

1. Validate compilation — sf agent validate authoring-bundle --json --api-name <Developer_Name> Do not proceed if validation fails.
2. Deploy bundle and dependencies — Read Metadata & Lifecycle for dependency management and deploy commands. Deploy AiAuthoringBundle and all backing logic (Apex classes, Flows, Prompt Templates) and dependencies to org.
3. Live preview — Read Validation & Debugging for preview workflow and session trace analysis. sf agent preview start --json --use-live-actions --authoring-bundle <Developer_Name> then send test utterances with: sf agent preview send --json --authoring-bundle <Developer_Name> --session-id <ID> -u "<message>" Test key conversation paths to validate agent behavior when backed by live actions. CHECKPOINT — Do NOT proceed to Publish unless ALL are true:
   • validate authoring-bundle passes with zero errors
   • Live preview (--use-live-actions) tested with representative utterances per subagent
   • Traces confirm correct subagent routing and action invocation
   • User explicitly approves deployment
4. Publish — Publish validates metadata structure, not agent behavior. DO NOT publish as part of a dev/test inner loop. ONLY publish as the FINAL step prior to activating the agent and surfacing it to end users. sf agent publish authoring-bundle --json --api-name <Developer_Name> If publish fails, follow Troubleshooting Publish Failures in Metadata & Lifecycle before retrying.
5. Activate — Makes new version available to users. sf agent activate --json --api-name <Developer_Name>
6. Verify published agent — Preview user-facing behavior AFTER activation with sf agent preview start --json --api-name <Developer_Name> Use --api-name, not --authoring-bundle.
7. Configure end-user access — ONLY for employee agents. Read Agent Access Guide to configure perms and assign access.

Reference Files

1. CLI for Agents — exact command syntax for deploy, publish, activate, deactivate
2. Validation & Debugging — compilation validation, preview workflow
3. Metadata & Lifecycle — dependency management, deploy commands; publish troubleshooting
4. Agent Access Guide — end-user access permissions, visibility troubleshooting
5. Known Issues — only load when deploy hangs, publish fails, or activate fails unexpectedly

Diagnose Production Issues

User's agent is published and active but experiencing issues not caught during preview. Includes credit overconsumption, token or size limit failures, loop guardrail interruptions, reserved keyword runtime errors, VS Code sync failures, or unexpected behavioral differences between preview and production.

Required Steps

Read CLI for Agents for exact command syntax.

1. Classify issue — Determine whether this is billing/cost concern, runtime limit, naming conflict, tooling issue, or behavioral difference between preview and production.
2. Check known production gotchas — Read Production Gotchas for credit consumption, token limits, loop guardrails, reserved keywords, lifecycle hooks, and VS Code workarounds.
3. Compare preview vs production behavior — If issue is behavioral, preview published agent with sf agent preview start --json --api-name <Developer_Name> (not --authoring-bundle). Compare against live-actions authoring bundle preview --authoring-bundle <Developer_Name> --use-live-actions to isolate preview-vs-production differences.
4. Check known issues — Read Known Issues for platform bugs that may explain production-only failures.
5. Fix and republish — Apply fixes, validate, re-preview, publish, activate, verify. Follow Deploy, Publish, and Activate steps.
6. Explain diagnosis — Tell user what was happening and what you changed. Explain root cause.

Reference Files

1. Production Gotchas — credit consumption, token limits, loop guardrails, reserved keywords, lifecycle hooks, VS Code workarounds
2. CLI for Agents — command syntax for preview, publish, activate
3. Validation & Debugging — preview workflow, session trace analysis
4. Known Issues — only load when issue may be a platform bug

Delete or Rename an Agent

User wants to remove agent or change its name. Maintenance tasks complicated by AiAuthoringBundle versioning and published version dependencies.

Required Steps

Read CLI for Agents for exact command syntax.

1. Understand current state — Read Metadata & Lifecycle for versioning, delete mechanics, and rename mechanics. Identify whether agent has been published, how many versions exist, and whether it's currently active.
2. Deactivate if active — sf agent deactivate --json --api-name <Developer_Name> Active agent cannot be deleted or renamed.
3. Execute operation — For delete: follow delete mechanics in Metadata & Lifecycle reference. For rename: follow rename mechanics in same reference.
4. Clean up orphans — Check for and remove orphaned metadata: Bot, BotVersion, GenAiPlannerBundle, GenAiPlugin, GenAiFunction. Metadata & Lifecycle reference details what to look for.
5. Validate — Confirm operation completed cleanly. For rename, validate new bundle compiles and preview to confirm behavior.

Reference Files

1. CLI for Agents — exact command syntax for delete, deactivate, retrieve
2. Validation & Debugging — compilation validation, preview workflow
3. Metadata & Lifecycle — delete mechanics, rename mechanics, orphan cleanup

Test an Agent

User wants to create automated tests for Agent Script agent. Involves writing AiEvaluationDefinition test specs in YAML format that define test scenarios, expected behaviors, and quality metrics.

Required Steps

Read CLI for Agents for exact command syntax.

1. Establish coverage baseline — Read Agent Spec. If no Agent Spec exists, reverse-engineer first by following Comprehend steps. Map every subagent, action, and flow control path to identify what needs test coverage.
2. Design test scenarios — For test design methodology, expectations, metrics, test spec YAML format, and templates, use agentforce-test skill. That skill owns all testing content. For each coverage target, write one or more test scenarios: user utterance, expected subagent routing, expected action invocations, and expected agent response. Include both happy paths and edge cases.
3. Write test spec YAML — Use template and reference files from agentforce-test skill. Save to specs/<Agent_API_Name>-testSpec.yaml in SFDX project.
4. Create test metadata — Generate AiEvaluationDefinition from test spec using CLI.
5. Deploy test — Deploy AiEvaluationDefinition to org.
6. Run tests — Execute test run using CLI. Capture results.
7. Analyze results — Compare actual outcomes against expectations. For failures, identify whether issue is in agent code, backing logic, or test spec itself.
8. Iterate — Fix agent code or test spec as needed, redeploy, and re-run until coverage targets are met.

Reference Files

1. CLI for Agents — exact command syntax for test create, test run, test results
2. Core Language — agent structure for designing meaningful tests
3. Design & Agent Spec — Agent Spec as test coverage baseline
4. agentforce-test skill — test spec YAML format, expectations, metrics, test design methodology, and test spec template

The Agent Spec

Agent Spec is the central artifact this skill produces and consumes. A structured design document representing agent's purpose, subagent graph, actions with backing logic, variables, gating logic, and behavioral intent.

Agent Specs evolve with the agent. Sparse during agent creation (purpose, topics, directional notes). Fleshed out during agent build (flowchart, backing logic mapped, gating documented). Reverse-engineered when comprehending existing agents. Critical for advanced troubleshooting, providing reference to compare expected vs. actual behavior. During testing, test coverage maps against it.

Always produce or update Agent Spec as first step of any operation that changes or analyzes agent. It is consistent grounding to work from, and a durable artifact a developer can review.

Read Design & Agent Spec for Agent Spec structure and production methodology.

Assets

The assets/ directory contains templates and examples. Read when you need a starting point or a concrete reference for artifacts and source files.

• assets/agent-spec-template.md — Agent Spec template with all sections and placeholder content. Copy to <AgentName>-AgentSpec.md in project directory, then fill in during design. Save Agent Spec as file — significant design artifact that benefits from proper rendering, especially Mermaid Subagent Map diagram.

• assets/local-info-agent-annotated.agent — Complete annotated example based on Local Info Agent, showing all major Agent Script constructs in context with inline comments explaining why each construct is used. Read when you need concrete reference for how concepts compose into working agent, or as fallback when focused examples in reference files aren't sufficient.

• assets/template-single-subagent.agent — Minimal agent with one subagent. Copy and modify for simple agents.

• assets/template-multi-subagent.agent — Minimal agent with multiple subagents and transitions. Copy and modify for complex agents.

• assets/invocable-apex-template.cls — Reference for invocable Apex classes. Copy and modify when complex Apex backing logic is desired.

Important Constraints

• Use only Salesforce CLI and Salesforce org. Do not reference or depend on other skills, MCP servers, or external tooling. All commands use sf (Salesforce CLI).

• Only certain backing logic types are valid for actions. For example, only invocable Apex (not arbitrary Apex classes) can back action. Similar constraints may apply to Flows and Prompt Templates. When wiring actions to backing logic, consult Design & Agent Spec reference file for valid types and stubbing methodology.

• sf agent generate test-spec is not for agentic use. It is interactive, REPL-style command designed for humans. When creating test specs, start from boilerplate template in assets instead.

Common Issues Quick Reference

Internal Error, try again later during publish: Invalid or missing default_agent_user. Re-run query from Design & Agent Spec, Section 3. Do not invent username.

Unable to access Salesforce Agent APIs... during preview: default_agent_user lacks permissions. See Agent User Setup & Permissions. Do NOT publish as fix — --use-live-actions does not require published agent.

Permission error referencing different username than configured: Same fix as above — error references org's default running user, but root cause is Einstein Agent User permissions.

Agent fails with permission error even though current subagent's actions work: Planner validates ALL actions across ALL subagents at startup. One missing permission fails entire agent.

Apex action returns empty results in live preview but works in simulated: WITH USER_MODE + missing object permissions = silent failure (0 rows, no error). See Agent User Setup & Permissions, Section 6.2.

Syntax Quick Reference

• Block order: system: → config: → variables: → connection: → knowledge: → language: → start_agent agent_router: → subagent: blocks
• Indentation: 4 spaces per indent level. Never use tabs. Mixing spaces and tabs breaks the parser.
• Booleans: True/False (capitalized)
• Strings: always double-quoted
• Numeric action I/O: bare number works for variables but fails at publish in action I/O. Use object + complex_data_type_name for numeric action parameters. See Complex Data Types for the full decision tree.
• after_reasoning: has NO instructions: wrapper
• No else if — use compound if x and y: or sequential flat ifs
• Reserved @InvocableVariable names: model, description, label — cannot be used as Apex parameter names
• @inputs and @outputs are ephemeral: @inputs only in with; @outputs only in set/if immediately after the action. @inputs in set = silent failure.

See Complex Data Types for the full Lightning type mapping decision tree. See Instruction Resolution for the 3-phase runtime model.

Architecture Patterns

Three primary FSM patterns. Full details with code in Architecture Patterns.

• Hub-and-Spoke (most common): start_agent routes to specialized subagents. Each subagent has "back to hub" transition. Do NOT create a separate routing subagent.
• Verification Gate: Identity verification before protected subagents. available when guards on protected transitions.
• Post-Action Loop: Post-action checks at TOP of instructions: -> trigger on re-resolution after action completes.

Scoring Rubric

Score every generated agent on 100 points across 7 categories: Structure (15), Safety (15), Deterministic Logic (20), Instruction Resolution (20), FSM Architecture (10), Action Configuration (10), Deployment Readiness (10).

See Scoring Rubric for the complete rubric.

Review Mode

When user provides an existing .agent file (e.g., review path/to/file.agent):

1. Read the file
2. Score against the 100-point rubric
3. List every issue grouped by category
4. Provide corrected code snippets
5. Offer to apply fixes

Safety Review

7-category LLM-driven safety review for .agent files. Integrated into Phase 0 of authoring and deployment. Categories: Identity & Transparency, User Safety, Data Handling, Content Safety, Fairness, Deception, Scope & Boundaries.

See Safety Review for the complete framework, severity levels, false positive guidance, and adversarial test prompts.

Discover & Scaffold

Validate action targets exist in org and generate stubs for missing ones.

See Discover Reference and Scaffold Reference.

CRITICAL: Stubs must return realistic data, not 'TODO'. Placeholder responses cause SMALL_TALK grounding because the LLM falls back to training data.

Deploy Lifecycle

Validate → deploy metadata → publish bundle → activate. See Deploy Reference for phases, error recovery, CI/CD, and rollback.

Template Assets

Ready-to-use .agent templates in assets/agents/ (hello-world, simple-qa, multi-subagent, production-faq, order-service, verification-gate). See also assets/patterns/ for 11+ reusable design patterns and Examples for inline walkthroughs.

Additional References

Agentforce Observability

Improve Agentforce agents using session trace data and live preview testing.

Three-phase workflow:

• Observe -- Query STDM sessions from Data Cloud (if available), OR run test suites + preview with local traces as fallback
• Reproduce -- Use sf agent preview to simulate problematic conversations live
• Improve -- Edit the .agent file directly, validate, publish, verify

Platform Notes

• Shell examples below use bash syntax. On Windows, use PowerShell equivalents or Git Bash.
• Replace python3 with python on Windows.
• Replace /tmp/ with $env:TEMP\ (PowerShell) or %TEMP%\ (cmd).
• Replace jq with python -c "import json,sys; ..." if jq is not installed.

Routing

Gather these inputs before starting:

• Org alias (required)
• Agent API name (required for preview and deploy; ask if not provided)
• Agent file path (optional) -- path to the .agent file, typically force-app/main/default/aiAuthoringBundles/<AgentName>/<AgentName>.agent. Auto-detect if not provided.
• Session IDs (optional) -- analyze specific sessions; if absent, query last 7 days
• Days to look back (optional, default 7)

Determine intent from user input:

• No specific action -> run all three phases: Observe -> surface issues -> ask if user wants to Reproduce and/or Improve
• "analyze" / "sessions" / "what's wrong" -> Phase 1 only, then suggest next steps
• "reproduce" / "test" / "preview" -> Phase 2 (run Phase 1 first if no issues in hand)
• "fix" / "improve" / "update" -> Phase 3 (run Phase 1 first if no issues in hand)

Resolve agent name

Before any STDM query, resolve the user-provided agent name against the org to get the exact MasterLabel and DeveloperName:

sf data query --json \
  --query "SELECT Id, MasterLabel, DeveloperName FROM GenAiPlannerDefinition WHERE MasterLabel LIKE '%<user-provided-name>%' OR DeveloperName LIKE '%<user-provided-name>%'" \
  -o <org>

• MasterLabel = display name used by STDM findSessions and Agent Builder UI (e.g. "Order Service")
• DeveloperName = API name with version suffix used in metadata (e.g. "OrderService_v9")
• The --api-name flag for sf agent preview/activate/publish uses DeveloperName without the _vN suffix (e.g. "OrderService")

Store these values:

• AGENT_MASTER_LABEL -- for findSessions() agent filter
• AGENT_API_NAME -- DeveloperName without _vN suffix, for sf agent CLI commands
• PLANNER_ID -- the Salesforce record ID for this agent

Locate the .agent file

Step 1 -- Search locally:

find <project-root>/force-app/main/default/aiAuthoringBundles -name "*.agent" 2>/dev/null

If the user provided an agent file path, use that directly. Otherwise, search for files matching AGENT_API_NAME.

Step 2 -- If not found locally, retrieve from the org:

sf project retrieve start --json --metadata "AiAuthoringBundle:<AGENT_API_NAME>" -o <org>

Known bug: sf project retrieve start creates a double-nested path: force-app/main/default/main/default/aiAuthoringBundles/.... Fix it immediately after retrieve:

if [ -d "force-app/main/default/main/default/aiAuthoringBundles" ]; then
  mkdir -p force-app/main/default/aiAuthoringBundles
  cp -r force-app/main/default/main/default/aiAuthoringBundles/* \
    force-app/main/default/aiAuthoringBundles/
  rm -rf force-app/main/default/main
fi

Step 3 -- Validate the retrieved file:

Read the .agent file and verify it has proper Agent Script structure:

• system: block with instructions:
• config: block with developer_name:
• start_agent or subagent blocks with reasoning: instructions:
• Each subagent should have distinct instructions: content (not identical across subagents)

Store the resolved path as AGENT_FILE for Phase 3.

Phase 0: Discover Data Space

Before running any STDM query, determine the correct Data Cloud Data Space API name.

sf api request rest "/services/data/v63.0/ssot/data-spaces" -o <org>

Note: sf api request rest is a beta command -- do not add --json (that flag is unsupported and causes an error).

The response shape is:

{
  "dataSpaces": [
    {
      "id": "0vhKh000000g3DjIAI",
      "label": "default",
      "name": "default",
      "status": "Active",
      "description": "Your org's default data space."
    }
  ],
  "totalSize": 1
}

The name field is the API name to pass to AgentforceOptimizeService.

Decision logic:

• If the command fails (e.g. 404 or permission error), fall back to 'default' and note it as an assumption.
• Filter to only status: "Active" entries.
• If exactly one active Data Space exists, use it automatically and confirm to the user: "Using Data Space: <name>".
• If multiple active Data Spaces exist, show the list (label + name) and ask the user which to use.

Store the selected name value as DATA_SPACE for all subsequent steps.

Prerequisite check: STDM DMOs

After deploying the helper class (step 1.0), run a quick probe to verify the STDM Data Model Objects exist in Data Cloud:

sf apex run -o <org> -f /dev/stdin << 'APEX'
ConnectApi.CdpQueryInput qi = new ConnectApi.CdpQueryInput();
qi.sql = 'SELECT ssot__Id__c FROM "ssot__AiAgentSession__dlm" LIMIT 1';
try {
    ConnectApi.CdpQueryOutputV2 out = ConnectApi.CdpQuery.queryAnsiSqlV2(qi, '<DATA_SPACE>');
    System.debug('STDM_CHECK:OK rows=' + (out.data != null ? out.data.size() : 0));
} catch (Exception e) {
    System.debug('STDM_CHECK:FAIL ' + e.getMessage());
}
APEX

If STDM_CHECK:FAIL: STDM is not activated. Inform the user and switch to Phase 1-ALT:

STDM (Session Trace Data Model) is not available in this org. To enable: Setup -> Data Cloud -> Data Streams and verify "Agentforce Activity" is active. Proceeding with fallback: test suites + local traces.

If STDM_CHECK:OK, proceed to Phase 1 (STDM path).

Phase 1-ALT: Observe Without STDM (Fallback Path)

When STDM is not available, use test suites and sf agent preview --authoring-bundle with local trace analysis.

1-ALT.1 Run existing test suite (if available)

sf agent test list --json -o <org>
sf agent test run --json --api-name <TestSuiteName> --wait 10 --result-format json -o <org> | tee /tmp/test_run.json
JOB_ID=$(python3 -c "import json; print(json.load(open('/tmp/test_run.json'))['result']['runId'])")
sf agent test results --json --job-id "$JOB_ID" --result-format json -o <org>

1-ALT.2 Derive test utterances from .agent file (if no test suite)

If no test suite exists, derive utterances: one per non-entry subagent (from description: keywords), one per key action, one guardrail test, one multi-turn test.

1-ALT.3 Preview with --authoring-bundle (local traces)

Run each test utterance through preview to generate local trace files:

sf agent preview start --json --authoring-bundle <BundleName> -o <org> | tee /tmp/preview_start.json
SESSION_ID=$(python3 -c "import json; print(json.load(open('/tmp/preview_start.json'))['result']['sessionId'])")

sf agent preview send --json --session-id "$SESSION_ID" --authoring-bundle <BundleName> \
  --utterance "$UTT" -o <org> | tee /tmp/preview_response.json

sf agent preview end --json --session-id "$SESSION_ID" --authoring-bundle <BundleName> -o <org>

Trace file location: .sfdx/agents/{BundleName}/sessions/{sessionId}/traces/{planId}.json

1-ALT.4 Local trace diagnosis

DefaultTopic trace quirk: With --authoring-bundle, the root .topic field often shows "DefaultTopic" even when routing works. Always use NodeEntryStateStep.data.agent_name for the real subagent chain.

Entry answering directly (SMALL_TALK pattern): If start_agent trace shows SMALL_TALK grounding and transition tools visible but none invoked, add "You are a router only. Do NOT answer questions directly." to start_agent instructions.

1-ALT.5 Classify and present

Classify issues using the categories in references/issue-classification.md. After presenting findings, automatically proceed to agent config evidence analysis.

Phase 1: Observe -- Query STDM

Full STDM query details, Apex service deployment, and response parsing: see references/stdm-queries.md

1.0 Deploy helper class (once per org)

Deploy AgentforceOptimizeService Apex class to the org. Check if already deployed first:

sf data query --json --query "SELECT Id, Name FROM ApexClass WHERE Name = 'AgentforceOptimizeService'" -o <org>

If not deployed, copy from skill directory and deploy. See references/stdm-queries.md for full steps.

1.1 Find sessions

Query recent sessions using findSessions(). Parse DEBUG|STDM_RESULT: from the Apex debug log. If findSessions returns empty, switch to Phase 1-ALT.

1.2 Get conversation details

Use getMultipleConversationDetails() for up to 5 sessions (most recent first). Returns turn-by-turn data with messages, steps, topics, and action results.

1.2b Get LLM prompt/response (optional)

When LOW adherence detected, use getLlmStepDetails() to get the actual LLM prompt and response.

1.2c Get aggregated metrics (recommended first step)

Use getAggregatedMetrics() for high-level health dashboard: session rates, top intents, quality distribution, RAG averages.