@salesforce/afv-skills 1.1.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (103) hide show
  1. package/package.json +4 -4
  2. package/skills/agentforce-development/SKILL.md +427 -0
  3. package/skills/agentforce-development/assets/README-legacy.md +89 -0
  4. package/skills/agentforce-development/assets/agent-spec-template.md +90 -0
  5. package/skills/agentforce-development/assets/agents/README.md +45 -0
  6. package/skills/agentforce-development/assets/agents/hello-world.agent +60 -0
  7. package/skills/agentforce-development/assets/agents/multi-topic.agent +105 -0
  8. package/skills/agentforce-development/assets/agents/production-faq.agent +101 -0
  9. package/skills/agentforce-development/assets/agents/production-faq.bundle-meta.xml +4 -0
  10. package/skills/agentforce-development/assets/agents/simple-qa.agent +72 -0
  11. package/skills/agentforce-development/assets/apex/models-api-queueable.cls +225 -0
  12. package/skills/agentforce-development/assets/bundle-meta.xml +23 -0
  13. package/skills/agentforce-development/assets/components/apex-action.agent +52 -0
  14. package/skills/agentforce-development/assets/components/error-handling.agent +58 -0
  15. package/skills/agentforce-development/assets/components/escalation-setup.agent +169 -0
  16. package/skills/agentforce-development/assets/components/flow-action.agent +66 -0
  17. package/skills/agentforce-development/assets/components/n-ary-conditions.agent +110 -0
  18. package/skills/agentforce-development/assets/components/topic-with-actions.agent +40 -0
  19. package/skills/agentforce-development/assets/deterministic-routing.agent +166 -0
  20. package/skills/agentforce-development/assets/escalation-pattern.agent +209 -0
  21. package/skills/agentforce-development/assets/flow-action-lookup.agent +115 -0
  22. package/skills/agentforce-development/assets/hub-and-spoke.agent +104 -0
  23. package/skills/agentforce-development/assets/invocable-apex-template.cls +187 -0
  24. package/skills/agentforce-development/assets/local-info-agent-annotated.agent +355 -0
  25. package/skills/agentforce-development/assets/metadata/basic-prompt-template.promptTemplate-meta.xml +109 -0
  26. package/skills/agentforce-development/assets/metadata/genai-function-apex.xml +92 -0
  27. package/skills/agentforce-development/assets/metadata/genai-function-flow.xml +57 -0
  28. package/skills/agentforce-development/assets/metadata/genai-plugin.xml +72 -0
  29. package/skills/agentforce-development/assets/metadata/http-callout-flow.flow-meta.xml +348 -0
  30. package/skills/agentforce-development/assets/metadata/record-grounded-prompt.promptTemplate-meta.xml +136 -0
  31. package/skills/agentforce-development/assets/minimal-starter.agent +42 -0
  32. package/skills/agentforce-development/assets/patterns/README.md +254 -0
  33. package/skills/agentforce-development/assets/patterns/action-callbacks.agent +178 -0
  34. package/skills/agentforce-development/assets/patterns/advanced-input-bindings.agent +141 -0
  35. package/skills/agentforce-development/assets/patterns/bidirectional-routing.agent +156 -0
  36. package/skills/agentforce-development/assets/patterns/critical-input-collection.agent +244 -0
  37. package/skills/agentforce-development/assets/patterns/delegation-routing.agent +89 -0
  38. package/skills/agentforce-development/assets/patterns/lifecycle-events.agent +127 -0
  39. package/skills/agentforce-development/assets/patterns/llm-controlled-actions.agent +184 -0
  40. package/skills/agentforce-development/assets/patterns/multi-step-workflow.agent +282 -0
  41. package/skills/agentforce-development/assets/patterns/open-gate-routing.agent +286 -0
  42. package/skills/agentforce-development/assets/patterns/procedural-instructions.agent +273 -0
  43. package/skills/agentforce-development/assets/patterns/prompt-template-action.agent +188 -0
  44. package/skills/agentforce-development/assets/patterns/system-instruction-overrides.agent +293 -0
  45. package/skills/agentforce-development/assets/prompt-rag-search.agent +131 -0
  46. package/skills/agentforce-development/assets/template-multi-topic.agent +160 -0
  47. package/skills/agentforce-development/assets/template-single-topic.agent +81 -0
  48. package/skills/agentforce-development/assets/verification-gate.agent +208 -0
  49. package/skills/agentforce-development/references/action-prompt-templates.md +164 -0
  50. package/skills/agentforce-development/references/actions-reference.md +592 -0
  51. package/skills/agentforce-development/references/agent-access-guide.md +72 -0
  52. package/skills/agentforce-development/references/agent-design-and-spec-creation.md +1010 -0
  53. package/skills/agentforce-development/references/agent-metadata-and-lifecycle.md +575 -0
  54. package/skills/agentforce-development/references/agent-script-core-language.md +1218 -0
  55. package/skills/agentforce-development/references/agent-topic-map-diagrams.md +323 -0
  56. package/skills/agentforce-development/references/agent-user-setup.md +526 -0
  57. package/skills/agentforce-development/references/agent-validation-and-debugging.md +803 -0
  58. package/skills/agentforce-development/references/known-issues.md +353 -0
  59. package/skills/agentforce-development/references/minimal-examples.md +67 -0
  60. package/skills/agentforce-development/references/production-gotchas.md +279 -0
  61. package/skills/agentforce-development/references/salesforce-cli-for-agents.md +393 -0
  62. package/skills/agentforce-development/references/version-history.md +23 -0
  63. package/skills/generate-permission-set/SKILL.md +174 -0
  64. package/skills/salesforce-custom-application/SKILL.md +1 -2
  65. package/skills/salesforce-custom-field/SKILL.md +0 -4
  66. package/skills/salesforce-custom-tab/SKILL.md +84 -8
  67. package/skills/salesforce-experience-lwr-site/SKILL.md +196 -0
  68. package/skills/salesforce-experience-lwr-site/docs/bootstrap-template-byo-lwr.md +224 -0
  69. package/skills/salesforce-experience-lwr-site/docs/configure-content-brandingSet.md +131 -0
  70. package/skills/salesforce-experience-lwr-site/docs/configure-content-route.md +232 -0
  71. package/skills/salesforce-experience-lwr-site/docs/configure-content-themeLayout.md +141 -0
  72. package/skills/salesforce-experience-lwr-site/docs/configure-content-view.md +233 -0
  73. package/skills/salesforce-experience-lwr-site/docs/configure-guest-sharing-rules.md +42 -0
  74. package/skills/salesforce-experience-lwr-site/docs/handle-component-and-region-ids.md +27 -0
  75. package/skills/salesforce-experience-lwr-site/docs/handle-ui-components.md +215 -0
  76. package/skills/salesforce-flow/SKILL.md +2 -2
  77. package/skills/salesforce-fragment/SKILL.md +85 -10
  78. package/skills/salesforce-lightning-app-build/SKILL.md +102 -10
  79. package/skills/apex-class/SKILL.md +0 -253
  80. package/skills/apex-class/examples/AccountDeduplicationBatch.cls +0 -148
  81. package/skills/apex-class/examples/AccountSelector.cls +0 -193
  82. package/skills/apex-class/examples/AccountService.cls +0 -201
  83. package/skills/apex-class/templates/abstract.cls +0 -128
  84. package/skills/apex-class/templates/batch.cls +0 -125
  85. package/skills/apex-class/templates/domain.cls +0 -102
  86. package/skills/apex-class/templates/dto.cls +0 -108
  87. package/skills/apex-class/templates/exception.cls +0 -51
  88. package/skills/apex-class/templates/interface.cls +0 -25
  89. package/skills/apex-class/templates/queueable.cls +0 -92
  90. package/skills/apex-class/templates/schedulable.cls +0 -75
  91. package/skills/apex-class/templates/selector.cls +0 -92
  92. package/skills/apex-class/templates/service.cls +0 -69
  93. package/skills/apex-class/templates/utility.cls +0 -97
  94. package/skills/apex-test-class/SKILL.md +0 -101
  95. package/skills/apex-test-class/references/assertion-patterns.md +0 -209
  96. package/skills/apex-test-class/references/async-testing.md +0 -276
  97. package/skills/apex-test-class/references/mocking-patterns.md +0 -219
  98. package/skills/apex-test-class/references/test-data-factory.md +0 -176
  99. package/skills/deployment-readiness-check/SKILL.md +0 -257
  100. package/skills/deployment-readiness-check/assets/deployment_checklist.md +0 -286
  101. package/skills/deployment-readiness-check/references/rollback_procedures.md +0 -308
  102. package/skills/deployment-readiness-check/scripts/check_metadata.sh +0 -207
  103. package/skills/salesforce-experience-site/SKILL.md +0 -178
