@salesforce/afv-skills 1.7.0 → 1.7.2

package/README.md

@@ -1,10 +1,8 @@
 # Agentforce Vibes Library
 
-AI skills library for Agentforce Vibes development of Salesforce metadata.
+This repository provides a curated collection of Salesforce agent skills for building applications. It includes skills for Agentforce agents, Lightning apps, Flow, Apex, SOQL, Lightning Web Components (LWC), UI bundles, objects and fields, permission sets, and related areas.
 
-## 📚 About
-
-This repository curates Salesforce-focused skills from the wider developer community to accelerate Agentforce Vibes agentic workflows. 
+The skills are contributed by Salesforce and the broader community. It’s optimized for Agentforce Vibes and can be used with any AI tool that supports skills.
 
 ## 🗂️ Structure
 
@@ -23,44 +21,51 @@ afv-library/
 └── README.md
 ```
 
-## Manual Usage
+## 🚀 Usage
+
+| **Tool** | **Usage** |
+|----------|-------------|
+| **Agentforce Vibes** | Skills are auto-installed and auto-updated |
+| **OpenCode, Claude Code, Codex, Cursor, [more](https://agentskills.io/)** | `npx skills add forcedotcom/afv-library` |
 
-Browse the repository and copy/paste any skill directly into Agentforce Vibes or your preferred AI tool.
+## 📦 Samples
 
-## Samples
+The `samples/` folder contains synced sample apps. For example, `samples/ui-bundle-template-app-react-sample-b2e/` tracks the npm package `@salesforce/ui-bundle-template-app-react-sample-b2e` (nightly and on manual trigger via GitHub Actions). 
 
-The `samples/` folder contains synced sample apps. For example, `samples/ui-bundle-template-app-react-sample-b2e/` is kept in sync with the npm package `@salesforce/ui-bundle-template-app-react-sample-b2e` (nightly and on manual trigger via GitHub Actions). To run the same sync locally from the repo root:
+To run the same sync locally from the repository root: 
 
 ```bash
 npm install
 npm run sync-react-b2e-sample
 ```
 
-The GitHub Action runs these same commands and opens a PR only when the npm package version has changed. See [samples/README.md](samples/README.md) for details.
-
+The GitHub Action runs the same commands and opens a pull request when the npm package version changes. For more information, see [samples/README.md](samples/README.md).
 
 ## 🛠️ Agent Skills
 
-Agent Skills are modular capabilities that bundle executable workflows, scripts, and reference materials into self-contained directories. Skills follow the open [Agent Skills specification](https://agentskills.io/) and are portable across many agent tools (Agentforce Vibes, Cursor, Claude Code, etc).
+Agent Skills package executable workflows, scripts, and reference material into self-contained directories. This repository follows the open [Agent Skills specification](https://agentskills.io/) and can be used with OpenCode, Claude Code, Codex, Cursor, and other tools that support skills.
 
 ### Directory Structure
 
-Each skill is a folder containing:
-- `SKILL.md` (required) - instructions + YAML frontmatter
-- `scripts/` (optional) - executable Python/Bash/JS
-- `references/` (optional) - additional documentation
-- `assets/` (optional) - templates, schemas, lookup data
-
+Each skill is a folder that can include:
+- `SKILL.md` (required): Instructions and YAML front matter.
+- `scripts/` (optional): Executable scripts (For example, Python, Bash, or JavaScript).
+- `references/` (optional): Extra reference documentation.
+- `assets/` (optional): Templates, schemas, and lookup data
 
 ## 🤝 Contributing
 
-See [Contributing](./CONTRIBUTING.md) for complete details.
+See [Contributing](./CONTRIBUTING.md).
 
+## 💬 Feedback
 
-## Feedback
+- Open an issue in this repository
+- Open a pull request with suggested changes
+- Use GitHub Discussions or the pull request thread for broader conversation
 
-Found an issue or have a suggestion?
-- Open an issue in GitHub
-- Suggest improvements via pull request
-- Start a discussion in GitHub Discussions or the pull request thread
+## Project Governance & Support
 
+- [License](./LICENSE.txt)
+- [Code of Conduct](./CODE_OF_CONDUCT.md)
+- [Contributing](./CONTRIBUTING.md)
+- [Security](./SECURITY.md)

package/package.json

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

package/skills/generating-flow/SKILL.md

@@ -87,7 +87,7 @@ Generates flow metadata element by element. This step is **mandatory** and must
 - When `isComplete` is `true`, extract the flow metadata from the `result` field.
 - If errors are returned, stop the loop and surface the error to the user.
 
-**STRICT CONSTRAINTS (CRITICAL):**
+**STRICT CONSTRAINTS (CRITICAL) — These rules apply to the XML returned by the generation pipeline:**
 - DO NOT modify the content, values, or child nodes inside any block.
 - DO NOT add new nodes, tags, attributes, or text (do not add missing labels, X/Y coordinates, etc.).
 - DO NOT remove any existing nodes.
@@ -334,6 +334,7 @@ Call repeatedly with the same `operationId` until `isComplete` is `true` or erro
 ## Mandatory Best Practices
 - **ALWAYS** follow the 3-step pipeline: fetchGroundedObjectMetadata → flowElementSelection → flowElementGeneration. This is the ONLY way to generate flow metadata. There are no alternatives.
 - Do NOT manually create flow metadata XML, JSON, or any other format outside of this pipeline.
+- **When the user explicitly requests fixes to validation or deployment errors** in an already-generated flow XML, you ARE permitted to make targeted manual edits to the XML to resolve those errors. This is the only exception to the "no manual metadata" rule.
 - Do NOT attempt to "optimize" by skipping steps or combining steps. Each step is atomic and required.
 - **NEVER** skip any step in the pipeline. All 3 steps are required.
 - **NEVER** try to generate flow metadata without calling all 3 steps.
@@ -366,3 +367,4 @@ Call repeatedly with the same `operationId` until `isComplete` is `true` or erro
 - [ ] **Multi-flow**: Each flow's full pipeline is completed before starting the next flow's pipeline (no interleaving)
 - [ ] **result** field is used to extract the XML flow metadata only when `isComplete` is `true`
 - [ ] **No additions to XML**: NO elements, attributes, or properties were added that were not present in the original pipeline output. Nothing was inserted (no `<label>`, `<description>`, or any other node). The final XML must be identical to what the pipeline returned.
+- [ ] **Error fix exception**: If the user explicitly requested fixes to validation/deployment errors, targeted manual edits to the XML are permitted and the "No additions to XML" / "No manual metadata" constraints do not apply to those edits.

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