Skip to content

Commit 690f722

Browse files
scottmojeffcareyhsinghbisht-sfdc
authored
@W-21482430 feat: migrate exp lwr site knowledge docs to skill (#27)
* feat: migrate exp lwr site knowledge docs to skill * feat: small wording adjustment * feat: stricter wording for loading reference docs * feat: incorporate new guest user fix * feat: rename docs to use verb and update some wording * feat: updating wording * feat: wording adjustments * fix: resolve pr comments * fix: rm old references * fix: rm extra comma * fix: make LLM always load the reference docs * fix: wording * feat: incorporate core changes and wording updates * fix: guest user name * fix: stricter wording * fix: revert to repeat instructions * fix: rm "manual" to avoid confusion * fix: updating mcp tools calls instructions * feat: handle component slots * fix: add MCP hints for objectList --------- Co-authored-by: Jeff Carey <jeffrey.carey@salesforce.com> Co-authored-by: Hemant Singh Bisht <hsinghbisht@salesforce.com>
1 parent 287a7e9 commit 690f722

10 files changed

Lines changed: 1441 additions & 178 deletions

‎skills/salesforce-experience-lwr-site/SKILL.md‎

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -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}`

0 commit comments

Comments
 (0)