@@ -0,0 +1,174 @@
1
+ ---
2
+ name: generate-permission-set
3
+ description: Generates correct, deployable Salesforce permission set metadata (PermissionSet XML) with object, field, user, and app permissions. Use this skill when creating or editing permission set metadata, object permissions, field-level security (FLS), tab visibility, or deploying permission sets.
4
+ compatibility: Salesforce Metadata API v60.0+
5
+ metadata:
6
+ author: afv-library
7
+ version: "1.0"
8
+ ---
9
+
10
+ ## When to Use This Skill
11
+
12
+ Use when generating or editing permission set metadata, or when granting object, field, user, and app permissions.
13
+
14
+ ## Step 1: Define Core Properties
15
+
16
+ Start by defining the required permission set properties:
17
+
18
+ ```xml
19
+ <PermissionSet xmlns="http://soap.sforce.com/2006/04/metadata">
20
+ <fullName>YourPermissionSetName</fullName>
21
+ <label>Display Name for Administrators</label>
22
+ <description>Clear description of purpose and intended audience</description>
23
+ </PermissionSet>
24
+ ```
25
+
26
+ **Naming conventions:**
27
+ - Use descriptive API names (e.g., `Sales_Manager_Access`)
28
+
29
+ ## Step 2: Configure Object Permissions
30
+
31
+ Add CRUD permissions for standard and custom objects:
32
+
33
+ ```xml
34
+ <objectPermissions>
35
+ <allowCreate>true</allowCreate>
36
+ <allowRead>true</allowRead>
37
+ <allowEdit>true</allowEdit>
38
+ <allowDelete>false</allowDelete>
39
+ <modifyAllRecords>false</modifyAllRecords>
40
+ <viewAllRecords>false</viewAllRecords>
41
+ <viewAllFields>false</viewAllFields>
42
+ <object>Account</object>
43
+ </objectPermissions>
44
+ ```
45
+
46
+ ## Step 3: Set Field-Level Security
47
+
48
+ Define field permissions for sensitive or custom fields:
49
+
50
+ ```xml
51
+ <fieldPermissions>
52
+ <editable>true</editable>
53
+ <readable>true</readable>
54
+ <field>Account.SSN__c</field>
55
+ </fieldPermissions>
56
+ ```
57
+
58
+ **Important:**
59
+ - 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.
60
+ - Before adding any field, confirm from the object metadata that the field exists and is not required
61
+ - A field is required when its metadata contains `<required>true</required>`:
62
+ - Formula fields cannot be editable
63
+ - Master-detail fields are required fields on the child (detail) object
64
+
65
+ ```xml
66
+ <fields>
67
+ <fullName>FieldName__c</fullName>
68
+ <required>true</required>
69
+ </fields>
70
+ ```
71
+ - Use format `ObjectName.FieldName` for field references
72
+ - Set both readable and editable to true when the user needs edit access; editable implies readable
73
+ - If all fields should be visible, can alternatively enable the "viewAllFields" object permission
74
+
75
+ ## Step 4: Grant User Permissions
76
+
77
+ Add system-level permissions for features and capabilities:
78
+
79
+ ```xml
80
+ <userPermissions>
81
+ <enabled>true</enabled>
82
+ <name>ApiEnabled</name>
83
+ </userPermissions>
84
+ <userPermissions>
85
+ <enabled>true</enabled>
86
+ <name>RunReports</name>
87
+ </userPermissions>
88
+ ```
89
+
90
+ **Common permissions:**
91
+ - `ApiEnabled`: API access
92
+ - `ViewSetup`: View Setup menu
93
+ - `ManageUsers`: User management
94
+ - `RunReports`: Report execution
95
+
96
+ **Security review required for:**
97
+ - `ViewAllData`: Read all records
98
+ - `ModifyAllData`: Edit all records
99
+ - `ManageUsers`: User administration
100
+
101
+ ## Step 5: Configure App and Tab Visibility
102
+
103
+ Make applications and tabs visible to users:
104
+
105
+ ```xml
106
+ <applicationVisibilities>
107
+ <application>Sales_Console</application>
108
+ <visible>true</visible>
109
+ </applicationVisibilities>
110
+ <tabSettings>
111
+ <tab>CustomTab__c</tab>
112
+ <visibility>Visible</visibility>
113
+ </tabSettings>
114
+ ```
115
+
116
+ **Application visibility options:**
117
+ - <visible> can be true or false
118
+
119
+ **Tab visibility options:**
120
+ - `Visible`: The tab is available on the All Tabs page and appears in the visible tabs for its associated app. Can be customized.
121
+ - `Available`: The tab is available on the All Tabs page. Individual users can customize their display to make the tab visible in any app
122
+ - `None`: Not visible
123
+
124
+ **CRITICAL - Tab Naming:**
125
+ - Custom object tabs: MUST include the __c suffix (e.g., MyCustomObject__c)
126
+ - Standard object tabs: Use the object name with "standard-" prefix (e.g., standard-Account, standard-Contact)
127
+ - The tab name matches the object's API name exactly
128
+
129
+ ## Step 6: Add Apex and Visualforce Access (Optional)
130
+
131
+ Grant access to custom code:
132
+
133
+ ```xml
134
+ <classAccesses>
135
+ <apexClass>CustomController</apexClass>
136
+ <enabled>true</enabled>
137
+ </classAccesses>
138
+ <pageAccesses>
139
+ <apexPage>CustomPage</apexPage>
140
+ <enabled>true</enabled>
141
+ </pageAccesses>
142
+ ```
143
+
144
+ ## Step 7: Set License and Record Type Settings (Optional)
145
+
146
+ Specify license requirements and record type visibility:
147
+
148
+ ```xml
149
+ <license>Salesforce</license>
150
+ <hasActivationRequired>false</hasActivationRequired>
151
+ <recordTypeVisibilities>
152
+ <recordType>Account.Business</recordType>
153
+ <visible>true</visible>
154
+ <default>true</default>
155
+ </recordTypeVisibilities>
156
+ ```
157
+
158
+ ## Validation Checklist
159
+
160
+ Before deploying, verify:
161
+ - [ ] fullName, label, description set
162
+ - [ ] Permissions follow least privilege
163
+ - [ ] No required fields in `<fieldPermissions>`
164
+ - [ ] No duplicate permissions
165
+ - [ ] no lengthy comments
166
+
167
+ ## What Causes Deployment Failure
168
+
169
+ - **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.
170
+ - **Incorrect API names:** Using the wrong name or missing suffixes (e.g. missing `__c` for custom objects, fields, tabs) cause failure.
171
+
172
+ ## Deployment
173
+
174
+ Deploy using Salesforce CLI
@@ -43,7 +43,7 @@ Custom applications (Lightning Apps) that group tabs and functionality to provid
43
43
  - **description**: Brief description of the application's purpose
