@salesforce/afv-skills 1.7.1 → 1.7.3

package/package.json

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

package/skills/generating-custom-lightning-type/SKILL.md

@@ -20,6 +20,7 @@ Use this skill when you need to:
 Custom Lightning Types (CLTs) are JSON Schema-based type definitions used by the Lightning Platform (including Einstein Agent actions) to describe structured inputs/outputs and drive editor/renderer experiences.
 
 ## Configuration
+- **Choose referenced CLT pattern for nested objects** - When you need a **reusable** or **separately deployed** nested type, create a CLT for that shape and reference it with `"lightning:type": "c__<CLTName>"`. That string is the referenced type’s **`lightning:type` value / FQN / registered identifier** — not the JSON Schema `title`.
 - **Choose standard Lightning types** when the structure is simple and can be expressed with properties and supported primitive `lightning:type` identifiers.
 - **Choose Apex class types** (`@apexClassType/...`) when the structure already exists server-side and you want the Apex class to define the shape.
 - **Include editor/renderer config** only when you need custom UI behavior (custom LWC input/output components). Otherwise, omit.
@@ -33,7 +34,7 @@ Custom Lightning Types (CLTs) are JSON Schema-based type definitions used by the
 - `"unevaluatedProperties"` is enforced as `false` by the CLT metaschema. Do not set it to `true`.
 - **Root object schemas MUST NOT include** `"examples"` when `"unevaluatedProperties": false` is set.
 - **Nested objects (inside `properties`) MUST NOT set** `"lightning:type": "lightning__objectType"`.
-  - Nested objects should be plain JSON Schema objects (`type`, `properties`, optional `required`, optional `unevaluatedProperties`).
+    - Nested objects can be: references to other CLTs using `c__<CLTName>` syntax.
 - **List/array properties are highly restricted by the CLT metaschema**:
   - **CRITICAL LIMITATION**: the CLT metaschema may reject the `items` keyword entirely. Treat `items` as **disallowed by default**.
   - **Root-level arrays** (direct children of the root `properties`):
@@ -96,8 +97,13 @@ When strict validation is enabled (`unevaluatedProperties: false`), keep each pr
 2. **Draft `schema.json`**
    - Start with the root object structure (required root fields).
    - Add `properties` using valid primitive `lightning:type` identifiers.
-   - For nested objects: omit `lightning:type` and keep keywords minimal.
+   - For nested-object properties, use **CLT Reference pattern**:
+     - `"lightning:type": "c__<CLTName>"` to reference another CLT
+     - The referenced CLT must be deployed to the org before the parent CLT.
+   - For Apex-based nested objects: Use `@apexClassType/...` when structure exists server-side.
+   - If the prompt explicitly requires true nested object output, prefer an **Apex-based CLT** (`@apexClassType/...`) for deploy-safe nested structures.
    - For arrays: follow the strict list rules (avoid `items`; avoid `lightning:type` on nested arrays).
+   - Before deployment, verify exact `lightning:type` spellings (for example, use `lightning__richTextType`, not misspelled variants).
 3. **(Optional) Draft `editor.json`** (only if custom UI is required)
    - **Supported shape:** Top-level `editor` object with `editor.componentOverrides` and `editor.layout`.
      - Top-level `editor` object.
