From 77108bae20bc67c92acefa019b6e11a7192d26d0 Mon Sep 17 00:00:00 2001 From: k-j-kim <17989954+k-j-kim@users.noreply.github.com> Date: Thu, 2 Apr 2026 20:52:32 -0700 Subject: [PATCH] fix: tighten ui-bundle skill descriptions to reduce false triggers @W-21800526@ (#162) * fix: tighten skill descriptions to reduce false triggers - generating-ui-bundle-metadata: remove generic triggers (metadata, new app, meta XML, configuration), update command to sf template generate ui-bundle, add --template reactbasic flag - building-ui-bundle-app: reframe as orchestrator for multi-skill ui-bundle work, distinguish from generating-lightning-app * fix: improve ui-bundle skill descriptions to reduce false triggers and improve activation - Add MUST activate + file-pattern triggers to all 9 ui-bundle skills - Remove overly specific examples that waste context tokens - Scope features skill to authentication and search only - Add boundary language between orchestrator and frontend skills - Update metadata skill to use sf template generate ui-bundle --template reactbasic * fix: standardize uiBundles/*/src/ directory trigger across all ui-bundle skills * fix: remove React references from skill descriptions for framework agnosticism * fix: standardize uiBundles/*/src/ trigger in agentforce and data skills * fix: add 'Use this skill when' trigger context to all ui-bundle skill descriptions * fix: require mobile-responsive UI in building-ui-bundle-frontend skill --- skills/building-ui-bundle-app/SKILL.md | 2 +- skills/building-ui-bundle-frontend/SKILL.md | 4 +++- skills/deploying-ui-bundle/SKILL.md | 2 +- skills/generating-ui-bundle-features/SKILL.md | 2 +- skills/generating-ui-bundle-metadata/SKILL.md | 11 +++++++++-- skills/generating-ui-bundle-site/SKILL.md | 2 +- .../SKILL.md | 2 +- skills/implementing-ui-bundle-file-upload/SKILL.md | 2 +- skills/using-ui-bundle-salesforce-data/SKILL.md | 2 +- 9 files changed, 19 insertions(+), 10 deletions(-) diff --git a/skills/building-ui-bundle-app/SKILL.md b/skills/building-ui-bundle-app/SKILL.md index 4b68e0e..336c4bc 100644 --- a/skills/building-ui-bundle-app/SKILL.md +++ b/skills/building-ui-bundle-app/SKILL.md @@ -1,6 +1,6 @@ --- name: building-ui-bundle-app -description: "Build complete Salesforce React UI bundle applications from natural language descriptions. Use this skill when a user requests a full React app, UI bundle app, web app on Salesforce, or describes a scenario requiring scaffolding, features, data access, UI pages, and deployment of a React application hosted on Salesforce. Orchestrates all UI bundle skills in proper dependency order to produce a deployable application. Triggers on: build a React app, create a UI bundle, build me an app, full-stack Salesforce React app, create a web app on Salesforce." +description: "MUST activate when the project contains a uiBundles/*/src/ directory or sfdx-project.json and the prompt says create, build, construct, or generate a new app, site, or page from scratch — even if the prompt also describes visual styling. MUST also activate when the task spans more than one ui-bundle skill. Use this skill when building a complete app end-to-end. This is the orchestrator that coordinates scaffolding, features, data access, frontend UI, integrations, and deployment in the correct dependency order. Without it, phases execute out of order and the app breaks. Do NOT use for Lightning Experience apps with custom objects (use generating-lightning-app). Do NOT use for single-concern edits to an existing page (use building-ui-bundle-frontend)." metadata: version: "1.0" related-skills: generating-ui-bundle-metadata, generating-ui-bundle-features, using-ui-bundle-salesforce-data, building-ui-bundle-frontend, implementing-ui-bundle-agentforce-conversation-client, implementing-ui-bundle-file-upload, deploying-ui-bundle, generating-experience-react-site diff --git a/skills/building-ui-bundle-frontend/SKILL.md b/skills/building-ui-bundle-frontend/SKILL.md index 47a07fa..372da9c 100644 --- a/skills/building-ui-bundle-frontend/SKILL.md +++ b/skills/building-ui-bundle-frontend/SKILL.md @@ -1,6 +1,6 @@ --- name: building-ui-bundle-frontend -description: "Build and modify React UI for Salesforce UI bundles — pages, components, layout, navigation, and headers/footers. Use whenever creating or editing TSX/JSX files or making visual/layout changes. Triggers on: add page, add component, header, footer, navigation, layout, styling, Tailwind, shadcn, React component, appLayout." +description: "MUST activate before editing ANY file under uiBundles/*/src/ for visual or UI changes to an EXISTING app — pages, components, sections, layout, styling, colors, fonts, navigation, animations, or any look-and-feel change. Use this skill when modifying pages, components, layout, styling, or navigation in an existing UI bundle app. Activate when the project contains appLayout.tsx, routes.tsx, src/pages/, src/components/, or global.css. This skill contains critical project-specific conventions (appLayout.tsx shell, shadcn/ui components, Tailwind CSS, Salesforce base-path routing, module restrictions) that override general knowledge. Without this skill, generated code will use wrong imports, break routing, or ignore project structure. Do NOT use when creating a new app from scratch (use building-ui-bundle-app instead)." --- # UI Bundle UI @@ -94,6 +94,8 @@ Choose a clear conceptual direction and execute it with precision. Bold maximali - **Spatial Composition:** Unexpected layouts — asymmetry, overlap, diagonal flow, grid-breaking elements. Generous negative space OR controlled density. - **Backgrounds & Depth:** Create atmosphere rather than defaulting to solid colors. Gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, grain overlays. +- **Mobile Responsiveness:** All generated UI MUST be mobile-responsive. Use Tailwind responsive prefixes (`sm:`, `md:`, `lg:`) to adapt layouts across breakpoints. Stack columns on small screens, use flexible grids, and ensure touch targets are at least 44px. Test that navigation, typography, and spacing work on mobile viewports. + Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate animations and effects. Minimalist designs need restraint, precision, and careful spacing/typography. No two designs should look the same — vary themes, fonts, and aesthetics across generations. --- diff --git a/skills/deploying-ui-bundle/SKILL.md b/skills/deploying-ui-bundle/SKILL.md index 9c9e16f..7bff06a 100644 --- a/skills/deploying-ui-bundle/SKILL.md +++ b/skills/deploying-ui-bundle/SKILL.md @@ -1,6 +1,6 @@ --- name: deploying-ui-bundle -description: "Deploy a Salesforce UI bundle to an org — the full deployment sequence including org authentication, pre-deploy build, metadata deployment, permission set assignment, data import, GraphQL schema fetch, and codegen. Use whenever the user wants to deploy, push to org, assign permission sets, import data, fetch GraphQL schema, run codegen, or set up an org after development. Triggers on: deploy, push to org, deploy metadata, assign permission set, import data, schema fetch, codegen, org auth, authenticate org, build and deploy, post-deploy, org setup." +description: "MUST activate when the project contains a uiBundles/*/src/ directory or sfdx-project.json and the task involves deploying, pushing to an org, or post-deploy setup. Use this skill when deploying a UI bundle app to a Salesforce org. Covers the full deployment sequence: org authentication, pre-deploy build, metadata deployment, permission set assignment, data import, GraphQL schema fetch, and codegen. Activate when files like *.uibundle-meta.xml or sfdx-project.json exist and the user mentions deploying, pushing, org setup, or post-deploy tasks." --- # Deploying a UI Bundle diff --git a/skills/generating-ui-bundle-features/SKILL.md b/skills/generating-ui-bundle-features/SKILL.md index 00b6280..7cc4c61 100644 --- a/skills/generating-ui-bundle-features/SKILL.md +++ b/skills/generating-ui-bundle-features/SKILL.md @@ -1,6 +1,6 @@ --- name: generating-ui-bundle-features -description: "Search and install pre-built features into Salesforce React UI bundles — authentication, shadcn, search, navigation, GraphQL, Agentforce AI, and more. Use whenever searching for or installing features. Always check for an existing feature before building from scratch. Triggers on: install feature, add authentication, add shadcn, add feature, search features, list features." +description: "MUST activate when the project contains a uiBundles/*/src/ directory and the user wants to add authentication or search to their app. Use this skill when adding authentication or search to a UI bundle app. Only covers two features: authentication (login, logout, protected routes, session management) and search (global search across pages and content). Always use this skill for these two features instead of building from scratch." --- # UI Bundle Features diff --git a/skills/generating-ui-bundle-metadata/SKILL.md b/skills/generating-ui-bundle-metadata/SKILL.md index bd851fd..591dd28 100644 --- a/skills/generating-ui-bundle-metadata/SKILL.md +++ b/skills/generating-ui-bundle-metadata/SKILL.md @@ -1,6 +1,6 @@ --- name: generating-ui-bundle-metadata -description: "Scaffold new Salesforce UI bundles and configure their metadata — sf template generate ui-bundle, UIBundle bundles (meta XML, ui-bundle.json with routing/headers/outputDir), and CSP Trusted Sites for external domains. Use whenever creating a new UI bundle, setting up UI bundle metadata structure, configuring routing or headers, setting outputDir, adding external domains that need CSP registration, or editing bundle configuration. Triggers on: create UI bundle, create ui-bundle, new app, sf template generate ui-bundle, metadata, ui-bundle.json, CSP, trusted site, bundle configuration, meta XML, routing config, external domain, headers config, outputDir." +description: "MUST activate when the project contains a uiBundles/*/src/ directory and scaffolding a new UI bundle or app, or when editing ui-bundle.json, .uibundle-meta.xml, or CSP trusted site files. Use this skill when scaffolding with sf template generate ui-bundle, configuring ui-bundle.json (routing, headers, outputDir), or registering CSP Trusted Sites. Activate when the task involves files matching *.uibundle-meta.xml, ui-bundle.json, or cspTrustedSites/*.cspTrustedSite-meta.xml." --- # UI Bundle Metadata @@ -9,7 +9,14 @@ description: "Scaffold new Salesforce UI bundles and configure their metadata Use `sf template generate ui-bundle` to create new apps — not create-react-app, Vite, or other generic scaffolds. -**UI bundle name (`-n`):** Alphanumerical only — no spaces, hyphens, underscores, or special characters. Example: `CoffeeBoutique` (not `Coffee Boutique`). +**Always pass `--template reactbasic`** to scaffold a React-based bundle. + +**UI bundle name (`-n`):** Alphanumerical only — no spaces, hyphens, underscores, or special characters. + +**Example:** +```bash +sf template generate ui-bundle -n CoffeeBoutique --template reactbasic +``` After generation: 1. Replace all default boilerplate — "React App", "Vite + React", default ``, placeholder text diff --git a/skills/generating-ui-bundle-site/SKILL.md b/skills/generating-ui-bundle-site/SKILL.md index f2d0a2a..fdface6 100644 --- a/skills/generating-ui-bundle-site/SKILL.md +++ b/skills/generating-ui-bundle-site/SKILL.md @@ -1,6 +1,6 @@ --- name: generating-ui-bundle-site -description: "Use this skill when users need to create or configure a Salesforce Digital Experience Site specifically for hosting a React UI bundle. Trigger when users mention creating an Experience site for a React app, setting up a React site on Salesforce, configuring Network/CustomSite/DigitalExperience metadata for a UI bundle, or deploying site infrastructure for a React application. Also trigger when users mention site URL path prefixes, app namespaces, appDevName, guest access configuration, DigitalExperienceConfig, DigitalExperienceBundle, or sfdc_cms__site content types in the context of React apps. Always use this skill for any React UI bundle site creation or site infrastructure configuration work, even if the user just says \"create a site for my React app\" or \"set up the site for my UI bundle.\"" +description: "MUST activate when the project contains a uiBundles/*/src/ directory and the task involves creating or configuring site infrastructure. Use this skill when creating or configuring a Salesforce Digital Experience Site for hosting a UI bundle. Activate when files matching digitalExperiences/, networks/, customSite/, or DigitalExperienceBundle exist and need modification, or when the user wants to publish, host, or configure guest access for their app." --- # Digital Experience Site for React UI Bundles diff --git a/skills/implementing-ui-bundle-agentforce-conversation-client/SKILL.md b/skills/implementing-ui-bundle-agentforce-conversation-client/SKILL.md index 0e9bd3f..96cfec8 100644 --- a/skills/implementing-ui-bundle-agentforce-conversation-client/SKILL.md +++ b/skills/implementing-ui-bundle-agentforce-conversation-client/SKILL.md @@ -1,6 +1,6 @@ --- name: implementing-ui-bundle-agentforce-conversation-client -description: Use this skill when the user asks to add, embed, integrate, configure, style, or remove an agent, chatbot, chat widget, conversation client, or AI assistant in a React component. Covers styling (colors, fonts, spacing, borders), layout (inline vs floating, width, height, dimensions), and props (agentId, agentLabel, headerEnabled, showHeaderIcon, showAvatar, styleTokens). Also matches references to specific agents (e.g. travel agent, HR agent, support agent, employee agent). Never create a custom agent, chatbot, or chat widget component. +description: "MUST activate when the project contains a uiBundles/*/src/ directory and the task involves adding or modifying a chat widget, chatbot, or conversational AI. Use this skill when the user asks to add, embed, integrate, configure, style, or remove an agent, chatbot, chat widget, conversation client, or AI assistant. Covers styling (colors, fonts, spacing, borders), layout (inline vs floating, width, height, dimensions), and props (agentId, agentLabel, headerEnabled, showHeaderIcon, showAvatar, styleTokens). Activate when files under uiBundles/*/src/ import AgentforceConversationClient or when adding any chat or agent functionality to a page. Never create a custom agent, chatbot, or chat widget component." metadata: author: ACC Components version: 1.0.1 diff --git a/skills/implementing-ui-bundle-file-upload/SKILL.md b/skills/implementing-ui-bundle-file-upload/SKILL.md index 3ccf452..8104f82 100644 --- a/skills/implementing-ui-bundle-file-upload/SKILL.md +++ b/skills/implementing-ui-bundle-file-upload/SKILL.md @@ -1,6 +1,6 @@ --- name: implementing-ui-bundle-file-upload -description: "Add file upload functionality to React UI bundles with progress tracking and Salesforce ContentVersion integration. Use when the user wants to upload files, attach documents, handle file input, create file dropzones, track upload progress, or link files to Salesforce records. This feature provides programmatic APIs ONLY — no components or hooks are exported. Build your own custom UI using the upload() API. ALWAYS use this feature instead of building file upload from scratch with FormData or XHR." +description: "MUST activate when the project contains a uiBundles/*/src/ directory and the task involves uploading, attaching, or dropping files. Use this skill when adding file upload functionality to a UI bundle app. Provides progress tracking and Salesforce ContentVersion integration. This feature provides programmatic APIs ONLY — build custom UI using the upload() API. ALWAYS use this instead of building file upload from scratch with FormData or XHR." --- # File Upload API (workflow) diff --git a/skills/using-ui-bundle-salesforce-data/SKILL.md b/skills/using-ui-bundle-salesforce-data/SKILL.md index 9e091c2..3779618 100644 --- a/skills/using-ui-bundle-salesforce-data/SKILL.md +++ b/skills/using-ui-bundle-salesforce-data/SKILL.md @@ -1,6 +1,6 @@ --- name: using-ui-bundle-salesforce-data -description: "Salesforce data access for reading, writing, and querying records via REST, GraphQL, Apex, or Platform SDK. Use when the user wants to fetch, search, filter, sort, display, create, update, delete, or attach files to Salesforce records (standard objects like Accounts, Contacts, Opportunities, Cases, Quotes, or any custom object) in a UI bundle or UI component (React, Angular, Vue, etc.); call Chatter, Connect, or Apex REST APIs; or invoke AuraEnabled Apex methods from an external app. Does not apply to authentication/OAuth setup, schema changes (adding fields, relationships), Bulk/Tooling/Metadata API usage, declarative automation (Flows, Process Builder), general LWC/Apex coding guidance without a specific data operation, or Salesforce admin/configuration tasks." +description: "MUST activate when the project contains a uiBundles/*/src/ directory and the task involves ANY Salesforce record operation — reading, creating, updating, or deleting. Use this skill when building forms that submit to Salesforce, pages that display Salesforce records, or any code that touches Salesforce objects or custom objects. Activate when files under uiBundles/*/src/ import from @salesforce/sdk-data, or when *.graphql files or codegen.yml exist. This skill owns all Salesforce data access patterns in UI bundles. Does not apply to authentication/OAuth setup, schema changes, Bulk/Tooling/Metadata API, or declarative automation." --- # Salesforce Data Access