44
44
  - **tabs**: Array of tab names to include
45
45
  - **utilityBar**: API name of the Utility Bar configuration
46
- - **brand**: ⚠️ HIGHLY RECOMMENDED - Branding configuration object (headerColor, shouldOverrideOrgTheme, footerColor, primaryTabColor)
46
+ - **brand**: ⚠️ HIGHLY RECOMMENDED - Branding configuration object (headerColor, shouldOverrideOrgTheme, footerColor)
47
47
  - **actionOverrides**: ⚠️ REQUIRED when custom record pages exist - Action override configuration (actionName, content, formFactor, type, pageOrSobjectType)
48
48
  - **profileActionOverrides**: Profile-specific action overrides (actionName, content, formFactor, pageOrSobjectType, type, profile)
49
49
  - **isNavAutoTempTabsDisabled**: Navigation behavior setting (default: false)
@@ -86,7 +86,6 @@ Custom applications (Lightning Apps) that group tabs and functionality to provid
86
86
  - **brand.headerColor**: Header bar color in hex format (e.g., "#0070D2") - RECOMMENDED
87
87
  - **brand.shouldOverrideOrgTheme**: Override organization theme (true/false) - Default: false
88
88
  - **brand.footerColor**: Footer color in hex format
89
- - **brand.primaryTabColor**: Primary tab color in hex format
90
89
 
