@salesforce/afv-skills 1.9.1 → 1.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/afv-skills",
-  "version": "1.9.1",
+  "version": "1.11.0",
   "description": "Salesforce skills for Agentforce Vibes",
   "license": "CC-BY-NC-4.0",
   "files": [

package/skills/applying-cms-brand/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: applying-cms-brand
+description: "Extracts, retrieves, and applies CMS brand guidelines (voice, tone, style, colors, typography) to generated content. Use this skill ANY TIME a user request involves branding, brand voice, brand tone, brand guidelines, brand identity, brand styling, or applying a brand to content. Triggers for requests like \"apply my brand\", \"use our brand voice\", \"match our brand guidelines\", \"find my brand\", \"search for brand\", \"get brand instructions\", \"apply brand tone\". Handles the full workflow: searching for brands in Salesforce CMS, extracting brand instructions, and applying brand voice/tone/guidelines to generated content. Does not apply to media/image search (use searching-media skill), logo search, or creating new brand definitions."
+compatibility: "Requires get_brand_instructions and/or search_brands MCP tools"
+metadata:
+  version: "1.0"
+---
+
+# Applying CMS Brand
+
+Universal skill for searching, extracting, and applying CMS brand guidelines to generated content.
+
+## Scope
+
+**This skill is for APPLYING existing brand guidelines from Salesforce CMS to content you generate.**
+
+**Use this skill when the user wants to:**
+- Apply their brand voice/tone to generated content
+- Find and use brand guidelines stored in Salesforce CMS
+- Search for an existing brand in their org
+- Get brand instructions for content generation
+- Ensure generated content matches their brand identity
+- Apply brand styling, tone, or voice to a page, component, or app
+
+**DO NOT use this skill when the user wants to:**
+- Search for images or media (use searching-media skill)
+- Create a new brand from scratch
+- Edit brand definitions in CMS
+- Generate logos or visual brand assets
+
+## Before You Start
+
+**CRITICAL: You must retrieve brand instructions BEFORE generating or modifying any brand.**
+
+When a user requests branded content:
+
+1. **Search for available brands** (if brand is not already identified)
+2. **Extract brand instructions** for the selected brand
+3. **Apply brand guidelines** to all content you generate
+
+**Never generate content first and retrofit branding later.** Brand instructions must inform content generation from the start.
+
+## Workflow Overview
+
+Copy this checklist and track your progress:
+
+```
+CMS Branding Progress:
+- [ ] Step 1: Determine if brand is already identified or needs search
+- [ ] Step 2: Search for brands (if needed) and present options to user
+- [ ] Step 3: Extract brand instructions for the selected brand
+```
+
+## Step 1: Determine Brand Context
+
+Check if the user has already specified which brand to use:
+
+**Brand is known** (user named it, or only one brand exists):
+- Skip to Step 3 (Extract Brand Instructions)
+
+**Brand is unknown** (user says "apply my brand" without specifying which):
+- Proceed to Step 2 (Search for Brands)
+
+## Step 2: Search for Brands
+
+**Tool:** `search_brands`
+
+**Process:**
+
+1. **Determine search query** — Use the user's description, company name, or a general keyword
+2. **Build the request:**
+
+```json
+{
+  "inputs": [{
+    "searchQuery": "keyword or brand name"
+  }]
+}
+```
+
+3. **Call `search_brands`** with the query
+4. **Parse the response** — Extract brand results:
+   - `managedContentId` — Unique ID (use this for extraction in Step 3)
+   - `managedContentKey` — Content key identifier
+   - `title` — Brand display name
+   - `contentUrl` — URL to the brand content
+   - `totalResults` — Number of brands found
+
+### Presenting Brand Results
+
+**If multiple brands found**, use `ask_followup_question` to present options:
+
+```
+I found [N] brands in your CMS. Which one should I apply?
+
+1. [Brand Title 1]
+2. [Brand Title 2]
+3. [Brand Title 3]
+
+Which brand would you like to use?
+```
+
+**If one brand found**, confirm with the user:
+
+```
+I found the brand "[Brand Title]". Should I apply this brand's guidelines to the content?
+```
+
+**If no brands found:**
+
+```
+No brands found in Salesforce CMS. To use branding:
+1. Create a brand in Salesforce CMS (Content Type: sfdc_cms__brand)
+2. Provide brand guidelines directly in this conversation
+
+Would you like to proceed without CMS branding, or provide guidelines manually?
+```
+
+**Never auto-select a brand without confirmation.** Always wait for user choice.
+
+## Step 3: Extract Brand Instructions
+
+**Tool:** `get_brand_instructions`
+
+**Process:**
+
+1. **Call `get_brand_instructions`** — This retrieves the branding extraction prompt template
+2. **Parse the response:**
+   - `promptBody` — Contains the full brand instruction prompt with extraction and application rules
+
+3. **Follow the instructions in `promptBody`** — The prompt template contains specific guidance on:
+   - How to extract brand properties from the brand content
+   - Brand voice and tone rules
+   - Typography and color guidelines
+   - Content formatting rules
+   - Guardrails and restrictions
+
+### What Brand Instructions Contain
+
+The extracted brand instructions typically include:
+
+| Property | Description |
+|---|---|
+| Brand Voice | How the brand speaks (e.g., professional, friendly, authoritative) |
+| Brand Tone | Emotional quality of communication (e.g., confident, warm, empathetic) |
+| Key Messages | Core messaging pillars and value propositions |
+| Content Rules | Dos and don'ts for content generation |
+| Style Guidelines | Typography, color, spacing preferences |
+| Guardrails | Hard restrictions on language, topics, or claims |
+
+## Error Handling
+
+| Error | Response |
+|---|---|
+| `search_brands` unavailable | "Brand search is unavailable. Please provide your brand name or guidelines directly." |
+| `get_brand_instructions` unavailable | "Cannot retrieve brand instructions. Please share your brand guidelines in this conversation and I'll apply them manually." |
+| Org lacks Vibes branding | "CMS branding is not enabled for this org. Contact your admin to enable the Agentforce Vibes branding feature." |
+| Permission denied | "You don't have permission to access CMS brands. Ensure you have Managed Content Authoring permission." |
+| Brand extraction returns empty | "The brand exists but has no configured guidelines. Please add brand properties in CMS or provide guidelines here." |
+
+**Never silently fail.** Always inform the user and offer alternatives.
+
+## Key Principles
+
+1. **Brand first, content second** — Always extract brand instructions before generating content
+2. **Never assume brand guidelines** — Only apply what was explicitly retrieved from CMS
+3. **Respect guardrails absolutely** — Brand content rules are hard constraints, not suggestions
+4. **Confirm brand selection** — Never auto-select a brand without user confirmation
+5. **Show your work** — Tell the user which guidelines you applied and how
+6. **Graceful degradation** — If tools are unavailable, ask for manual guidelines rather than proceeding without branding

package/skills/generating-permission-set/SKILL.md

@@ -177,7 +177,7 @@ Before deploying, verify:
 - [ ] Permissions follow least privilege
 - [ ] No required fields in `<fieldPermissions>`
 - [ ] No duplicate permissions
-- [ ] no lengthy comments
+- [ ] No lengthy comments
 
 ## What Causes Deployment Failure
 

package/skills/integrating-b2b-commerce-open-code-components/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: integrating-b2b-commerce-open-code-components
+description: "Integrate Salesforce B2B Commerce open source components from GitHub into B2B Commerce stores. Use when users mention \"integrate open code components\", \"open source B2B commerce\", \"add open code components\", \"forcedotcom/b2b-commerce-open-source-components\", or want to add open source commerce components to their store. Copies all components and labels so they become available in Experience Builder."
+license: LICENSE.txt has complete terms
+allowed-tools: Bash(git clone:*) Bash(cp:*) Read
+metadata:
+  version: "1.0"
+---
+
+## 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 **creating-b2b-commerce-store** 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
+
+| Error | Message | Action |
+|-------|---------|--------|
+| Store not found | "Store '{name}' not found in org." | List stores again |
+| Git clone failed | "Failed to clone repository. Check internet connection." | Retry or abort |
+| Invalid repo structure | "Repository structure has changed. Expected sfdc_cms__lwc and sfdc_cms__label." | Warn user, abort |
+| File copy failed | "Failed to copy files. Check file permissions." | Show error details |
+
+---
+
+## 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