@@ -159,6 +165,7 @@ When strict validation is enabled (`unevaluatedProperties: false`), keep each pr
      </LightningComponentBundle>
      ```
 7. **Deploy and validate**
+   - Run a final schema sanity check before deploy: valid `lightning:type` names, required fields present, and no disallowed keywords.
    - Deploy the bundle using your org's standard metadata deployment flow (e.g. Salesforce CLI or IDE). The MCP client or tooling in use should provide or integrate with the appropriate deploy/retrieve commands for Lightning Type bundles.
    - Validate incrementally: if deployment fails, remove disallowed keywords first (especially `examples`, `items`, nested `lightning:type`).
 
@@ -166,7 +173,9 @@ When strict validation is enabled (`unevaluatedProperties: false`), keep each pr
 | Error / Symptom | Likely Cause | Fix |
 |---|---|---|
 | Schema validation fails due to unknown keyword | `unevaluatedProperties: false` + disallowed keyword (commonly `examples`, `items`) | Remove the offending keyword; keep schema minimal |
-| Nested object validation failure | Nested object includes `lightning:type: lightning__objectType` | Remove `lightning:type` from nested objects |
+| Nested object validation failure | Org/channel validation rejects nested object typing in `LightningTypeBundle` | Use CLT reference (`c__<CLTName>`) or Apex class types |
+| Invalid CLT reference | Referenced CLT doesn't exist in org or incorrect syntax | Deploy the referenced CLT first; `c__<CLTName>` must match the referenced type’s **`lightning:type` value / FQN / registered identifier**, not `title` |
+| Invalid or misspelled `lightning:type` (for example, `lightning__richtextType` instead of `lightning__richTextType`) | Incorrect generated type name | Cross-check all `lightning:type` values against supported type names and correct them before deployment |
 | Array property rejected | Use of `items` (or `lightning:type` in nested arrays) rejected by validator | For nested arrays: keep only `type: "array"`. For root arrays: use minimal structure; remove `items` if rejected |
 | Apex-based CLT rejected | Extra fields added (e.g., `type`, `properties`) | Use only `title`, optional `description`, and `lightning:type` |
 | Editor config rejected | Use of invalid patterns (`es_property_editors/inputList`, `itemSchema`) or unrecognized top-level keys | Use `editor.componentOverrides` and `editor.layout`; keep config minimal |

package/skills/searching-media/SKILL.md

@@ -33,11 +33,12 @@ Universal routing skill for searching and retrieving existing images and media.
 
 When a user requests to find an image:
 
-**Your first response MUST be plain text only — zero tool calls.** You MUST follow this sequence:
+**Your first action MUST use the ask_followup_question tool to present search sources.**
+
+1. **Use ask_followup_question** to present available search sources as options
+2. **Receive the user's selection** from the tool response
+3. **Then** call the appropriate search tool based on their choice
 
-1. **First response MUST be text only:** A numbered list of search sources for the user. No tool calls of any kind.
-2. **Wait for user to reply** with their selected option number
-3. **Only then** call the appropriate search tool (this is the FIRST tool call in the entire interaction)
 
 **Example of what NOT to do:**
 - ❌ Calling ANY tool before the user picks a source (MCP tools, file reads, descriptor checks, etc.)
@@ -279,7 +280,11 @@ Ask the user to provide:
 
 ## Presenting Search Results
 
-Parse the tool response and present **ALL** results as numbered options. Show the image title only — do not display the URL. When the user selects an option, use the URL internally to apply the image.
+**Your action MUST use the `ask_followup_question` tool to present search results as options.**
+1. **Parse the tool response** — Extract all image results (title and source)
+2. **Use `ask_followup_question`** to present ALL results as selectable options. Show the image title only — do not display the URL.
+3. **Receive the user's selection** from the tool response
+4. **Then** apply the selected image
 
 ```
 I found 4 images. Which one would you like to use?
@@ -301,6 +306,7 @@ I found 4 images. Which one would you like to use?
 
 ## Applying the Selected Image
 
+
 After the user chooses:
 
 1. Confirm the selection with image name and URL

package/skills/generating-fragment/SKILL.md

@@ -1,117 +0,0 @@
----
-name: generating-fragment
-description: "Use this skill when users need to create or edit Salesforce Fragments (reusable UI pieces). Trigger when users mention fragments, UEM blocks, reusable UI templates, structured rendering across Slack/Mobile/LEX, or block-based layouts. Also use when users want to create unified experience components. Always use this skill for any fragment work."
----
-
-## When to Use This Skill
-
-Use this skill when you need to:
-- Create reusable UI fragments for Salesforce experiences
-- Generate Fragment metadata following UEM structure
-- Build fragments for Slack, Mobile, LEX, and other Salesforce experiences
-- Troubleshoot deployment errors related to Fragments
-
-## Specification
-
-# 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.
-
-## 🎯 Purpose
-Fragments render data in a structured and unified way across various Salesforce experiences like Slack, Mobile, LEX etc
-
-## ⚙️ Composition
-A fragment is a UEM (Unified Experience Model) tree of blocks and regions. The fragment you return must follow the Typescript interfaces below:
-
-```ts
-interface BlockType {
-    type: 'block'
-    definition: string  // {namespace}/{blockName}
-    attributes?: Record<string, any>
-    children?: (BlockType | RegionType)[]
-}
-
-interface RegionType {
-    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