91
90
  ### Action Overrides (CRITICAL - DO NOT SKIP)
92
91
  **IMPORTANT**: Action overrides MUST be created for every custom object tab that has a record page generated by flexipage expert.
@@ -42,10 +42,6 @@ Every generated field must include these tags:
42
42
  | `<description>` | Mandatory | State the business "why" behind the field |
43
43
  | `<inlineHelpText>` | Mandatory | Provide actionable guidance for the end-user. Must add value beyond the label (e.g., "Enter the value in USD including tax" instead of just "The amount") |
44
44
 
45
- ### XML Comments — NEVER Before Root Element
46
-
47
- **NEVER place XML comments (`<!-- ... -->`) before the root `<CustomField>` element in metadata XML files.** Comments between the XML declaration and `<CustomField>` cause a `ConversionError` during deployment. Comments inside the root element are safe.
48
-
49
45
  ### External ID Configuration
50
46
 
51
47
  **Trigger:** If the user mentions "integration," "importing data," "external system ID," or "unique key from [System Name]," set `<externalId>true</externalId>`.
@@ -27,27 +27,99 @@ Custom tabs for navigating to objects, web content, or Visualforce pages within
27
27
  ## ⚙️ Required Properties
28
28
 
29
29
  ### Core Tab Properties
30
- - **label**: Display name of the tab
31
- - **fullName**: API name of the object (for object tabs)
30
+ - **customObject**: `true` for custom object tabs, `false` for all others.
31
+ - **motif**: Tab icon style — choose a motif that semantically matches the object's purpose. Do NOT reuse the same motif for every tab.
32
+ - **label**: Display name (required for non-object tabs ONLY; object tabs inherit label from the object)
32
33
  - **url**: Web URL (for web tabs)
