From d3928eb44c4e21aa759fa7db416d9f5dfcc84389 Mon Sep 17 00:00:00 2001
From: sowmya-sriram <sowmya.sriram@salesforce.com>
Date: Tue, 17 Mar 2026 13:39:17 +0530
Subject: [PATCH] @W-21480316 updated fragment skill.md (#38)

* updated fragment skill.md

* updated actionNames

---------

Co-authored-by: Hemant Singh Bisht <hsinghbisht@salesforce.com>
---
 skills/salesforce-fragment/SKILL.md | 95 ++++++++++++++++++++++++++---
 1 file changed, 85 insertions(+), 10 deletions(-)

diff --git a/skills/salesforce-fragment/SKILL.md b/skills/salesforce-fragment/SKILL.md
index d072b3d..8e764f9 100644
--- a/skills/salesforce-fragment/SKILL.md
+++ b/skills/salesforce-fragment/SKILL.md
@@ -16,7 +16,7 @@ Use this skill when you need to:
 # Fragment Generation Guide
 
 ## 📋 Overview
-Fragments are reusable pieces of UI similar to templates, with placeholders for actual data values. The purpose of this file is to assist developers in creating and editing fragments. 
+Fragments are reusable pieces of UI similar to templates, with placeholders for actual data values. The purpose of this file is to assist developers in creating and editing fragments.
 
 ## 🎯 Purpose
 Fragments render data in a structured and unified way across various Salesforce experiences like Slack, Mobile, LEX etc
@@ -24,19 +24,94 @@ Fragments render data in a structured and unified way across various Salesforce
 ## ⚙️ Composition
 A fragment is a UEM (Unified Experience Model) tree of blocks and regions. The fragment you return must follow the Typescript interfaces below:
 
-- **Block definition**: Follow `{namespace}}/{{blockName}` convention and use the same value as the block's definition when it appears in a fragment.
-
 ```ts
 interface BlockType {
-  type: 'block'
-  definition: string  // {namespace}/{blockName}, e.g. "bcx/heading"
-  attributes?: Record<string, any>
-  children?: (BlockType | RegionType)[]
+    type: 'block'
+    definition: string  // {namespace}/{blockName}
+    attributes?: Record<string, any>
+    children?: (BlockType | RegionType)[]
 }
 
 interface RegionType {
-  type: 'region'
-  name: string
-  children: BlockType[]
+    type: 'region'
+    name: string
+    children: BlockType[]
 }
 ```
+
+---
+
+## 🔧 Available Metadata Actions
+
+### When to Use Each Action
+
+#### discoverUiComponents
+
+**When:** You want to see what block components are available for fragments.
+
+**Purpose:** Discover the palette of available blocks that can be used in fragment composition.
+
+**Input Parameters:**
+- `pageType` (required): "FRAGMENT"
+- `pageContext` (optional): JSON object - not required for FRAGMENT type
+- `searchQuery` (optional): String to filter components by name or description
+
+**Returns:** List of components with:
+- `definition`: Fully qualified name (e.g., "namespace/definiton")
+- `description`: Component description
+- `label`: Human-readable label
+- `attributes`: Optional attribute metadata
+
+**Use for:** Finding available blocks before building your fragment structure.
+
+#### getUiComponentSchemas
+
+**When:** You know which components you want but need to understand their properties and attributes.
+
+**Purpose:** Get detailed JSON schemas for component configuration, including property types, required vs optional fields, and validation rules.
+
+**Input Parameters:**
+- `pageType` (required): "FRAGMENT"
+- `pageContext` (optional): JSON object - not required for FRAGMENT type
+- `componentDefinitions` (required): List of fully qualified names (e.g., ["namespace/definition"])
+- `includeKnowledge` (optional): Boolean, defaults to true - includes additional component-specific guidance
+
+**Returns:**
+- `componentSchemas`: List of results (supports partial failures)
+- **Success entries**: Contains JSON schema with property definitions, types, constraints
+- **Failure entries**: Contains error message explaining why schema couldn't be retrieved
+- `$defs`: Schema definitions and references (if schema transformation applied)
+
+**Use for:** Understanding how to configure component attributes before adding blocks to your fragment.
+
+**Key Feature:** Supports partial failures - if some components can't be found, you still get schemas for the successful ones.
+
+---
+
+## 💡 Typical Workflow
+
+1. **Discover Available Blocks**
+- Use `discoverUiComponents` to explore what blocks are available
+- Optional: Use `searchQuery` to filter by keywords (e.g., "text", "button", "image")
+
+2. **Select Components**
+- Choose blocks that fit your fragment requirements
+- Note their fully qualified definitions (e.g., "namespace/definition")
+
+3. **Get Component Schemas**
+- Use `getUiComponentSchemas` with the selected component definitions
+- Review the JSON schemas to understand required and optional attributes
+
+4. **Build Fragment**
+- Construct your fragment using the UEM tree structure
+- Configure block attributes according to the schemas
+- Use the TypeScript interfaces defined above
+
+---
+
+## ⚠️ Important Notes
+
+- Block definitions always follow the `{namespace}/{blockName}` convention
+- Use the same definition format returned by `discoverUiComponents` when calling `getUiComponentSchemas`
+- The FRAGMENT page type doesn't require additional `pageContext` parameters
+- Schemas include both required and optional attributes - review carefully to ensure valid configuration