33
34
  - **page**: Visualforce page name (for Visualforce tabs)
34
35
 
36
+
37
+ ### 🚨 STRICT ELEMENT ALLOWLIST — READ THIS FIRST
38
+
39
+ **The root element MUST always be `<CustomTab>` (NOT `<Tab>`).** The XML namespace must be `xmlns="http://soap.sforce.com/2006/04/metadata"`.
40
+
41
+ Only the elements listed below are valid. **Any element not on this list WILL cause a deployment error.**
42
+
43
+ | Tab Type | ONLY these elements are allowed (nothing else) |
44
+ |---|---|
45
+ | **Object tabs** | `<customObject>` (required, set to `true`), `<motif>` (required), `<description>` (optional) |
46
+ | **Web tabs** | `<customObject>` (required, set to `false`), `<label>` (required), `<motif>` (required), `<url>` (required), `<urlEncodingKey>` (required, set to `UTF-8`), `<description>` (optional), `<frameHeight>` (optional) |
47
+ | **Visualforce tabs** | `<customObject>` (required, set to `false`), `<label>` (required), `<motif>` (required), `<page>` (required), `<description>` (optional) |
48
+
49
+ ### ⚠️ FORBIDDEN ELEMENTS (every one of these causes a deployment error)
50
+ `<sobjectName>`, `<name>`, `<fullName>`, `<apiVersion>`, `<isHidden>`, `<tabVisibility>`, `<type>`, `<mobileReady>`, `<urlFrameHeight>`, `<urlType>`, `<urlRedirect>`, `<encodingKey>`, `<height>`, `<auraComponent>`
51
+
52
+ Also forbidden:
53
+ - `<label>` on object tabs (object tabs inherit their label from the custom object)
54
+ - `<page>` on web tabs (only for Visualforce tabs)
55
+ - Empty elements like `<page></page>` or `<description></description>`
56
+ - Any element not in the allowlist table above
57
+
35
58
  ## 🔧 Tab Types
36
59
 
37
60
  ### Object Tabs
38
61
  - **Purpose**: Navigate to custom or standard objects
39
- - **Required**: `fullName` property (set to object API name)
40
- - **Example**: `<fullName>CustomObject__c</fullName>`
62
+ - **File name** determines the object: `{ObjectApiName}.tab-meta.xml` (e.g., `Space_Station__c.tab-meta.xml`)
63
+ - **Required elements**: `<customObject>true</customObject>` and `<motif>`
64
+ - **Correct example** (for a Space_Station__c.tab-meta.xml):
65
+ ```xml
66
+ <?xml version="1.0" encoding="UTF-8"?>
67
+ <CustomTab xmlns="http://soap.sforce.com/2006/04/metadata">
68
+ <customObject>true</customObject>
69
+ <motif>Custom39: Telescope</motif>
70
+ </CustomTab>
71
+ ```
72
+ - **Correct example** (for a Supply__c.tab-meta.xml — note different motif):
73
+ ```xml
74
+ <?xml version="1.0" encoding="UTF-8"?>
75
+ <CustomTab xmlns="http://soap.sforce.com/2006/04/metadata">
76
+ <customObject>true</customObject>
77
+ <motif>Custom98: Truck</motif>
78
+ </CustomTab>
79
+ ```
80
+ - **❌ WRONG** — do NOT add `<sobjectName>`, `<name>`, `<fullName>`, or `<label>`:
81
+ ```xml
82
+ <CustomTab xmlns="http://soap.sforce.com/2006/04/metadata">
83
+ <sobjectName>Space_Station__c</sobjectName> <!-- DEPLOYMENT ERROR -->
84
+ <label>Space Station</label> <!-- DEPLOYMENT ERROR on object tabs -->
85
+ <customObject>true</customObject>
86
+ <motif>Custom57: Desert</motif>
87
+ </CustomTab>
88
+ ```
41
89
 
42
90
  ### Web Tabs
43
91
  - **Purpose**: Link to external websites or web applications
44
- - **Required**: `url` property
45
- - **Example**: `<url>https://example.com</url>`
92
+ - **File name**: Use a descriptive name: `{TabName}.tab-meta.xml` (e.g., `Knowledge_Base.tab-meta.xml`)
93
+ - **COPY THIS EXACT TEMPLATE** — only replace the placeholder values. Do NOT add, remove, or rename any XML elements:
94
+ ```xml
95
+ <?xml version="1.0" encoding="UTF-8"?>
96
+ <CustomTab xmlns="http://soap.sforce.com/2006/04/metadata">
97
+ <customObject>false</customObject>
98
+ <description>REPLACE_WITH_DESCRIPTION</description>
99
+ <frameHeight>600</frameHeight>
100
+ <label>REPLACE_WITH_LABEL</label>
101
+ <motif>REPLACE_WITH_MOTIF</motif>
102
+ <url>REPLACE_WITH_URL</url>
103
+ <urlEncodingKey>UTF-8</urlEncodingKey>
104
+ </CustomTab>
105
+ ```
106
+ - **These 7 elements above are the ONLY elements allowed in a web tab file.** Do not add ANY other elements.
107
+ - The `<description>` element is optional — you may remove it if not needed, but do not add anything else.
46
108
 
47
109
  ### Visualforce Tabs
48
110
  - **Purpose**: Access custom Visualforce pages
49
- - **Required**: `page` property
50
- - **Example**: `<page>CustomPage</page>`
111
+ - **File name**: `{TabName}.tab-meta.xml` (e.g., `Custom_Page_Tab.tab-meta.xml`)
112
+ - **Required elements**: `<customObject>false</customObject>`, `<label>`, `<motif>`, `<page>`
113
+ - **Correct example**:
114
+ ```xml
115
+ <?xml version="1.0" encoding="UTF-8"?>
116
+ <CustomTab xmlns="http://soap.sforce.com/2006/04/metadata">
117
+ <customObject>false</customObject>
118
+ <label>Custom Page</label>
119
+ <motif>Custom46: Computer</motif>
120
+ <page>CustomPage</page>
121
+ </CustomTab>
122
+ ```
51
123
 
52
124
  ## 🎨 Tab Configuration
53
125
 
@@ -72,7 +144,11 @@ Custom tabs for navigating to objects, web content, or Visualforce pages within
72
144
  ## ✅ Best Practices
73
145
  - Use clear, descriptive tab labels
74
146
  - Choose appropriate tab types for functionality
147
+ - **Select a unique, contextually relevant motif for each tab** — do not default every tab to the same icon
75
148
  - Consider user experience and navigation flow
76
149
  - Test tab functionality across different applications
77
150
  - Ensure proper permissions and visibility settings
78
151
  - Follow consistent naming conventions
152
+ - Object tab files MUST only contain `<customObject>true</customObject>` and `<motif>` — nothing else
153
+ - Web tab files MUST only contain: `<customObject>false</customObject>`, `<label>`, `<motif>`, `<url>`, `<urlEncodingKey>`, and optionally `<description>`, `<frameHeight>` — nothing else
154
+ - Never include `<isHidden>`, `<tabVisibility>`, `<type>`, `<mobileReady>`, or empty elements
@@ -0,0 +1,196 @@
1
+ ---
2
+ name: salesforce-experience-lwr-site
3
+ description: Creates, modifies, or manages Salesforce Experience Cloud LWR sites via DigitalExperience metadata. Always trigger when users mention Experience sites, LWR sites, DigitalExperience, Experience Cloud, community sites, portals, creating pages, adding routes, views, theme layouts, branding sets, previewing sites, or any DigitalExperience bundle work. Also use when users mention specific content types like sfdc_cms__route, sfdc_cms__themeLayout, etc. or when troubleshooting site deployment.
4
+ ---
5
+
6
+ # Experience LWR Site Builder
7
+
8
+ Build and configure Salesforce Experience Cloud Lightning Web Runtime (LWR) sites via metadata (DigitalExperienceConfig, DigitalExperienceBundle, Network, CustomSite, CMS contents).
9
+
10
+ ## Table of Contents
11
+
12
+ - When to Use
13
+ - Critical Rules
14
+ - Core Site Properties
15
+ - Project Structure in DigitalExperienceBundle Format
16
+ - Reference Docs
17
+ - Common Workflows
18
+
19
+ ## When to Use
20
+
21
+ When working with Experience LWR sites:
22
+
23
+ - Creating and scaffolding new LWR site
24
+ - Adding pages (routes + views)
25
+ - Configuring LWC components, layouts, themes, or branding styles
26
+ - Setting up guest user access (public sites)
27
+ - Troubleshoot deployment errors related to Experience LWR Sites
28
+
29
+ **Supported Template**: Build Your Own (LWR) - `talon-template-byo`
30
+
31
+ - More templates to support in the future.
32
+
33
+ ## Critical Rules
34
+
35
+ 1. Before using any MCP tool, make sure they're actually available. If a tool is missing for the current task, let the user know and pause the current workflow.
36
+ 2. **ALWAYS** load the relevant reference docs before doing anything.
37
+ 3. **ALWAYS** strictly follow workflows in [Common Workflows](#common-workflows) that match user's requirements. The instructions there should override any conflicting global rules and should have the highest priority over your existing knowledge.
38
+ 4. Flexipage is abstracted away for newer LWR sites with DigitalExperienceBundle, so **NEVER** use any Flexipage-related MCP tool or skills to handle LWR sites' contents.
39
+
40
+ ## Core Site Properties
41
+
42
+ Before doing anything else, note down the following properties from the local project if available as they will be used for various operations. Check with the user if any of the following is missing:
43
+
44
+ - **Site name**: Required. (e.g., `'My Community'`).
45
+ - **URL path prefix**: Optional. Alphanumeric characters only. Convert from site name if not provided (e.g., `'mycommunity'`) and verify with the user for the converted value.
46
+ - **Template type devName**: `talon-template-byo`.
47
+
48
+ ## Project Structure in DigitalExperienceBundle Format
49
+
50
+ ### Site Metadata
51
+
52
+ - DigitalExperienceConfig
53
+ - `digitalExperienceConfigs/{siteName}1.digitalExperienceConfig-meta.xml`
54
+ - DigitalExperienceBundle
55
+ - `digitalExperiences/site/{siteName}1/{siteName}1.digitalExperience-meta.xml`
56
+ - Network
57
+ - `networks/{siteName}.network-meta.xml`
58
+ - CustomSite
59
+ - `sites/{siteName}.site-meta.xml`
60
+
61
+ ### DigitalExperience Contents
62
+
63
+ - `digitalExperiences/site/{siteName}1/sfdc_cms__*/{contentApiName}/*`
64
+ - These are the content components defining routes, views, theme layouts, etc. Each component must have a `_meta.json` and `content.json` file.
65
+
66
+ #### Content Type Descriptions
67
+
68
+ | Content Type | Description | When to Use |
69
+ |-|-|-|
70
+ | `sfdc_cms__site` | Root site configuration containing site-wide settings | Required for every site; one per site |
71
+ | `sfdc_cms__appPage` | Application page container that groups routes and views | Required; defines the app shell |
72
+ | `sfdc_cms__route` | URL routing definition mapping paths to views | Create one for each page/URL path |
73
+ | `sfdc_cms__view` | Page layout and component structure | Create one for each route; defines page content. Also use to edit existing views (e.g., adding/removing components on a specific page) |
74
+ | `sfdc_cms__brandingSet` | Brand colors, fonts, and styling tokens | Required; defines site-wide styling |
75
+ | `sfdc_cms__languageSettings` | Language and localization configuration | Required; defines supported languages |
76
+ | `sfdc_cms__mobilePublisherConfig` | Mobile app publishing settings | Required for mobile app deployment |
77
+ | `sfdc_cms__theme` | Theme definition referencing layouts and branding | Required; one per site |
78
+ | `sfdc_cms__themeLayout` | Page layout templates used by views | Create layouts for different page structures. Also use to edit existing theme layouts (e.g., updating theme layout, add a component that's persistent across pages) |
79
+
80
+ **Important:** Creating any new pages require BOTH `sfdc_cms__route` AND `sfdc_cms__view`.
81
+
82
+ ## References
83
+
84
+ Reference docs within the skill directory. Note that these are **local** and not MCP.
85
+
86
+ - [bootstrap-template-byo-lwr.md](docs/bootstrap-template-byo-lwr.md) - Site creation, template defaults
87
+ - [configure-content-route.md](docs/configure-content-route.md) - Route creation (custom/object pages)
88
+ - [configure-content-view.md](docs/configure-content-view.md) - View creation/editing (custom/object pages)
89
+ - [configure-content-themeLayout.md](docs/configure-content-themeLayout.md) - Theme layout creation + theme sync
90
+ - [configure-content-brandingSet.md](docs/configure-content-brandingSet.md) - Branding with color patterns/WCAG
91
+ - [handle-component-and-region-ids.md](docs/handle-component-and-region-ids.md) - **UUID generation (CRITICAL)** for component and region ids used in views and themeLayout.
92
+ - [handle-ui-components.md](docs/handle-ui-components.md) - Component discovery, schemas, insertion, configuration
93
+
94
+ ## Common Workflows
95
+
96
+ - See [References](#references) for detailed capabilities.
97
+ - **Always** follow the steps defined in the workflows sequentially whether the task is small, big, quick, or complex.
98
+
99
+ ### Creating a New Site
100
+
101
+ **Rules**:
102
+
103
+ - **NEVER** generate the files manually.
104
+
105
+ **Steps** (Follow the steps sequentially. Do not skip any step before proceeding):
106
+
107
+ - [ ] **ALWAYS** read [bootstrap-template-byo-lwr.md](docs/bootstrap-template-byo-lwr.md) within the skill directory. Do not proceed to the next step without loading the file.
108
+ - [ ] Follow the bootstrap doc strictly on site creation
109
+
110
+ ### Creating and Editing Standard or Object Pages
111
+
112
+ **Steps** (Follow the steps sequentially. Do not skip any step before proceeding):
113
+
114
+ - [ ] Load [configure-content-route.md](docs/configure-content-route.md)
115
+ - [ ] Load [configure-content-view.md](docs/configure-content-view.md)
116
+ - [ ] Load [handle-component-and-region-ids.md](docs/handle-component-and-region-ids.md)
117
+ - [ ] Follow the instructions of the above docs strictly to accomplish user's goal
118
+
119
+ ### Adding UI Components to Pages
120
+
121
+ **Steps** (Follow the steps sequentially. Do not skip any step before proceeding):
122
+
123
+ - [ ] Read and follow [handle-ui-components.md](docs/handle-ui-components.md) to add LWCs to LWR sites.
124
+ - [ ] Load and follow [handle-component-and-region-ids.md](docs/handle-component-and-region-ids.md) to handle id generation
125
+ - [ ] Read and follow [configure-content-themeLayout.md](docs/configure-content-themeLayout.md) if a component has one of the following requirements:
126
+ - needs to be "sticky" and persistent across pages
127
+ - is used as a theme layout
128
+
129
+ ### Creating Theme Layouts
130
+
131
+ **Steps** (Follow the steps sequentially. Do not skip any step before proceeding):
132
+
133
+ - [ ] Read and follow strictly [configure-content-themeLayout.md](docs/configure-content-themeLayout.md).
134
+
135
+ ### Configuring Branding
136
+
137
+ **Steps** (Follow the steps sequentially. Do not skip any step before proceeding):
138
+
139
+ - [ ] Read and follow strictly [configure-content-brandingSet.md](docs/configure-content-brandingSet.md) to configure background colors, foreground colors, button colors, and other branding colors that affect all pages.
140
+
141
+ ### CUD Operations on DigitalExperience Contents
142
+
143
+ - Users can perform create, update, delete operations on DigitalExperience Contents.
144
+
145
+ **Steps** (Follow the steps sequentially. Do not skip any step before proceeding):
146
+
147
+ - [ ] Determine what content types the user wants to modify
148
+ - [ ] Read and follow strictly the reference doc related to the target content types if the doc exists. e.g., if modifying `sfdc_cms__route`, load [configure-content-route.md](docs/configure-content-route.md).
149
+ - [ ] **Always** Read [handle-component-and-region-ids.md](docs/handle-component-and-region-ids.md) if creating or modifying view or theme layout
150
+ - [ ] **Always** Call `execute_metadata_action` to get the schema and examples for that content type **after** loading the corresponding reference docs.
151
+ - **Call once per content type per user request**: If you're creating/modifying multiple items of the same content type (e.g., creating 3 routes), you only need to call `execute_metadata_action` ONCE for that content type. Reuse the schema and examples for all items of that type within the same user request.
152
+ - For each unique content type you need to work with, **always** call `execute_metadata_action` using the following:
153
+
154
+ ```json
155
+ {
156
+ "metadataType": "ExperienceSiteLwr",
157
+ "actionName": "getSiteContentMetadata",
158
+ "parameters": {
159
+ "contentType": "<content type from table above>",
160
+ "shouldIncludeExamples": true
161
+ }
162
+ }
163
+ ```
164
+
165
+ ### Retrieving Site URLs After Deployment
166
+
167
+ After successfully deploying the site using `sf project deploy`, use the `execute_metadata_action` MCP tool to get the preview and builder URLs:
168
+
169
+ ```json
170
+ {
171
+ "metadataType": "ExperienceSiteLwr",
172
+ "actionName": "getSiteUrls",
173
+ "parameters": {
174
+ "siteDevName": "<site developer name>"
175
+ }
176
+ }
177
+ ```
178
+
179
+ The site developer name can be found in the CustomSite filename (e.g., `sites/MySite.site-meta.xml` → developer name is `MySite`).
180
+
181
+ If the site is not found, an error message will be returned indicating that the site may not be deployed. Ensure the site has been successfully deployed before calling this action.
182
+
183
+ ### Validation & Deployment
184
+
185
+ Use `sf` CLI to validate and deploy. Access help docs by attaching `--help`, e.g.:
186
+
187
+ - `sf project deploy --help`
188
+ - `sf project deploy validate --help`
189
+
190
+ Note that metadata types are space-delimited.
191
+
192
+ **Validate**:
193
+ `sf project deploy validate --metadata DigitalExperienceBundle DigitalExperience DigitalExperienceConfig Network CustomSite --target-org ${usernameOrAlias}`
194
+
195
+ **Deploy**:
196
+ `sf project deploy start --metadata DigitalExperienceBundle DigitalExperience DigitalExperienceConfig Network CustomSite --target-org ${usernameOrAlias}`