mirror of
https://github.com/forcedotcom/afv-library.git
synced 2026-08-12 02:49:15 +08:00
Compare commits
6 Commits
5961882d45
...
e1764f5ed1
| Author | SHA1 | Date | |
|---|---|---|---|
|
e1764f5ed1 | ||
|
|
bdf0ff8f55 | ||
|
|
e515d3cfa7 | ||
|
|
36e89c4185 | ||
|
|
71bb1d8d44 | ||
|
|
6be8da95ff |
@ -1,40 +0,0 @@
|
||||
---
|
||||
name: cms-d360-search
|
||||
description: Data Cloud AI Hybrid Search via search_electronic_media or search_content_in_d360 MCP tool. Performs semantic search across Salesforce CMS and 3rd-party DAMs using natural language queries. Invoked from cms-media-search when the user selects Data Cloud – AI Hybrid Search.
|
||||
license: Apache-2.0
|
||||
compatibility: Requires content MCP server with search_electronic_media or search_content_in_d360 tool.
|
||||
metadata:
|
||||
author: afv-library
|
||||
version: "2.0"
|
||||
---
|
||||
|
||||
# Data Cloud – AI Hybrid Search
|
||||
|
||||
Semantic search across Salesforce CMS and connected 3rd-party DAMs. Invoked by `cms-media-search` when the user selects **Data Cloud – AI Hybrid Search**.
|
||||
|
||||
Best for natural language queries, cross-system searches, and semantic similarity (vs exact keyword matching).
|
||||
|
||||
## Step 1: Build the Query
|
||||
|
||||
Use the user's original request **as-is**. No keyword extraction, taxonomy splitting, or translation needed — the tool handles semantic interpretation.
|
||||
|
||||
## Step 2: Call the MCP Tool
|
||||
|
||||
Call **one** of these tools (try primary first, fall back to legacy):
|
||||
|
||||
| Priority | Tool name |
|
||||
|----------|-----------|
|
||||
| Primary | `search_content_in_d360` |
|
||||
| Fallback | `search_electronic_media` |
|
||||
|
||||
Input: `query` = the user's search query string. Refer to the tool's schema for additional parameters.
|
||||
|
||||
## Step 3: Present Results and Handle Selection
|
||||
|
||||
- Present **every** result as a numbered option with title, URL, and source. Never auto-select.
|
||||
- Wait for the user to choose by number or name.
|
||||
- After selection: confirm, apply the URL in code, show what changed, offer next steps.
|
||||
|
||||
## Errors
|
||||
|
||||
On any error (no results, tool unavailable, tool returns error): inform the user and offer to (1) retry with different terms, (2) try a different source via `cms-media-options`, or (3) provide their own image URL. Do not retry automatically.
|
||||
@ -1,350 +0,0 @@
|
||||
---
|
||||
name: cms-keyword-search
|
||||
description: Search Salesforce CMS for images by keywords and taxonomies via the search_media_cms_channels MCP tool. Delegated from cms-media-search when the user selects CMS Image Search. Analyzes the user query, extracts keywords and taxonomies, builds the search payload using the exact template and format rules defined in this skill, calls the tool, and presents results for user selection. Do NOT invoke this skill directly for initial image requests — it is always reached through cms-media-search.
|
||||
license: Apache-2.0
|
||||
metadata:
|
||||
author: afv-library
|
||||
version: "6.0"
|
||||
---
|
||||
|
||||
# CMS Keyword Search
|
||||
|
||||
Search Salesforce CMS for images using keywords and taxonomies. **Delegated from `cms-media-search`** when the user selects "CMS Image Search".
|
||||
|
||||
## Execution Flow
|
||||
|
||||
Follow these steps **in order**. Do NOT call `search_media_cms_channels` until Step 5.
|
||||
|
||||
1. Analyze the user's query and ng expand with domain-specific terms
|
||||
2. Extract keywords (concrete nouns)
|
||||
3. Extract taxonomies (descriptive attributes)
|
||||
4. Determine locale
|
||||
5. Build the payload using the **Payload Template**
|
||||
6. Call `search_media_cms_channels` with the payload
|
||||
7. Present results and wait for user selection
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Analyze and Expand the Query
|
||||
|
||||
Understand the user's intent and expand with domain knowledge:
|
||||
|
||||
- **Main subject** — what are they searching for? (apartments, cars, logos)
|
||||
- **Attributes** — how should it look? (luxury, modern, spacious)
|
||||
- **Domain** — what context? (real estate, automotive, corporate)
|
||||
|
||||
Expand with synonyms and domain-specific terms:
|
||||
|
||||
| Domain | Query term | Expansion |
|
||||
|---|---|---|
|
||||
| Real Estate | "luxury apartments" | villa, penthouse, residence, condo, duplex |
|
||||
| Automotive | "cars" | automobile, vehicle, auto, SUV |
|
||||
| Corporate | "company logo" | logo, brand, corporate logo, branding |
|
||||
| Home/Interior | "modern kitchen" | kitchen, contemporary kitchen, kitchen interior |
|
||||
|
||||
## Step 2: Extract Keywords
|
||||
|
||||
Keywords are **concrete, searchable nouns** that would appear in image titles or metadata.
|
||||
|
||||
Rules:
|
||||
- Only nouns and noun phrases — no verbs, adjectives, or stop words
|
||||
- Include domain-specific synonyms from Step 1
|
||||
- Maximum 10 terms
|
||||
- If the query has no concrete nouns (e.g. "something bright"), use **empty string**
|
||||
|
||||
| Query | Keywords |
|
||||
|---|---|
|
||||
| "luxury apartments" | apartment, villa, penthouse, residence, condo |
|
||||
| "company logo" | logo, brand, corporate logo, branding |
|
||||
| "modern kitchen" | kitchen, contemporary kitchen |
|
||||
| "bright spacious room" | _(empty — no concrete nouns)_ |
|
||||
| "car images" | car, automobile, vehicle, auto |
|
||||
|
||||
## Step 3: Extract Taxonomies
|
||||
|
||||
Taxonomies are **descriptive qualities, styles, moods, or categories** — how the image should look or feel, or what category it belongs to.
|
||||
|
||||
Rules:
|
||||
- Only adjectives, attributes, and categorical terms
|
||||
- Include domain-relevant descriptors from Step 1
|
||||
- If the query has no descriptive terms (e.g. "car"), use **empty string**
|
||||
|
||||
| Query | Taxonomies |
|
||||
|---|---|
|
||||
| "luxury apartment with river view" | Luxury, Premium, Waterfront, Riverside, Panoramic, Real Estate |
|
||||
| "company logo" | Corporate, Business, Professional, Branding |
|
||||
| "bright spacious room" | Bright, Spacious, Open, Airy, Light |
|
||||
| "car" | _(empty — no descriptive terms)_ |
|
||||
|
||||
**Never mix**: descriptive terms like "modern", "luxury", "warm" go in taxonomies, NOT keywords. Exception: compound domain terms like "Luxury Apartments" can appear in keywords.
|
||||
|
||||
## Step 4: Determine Locale
|
||||
|
||||
Use **locale format with underscore** (e.g. `en_US`, `es_MX`, `fr_FR`). Default: `en_US`.
|
||||
|
||||
Priority:
|
||||
1. Explicit language/region in query → use that locale
|
||||
2. Query in non-English → infer locale with region
|
||||
3. Context clues from conversation → include region
|
||||
4. Default: `en_US`
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Build the Payload
|
||||
|
||||
Construct the JSON payload for `search_media_cms_channels` using the template below. Follow every format rule exactly.
|
||||
|
||||
### Payload Template
|
||||
|
||||
```json
|
||||
{
|
||||
"inputs": [{
|
||||
"searchKeyword": "<KEYWORDS>",
|
||||
"taxonomyExpression": "<TAXONOMY>",
|
||||
"searchLanguage": "<LOCALE>",
|
||||
"channelIds": "",
|
||||
"channelType": "PublicUnauthenticated",
|
||||
"contentTypeFqns": "sfdc_cms__image",
|
||||
"pageOffset": 0,
|
||||
"pageLimit": 5
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
### Critical: Single Input Object Only
|
||||
|
||||
The `inputs` array must contain **exactly ONE object**. All keywords go into a single `searchKeyword` field, OR-separated. Do NOT create multiple input objects.
|
||||
|
||||
```
|
||||
✅ "inputs": [{ "searchKeyword": "logo OR brand OR emblem OR branding", ... }]
|
||||
❌ "inputs": [{ "searchKeyword": "logo", ... }, { "searchKeyword": "brand", ... }]
|
||||
```
|
||||
|
||||
### Format Rules
|
||||
|
||||
#### `searchKeyword` — Join keywords with ` OR ` (uppercase, space-padded)
|
||||
|
||||
```
|
||||
✅ "logo OR brand OR emblem OR branding OR corporate logo"
|
||||
✅ "car OR automobile OR vehicle OR auto"
|
||||
✅ "" ← no keywords
|
||||
❌ "logo, brand, emblem" ← comma-separated
|
||||
❌ "logo brand emblem" ← space-separated
|
||||
❌ "logo or brand" ← lowercase "or"
|
||||
```
|
||||
|
||||
#### `taxonomyExpression` — Stringified JSON object, NOT a raw object or plain string
|
||||
|
||||
Build the object `{"OR": ["term1", "term2"]}`, then **convert it to a string**. The value must be a **string**, not an object.
|
||||
|
||||
```
|
||||
✅ "{\"OR\": [\"Corporate\", \"Business\", \"Professional\", \"Branding\"]}"
|
||||
✅ "{\"OR\": [\"Luxury\", \"Premium\", \"High-end\"]}"
|
||||
✅ "{\"OR\": [\"Bright\"]}" ← single term
|
||||
✅ "{}" ← no taxonomies
|
||||
❌ {"OR": ["Corporate", "Business"]} ← raw object
|
||||
❌ "Corporate OR Business OR Professional" ← OR-separated
|
||||
❌ "Corporate, Business, Professional" ← CSV
|
||||
```
|
||||
|
||||
#### `searchLanguage` — Locale with underscore, never language-only
|
||||
|
||||
```
|
||||
✅ "en_US" "fr_CA" "es_MX" "ja_JP" "de_DE"
|
||||
❌ "en" "fr" "es" "ja" "de"
|
||||
```
|
||||
|
||||
#### Hardcoded fields — never change these values
|
||||
|
||||
| Field | Value | Notes |
|
||||
|---|---|---|
|
||||
| `channelIds` | `""` | Always empty string |
|
||||
| `channelType` | `"PublicUnauthenticated"` | Exact capitalization required |
|
||||
| `contentTypeFqns` | `"sfdc_cms__image"` | Double underscore, all lowercase |
|
||||
| `pageOffset` | `0` | Default start position |
|
||||
| `pageLimit` | `5` | Default; user can request more |
|
||||
|
||||
---
|
||||
|
||||
### Worked Examples
|
||||
|
||||
**Query: "Look for logo and apply it to the header"**
|
||||
|
||||
- Keywords: logo, brand, emblem, branding, corporate logo
|
||||
- Taxonomies: Corporate, Business, Professional, Branding
|
||||
- Locale: en_US
|
||||
|
||||
```json
|
||||
{
|
||||
"inputs": [{
|
||||
"searchKeyword": "logo OR brand OR emblem OR branding OR corporate logo",
|
||||
"taxonomyExpression": "{\"OR\": [\"Corporate\", \"Business\", \"Professional\", \"Branding\"]}",
|
||||
"searchLanguage": "en_US",
|
||||
"channelIds": "",
|
||||
"channelType": "PublicUnauthenticated",
|
||||
"contentTypeFqns": "sfdc_cms__image",
|
||||
"pageOffset": 0,
|
||||
"pageLimit": 5
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
**Query: "Find luxury car images"**
|
||||
|
||||
- Keywords: car, automobile, vehicle, auto
|
||||
- Taxonomies: Luxury, Premium, High-end
|
||||
- Locale: en_US
|
||||
|
||||
```json
|
||||
{
|
||||
"inputs": [{
|
||||
"searchKeyword": "car OR automobile OR vehicle OR auto",
|
||||
"taxonomyExpression": "{\"OR\": [\"Luxury\", \"Premium\", \"High-end\"]}",
|
||||
"searchLanguage": "en_US",
|
||||
"channelIds": "",
|
||||
"channelType": "PublicUnauthenticated",
|
||||
"contentTypeFqns": "sfdc_cms__image",
|
||||
"pageOffset": 0,
|
||||
"pageLimit": 5
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
**Query: "Something bright and spacious" (no concrete nouns)**
|
||||
|
||||
- Keywords: _(empty)_
|
||||
- Taxonomies: Bright, Spacious, Open, Airy, Light
|
||||
- Locale: en_US
|
||||
|
||||
```json
|
||||
{
|
||||
"inputs": [{
|
||||
"searchKeyword": "",
|
||||
"taxonomyExpression": "{\"OR\": [\"Bright\", \"Spacious\", \"Open\", \"Airy\", \"Light\"]}",
|
||||
"searchLanguage": "en_US",
|
||||
"channelIds": "",
|
||||
"channelType": "PublicUnauthenticated",
|
||||
"contentTypeFqns": "sfdc_cms__image",
|
||||
"pageOffset": 0,
|
||||
"pageLimit": 5
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
**Query: "Car images" (no descriptive terms)**
|
||||
|
||||
- Keywords: car, automobile, vehicle, auto
|
||||
- Taxonomies: _(empty)_
|
||||
- Locale: en_US
|
||||
|
||||
```json
|
||||
{
|
||||
"inputs": [{
|
||||
"searchKeyword": "car OR automobile OR vehicle OR auto",
|
||||
"taxonomyExpression": "{}",
|
||||
"searchLanguage": "en_US",
|
||||
"channelIds": "",
|
||||
"channelType": "PublicUnauthenticated",
|
||||
"contentTypeFqns": "sfdc_cms__image",
|
||||
"pageOffset": 0,
|
||||
"pageLimit": 5
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
**Query: "Luxury apartment with river view"**
|
||||
|
||||
- Keywords: apartment, villa, penthouse, residence, condo, suite
|
||||
- Taxonomies: Waterfront, Riverside, Panoramic, Luxury, Premium, Real Estate
|
||||
- Locale: en_US
|
||||
|
||||
```json
|
||||
{
|
||||
"inputs": [{
|
||||
"searchKeyword": "apartment OR villa OR penthouse OR residence OR condo OR suite",
|
||||
"taxonomyExpression": "{\"OR\": [\"Waterfront\", \"Riverside\", \"Panoramic\", \"Luxury\", \"Premium\", \"Real Estate\"]}",
|
||||
"searchLanguage": "en_US",
|
||||
"channelIds": "",
|
||||
"channelType": "PublicUnauthenticated",
|
||||
"contentTypeFqns": "sfdc_cms__image",
|
||||
"pageOffset": 0,
|
||||
"pageLimit": 5
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
**Query: "Cherche des images de voiture de luxe" (French)**
|
||||
|
||||
- Keywords: voiture, automobile, véhicule
|
||||
- Taxonomies: Luxe, Premium, Haut de gamme
|
||||
- Locale: fr_FR
|
||||
|
||||
```json
|
||||
{
|
||||
"inputs": [{
|
||||
"searchKeyword": "voiture OR automobile OR véhicule",
|
||||
"taxonomyExpression": "{\"OR\": [\"Luxe\", \"Premium\", \"Haut de gamme\"]}",
|
||||
"searchLanguage": "fr_FR",
|
||||
"channelIds": "",
|
||||
"channelType": "PublicUnauthenticated",
|
||||
"contentTypeFqns": "sfdc_cms__image",
|
||||
"pageOffset": 0,
|
||||
"pageLimit": 5
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Call the MCP Tool
|
||||
|
||||
Call `search_media_cms_channels` with the exact JSON payload from Step 5.
|
||||
|
||||
## Step 7: Present Results
|
||||
|
||||
Parse the response and present **all** results as numbered options. For each result, show:
|
||||
- Image title or name (`title` or `name` field)
|
||||
- Media URL (`mediaUrl` or from `deliveryInfo.urls`)
|
||||
|
||||
**Never auto-select an image.** Always wait for the user to choose.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
I found 3 images in Salesforce CMS. Which one would you like to use?
|
||||
|
||||
1. **Stainless Steel Kitchen Utensils**
|
||||
URL: https://cms.example.com/media/kitchen-utensils.jpg
|
||||
|
||||
2. **Modern Cookware Set**
|
||||
URL: https://cms.example.com/media/modern-cookware.jpg
|
||||
|
||||
3. **Professional Kitchen Tools**
|
||||
URL: https://cms.example.com/media/professional-tools.jpg
|
||||
```
|
||||
|
||||
### After User Selection
|
||||
|
||||
1. Confirm the selection with image name and URL
|
||||
2. Apply the URL to the user's code or component
|
||||
3. Show what was changed (file and line)
|
||||
4. Offer next steps (alt text, styling, more images)
|
||||
|
||||
---
|
||||
|
||||
## Search Behavior
|
||||
|
||||
- When both keyword and taxonomy are provided: results match keyword OR (keyword + taxonomy)
|
||||
- Empty keyword → search by taxonomy only
|
||||
- Empty taxonomy → search by keyword only
|
||||
- Default `pageLimit` is 5; user can request more
|
||||
- Use `pageOffset` for pagination (increment by `pageLimit`)
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Response |
|
||||
|---|---|
|
||||
| `search_media_cms_channels` unavailable | Inform user; offer Data Cloud, Unsplash, or Other via `cms-media-search` |
|
||||
| Tool returns an error | Show error message; offer retry with different terms or alternative source |
|
||||
| No results found | Suggest broader keywords, removing taxonomies, or trying Data Cloud/Unsplash |
|
||||
| Invalid user selection | Re-display the options and ask again |
|
||||
@ -1,128 +0,0 @@
|
||||
---
|
||||
name: cms-media-search
|
||||
description: REQUIRED first step for ALL image and media requests. Activate IMMEDIATELY when the user asks to find, search, get, fetch, retrieve, browse, look up, use, add, insert, or need any image, photo, picture, media, visual, graphic, icon, illustration, hero image, banner, thumbnail, logo, background image, cover image, feature image, stock photo, or visual asset. This skill discovers which search sources (Salesforce CMS, Data Cloud, Unsplash) are available by checking MCP tool presence, presents only available options to the user, and delegates to the correct search skill. NEVER call search_media_cms_channels, search_content_in_d360, search_electronic_media, or any image search tool directly — always route through this skill first.
|
||||
license: Apache-2.0
|
||||
metadata:
|
||||
author: afv-library
|
||||
version: "3.0"
|
||||
---
|
||||
|
||||
# CMS Media Search — Source Selection
|
||||
|
||||
**MANDATORY ENTRY POINT for every media and image search.** Do not assume a source. Do not call any search tool directly. Discover what is available, present only those options, and delegate to the matching search skill.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Activate **immediately** — before any other response — whenever the user's request involves any visual content:
|
||||
|
||||
- Images, photos, pictures, media, visuals, graphics
|
||||
- Icons, illustrations, banners, thumbnails, logos
|
||||
- Hero images, background images, feature images, cover images
|
||||
- Any asset described as visual (e.g. "something for the carousel", "a picture for the header")
|
||||
|
||||
Example triggers:
|
||||
|
||||
- "Find a modern luxury apartment exterior and use it in the hero section"
|
||||
- "I need a hero image for the landing page"
|
||||
- "Search for family lifestyle photos for the carousel"
|
||||
- "Get me a logo for the about page"
|
||||
- "Look up some banner graphics"
|
||||
- "Can you find product images?"
|
||||
- "Add an image to the header component"
|
||||
- "I need some stock photos for the homepage"
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Discover Available Sources via MCP Tool Presence
|
||||
|
||||
**Before presenting any options**, determine which search tools are available by checking the MCP tools accessible in your current environment. Do NOT skip this step. Do NOT assume any tool is available.
|
||||
|
||||
Check for these specific MCP tools:
|
||||
|
||||
| MCP Tool to look for | If present | Source option to show |
|
||||
|---|---|---|
|
||||
| `search_media_cms_channels` | ✅ Available | **CMS Image Search (Salesforce CMS)** |
|
||||
| `search_content_in_d360` OR `search_electronic_media` | ✅ Available | **Data Cloud – AI Hybrid Search (Salesforce CMS + 3rd-party DAMs)** |
|
||||
| Any tool from an Unsplash MCP server | ✅ Available | **Unsplash** |
|
||||
| _(always)_ | — | **Other** (user provides URL or asset path) |
|
||||
|
||||
### How to check
|
||||
|
||||
1. List the MCP servers and tools available in your environment (e.g. browse MCP tool descriptors, or check configured MCP servers).
|
||||
2. Match tool names against the table above.
|
||||
3. A source is available **only** if its corresponding MCP tool is confirmed accessible.
|
||||
|
||||
### Rules
|
||||
|
||||
- **NEVER present a source unless its MCP tool is confirmed available.**
|
||||
- If **no search tools are found** → present only **Other** and tell the user no automated media sources are currently configured.
|
||||
|
||||
## Step 2: Present Source Options
|
||||
|
||||
Build the options list dynamically. Include **only** sources whose MCP tool is available, plus **Other**. Number them sequentially. **Wait for the user to choose before doing anything else.**
|
||||
|
||||
**All sources available:**
|
||||
|
||||
> I can help you find that. Where would you like to search?
|
||||
> 1. **Data Cloud – AI Hybrid Search (Salesforce CMS + 3rd-party DAMs)** — Semantic search through D360
|
||||
> 2. **CMS Image Search (Salesforce CMS)** — Search images by keywords and taxonomies
|
||||
> 3. **Unsplash** — Stock images from Unsplash
|
||||
> 4. **Other** (please specify)
|
||||
|
||||
**Only CMS + D360 available:**
|
||||
|
||||
> I can help you find that image. Where would you like to search?
|
||||
> 1. **Data Cloud – AI Hybrid Search (Salesforce CMS + 3rd-party DAMs)**
|
||||
> 2. **CMS Image Search (Salesforce CMS)**
|
||||
> 3. **Other** (please specify)
|
||||
|
||||
**No sources available:**
|
||||
|
||||
> No automated media sources are currently configured. You can provide a direct URL or asset library path.
|
||||
> 1. **Other** (please specify)
|
||||
|
||||
## Step 3: Delegate Based on User Selection
|
||||
|
||||
Only after the user selects an option, follow the matching action by **source name** (not number — numbers change based on availability):
|
||||
|
||||
| User selects | Action |
|
||||
|---|---|
|
||||
| **CMS Image Search** | Read and follow `../cms-keyword-search/SKILL.md` |
|
||||
| **Data Cloud – AI Hybrid Search** | Read and follow `../cms-d360-search/SKILL.md` |
|
||||
| **Unsplash** | Invoke the Unsplash MCP tool directly (see below) |
|
||||
| **Other** | Ask the user for the source URL or asset library details |
|
||||
|
||||
### Unsplash: Direct MCP Tool Invocation
|
||||
|
||||
When the user selects **Unsplash**, do not load a separate skill. Call the Unsplash MCP tool directly:
|
||||
|
||||
1. **Build the query** from the user's request (e.g. "modern apartment exterior", "family lifestyle"). Use simple, descriptive keywords.
|
||||
2. **Invoke the Unsplash MCP tool** exposed by the Unsplash MCP server. Pass the search intent as the query parameter; use the tool's schema for exact parameter names and optional fields (e.g. `per_page`, `orientation`).
|
||||
3. **Present results** with preview thumbnails, photographer credit where available, and a note that Unsplash images are free to use under the [Unsplash License](https://unsplash.com/license). Let the user choose which image to use before placing it.
|
||||
|
||||
## Step 4: Handle Errors
|
||||
|
||||
If any MCP tool call fails (server error, token expired, connection refused):
|
||||
|
||||
- **Do not silently fail.** Tell the user the search tool is currently unavailable and suggest checking MCP server status.
|
||||
- Offer to retry, or fall back to **Other** (provide a direct URL or asset library path).
|
||||
- Do **not** present empty results as if the search succeeded.
|
||||
|
||||
## Step 5: Present Results
|
||||
|
||||
After the delegated skill returns results:
|
||||
|
||||
- Display returned assets with preview thumbnails when available.
|
||||
- Include asset title, source system, and relevance score or tags.
|
||||
- Let the user confirm which asset to use before inserting it into the page or component.
|
||||
- Do **not** automatically use the first result — user selection is required.
|
||||
|
||||
---
|
||||
|
||||
## Prohibitions
|
||||
|
||||
- ❌ Do NOT skip source discovery — never assume a source is available
|
||||
- ❌ Do NOT present source options without confirming MCP tool availability first
|
||||
- ❌ Do NOT call `search_media_cms_channels`, `search_content_in_d360`, `search_electronic_media`, or any search tool directly — always go through this skill's source selection flow first
|
||||
- ❌ Do NOT auto-select a source — always let the user choose
|
||||
- ❌ Do NOT bypass this skill by loading `cms-keyword-search` or `cms-d360-search` directly for an initial image request
|
||||
356
skills/searching-media/SKILL.md
Normal file
356
skills/searching-media/SKILL.md
Normal file
@ -0,0 +1,356 @@
|
||||
---
|
||||
name: searching-media
|
||||
description: Use when the user wants to FIND, SEARCH, or RETRIEVE images, photos, pictures, media, visuals, graphics, icons, illustrations, banners, thumbnails, logos, hero images, backgrounds, or visual assets. Trigger on search, find, get, fetch, retrieve, browse, look up, locate, or add existing media requests. ROUTING skill that presents search source options (Salesforce CMS, Data Cloud, Unsplash) and waits for user selection before calling any search tools. ALWAYS show numbered options first - NEVER call search_electronic_media or search_media_cms_channels directly. DO NOT trigger for GENERATE, CREATE, MAKE, DESIGN, or BUILD requests.
|
||||
metadata:
|
||||
author: afv-library
|
||||
version: "1.0"
|
||||
---
|
||||
|
||||
# Media Search
|
||||
|
||||
Universal routing skill for searching and retrieving existing images and media.
|
||||
|
||||
## Scope
|
||||
|
||||
**This skill is for FINDING existing media, not CREATING new media.**
|
||||
|
||||
**Use this skill when the user wants to:**
|
||||
- Search for images in Salesforce CMS, Data Cloud, or Unsplash
|
||||
- Find existing visual assets
|
||||
- Retrieve media from connected sources
|
||||
- Browse available images
|
||||
- Locate specific photos or graphics
|
||||
|
||||
**DO NOT use this skill when the user wants to:**
|
||||
- Generate new images with AI (use image generation tools)
|
||||
- Create graphics or designs from scratch
|
||||
- Edit or modify existing images
|
||||
- Build custom visuals or diagrams
|
||||
|
||||
## Before You Search
|
||||
|
||||
**CRITICAL: This is a routing skill, not a direct search skill.**
|
||||
|
||||
When a user requests to find an image:
|
||||
|
||||
**DO NOT call any search tool directly.** You MUST follow this sequence:
|
||||
|
||||
1. **First response MUST include:** A list of numbered search source options for the user
|
||||
2. **Wait for user to reply** with their selected option number
|
||||
3. **Only then** call the appropriate search tool
|
||||
|
||||
**Example of what NOT to do:**
|
||||
- ❌ Immediately calling `search_electronic_media` or `search_media_cms_channels`
|
||||
- ❌ Deciding which search source to use without asking
|
||||
- ❌ Saying "I'll search for you" and then calling a tool
|
||||
|
||||
**Example of what TO do:**
|
||||
- ✅ Show numbered list: "1. Search using Data 360 hybrid search, 2. Search using keywords, 3. Other"
|
||||
- ✅ Ask: "Which option would you like to use?"
|
||||
- ✅ Wait for user to reply with their choice
|
||||
- ✅ Then call the tool they selected
|
||||
|
||||
**Your first response when this skill triggers MUST present options and ask the user to choose. No exceptions.**
|
||||
|
||||
## Workflow Overview
|
||||
|
||||
**The user MUST choose the search source. You CANNOT skip this step.**
|
||||
|
||||
1. Identify which search sources (MCP tools) are available
|
||||
2. **Present ALL available options** to the user as a numbered list
|
||||
3. **Wait for user to reply** with their selection
|
||||
4. Execute the selected search method
|
||||
5. Return results for the user to choose from
|
||||
|
||||
If you skip steps 2-3 and call a search tool directly, you are not following this skill correctly.
|
||||
|
||||
## Discovering Available Search Sources
|
||||
|
||||
**Step 1: Check your available MCP tools**
|
||||
|
||||
Look at your environment and identify which of these tools you have:
|
||||
- Do you have `search_media_cms_channels`? → If YES, include "Search using keywords"
|
||||
- Do you have `search_electronic_media`? → If YES, include "Search using Data 360 hybrid search"
|
||||
- Do you have any Unsplash tool? → If YES, include "Unsplash"
|
||||
- Always include "Other" as the last option
|
||||
|
||||
**Step 2: Build your response**
|
||||
|
||||
Your first response must follow this structure exactly:
|
||||
|
||||
```
|
||||
I'll help you find that image. Here are your search options:
|
||||
|
||||
[NUMBER]. [SEARCH SOURCE NAME] — [Brief description]
|
||||
[NUMBER]. [SEARCH SOURCE NAME] — [Brief description]
|
||||
[NUMBER]. Other — Provide your own URL or path
|
||||
|
||||
Which option would you like to use?
|
||||
```
|
||||
|
||||
**Step 3: Stop and wait**
|
||||
|
||||
After presenting options, STOP. Do not proceed until the user replies with their choice.
|
||||
|
||||
### Example First Response
|
||||
|
||||
```
|
||||
I'll help you find that image. Let me check which search sources are available.
|
||||
|
||||
Available search sources:
|
||||
1. Search using Data 360 hybrid search — Semantic search across Salesforce CMS and connected DAMs
|
||||
2. Search using keywords — Search Salesforce CMS by keywords and taxonomies
|
||||
3. Other — Provide your own URL or path
|
||||
|
||||
Which option would you like to use?
|
||||
```
|
||||
|
||||
If no automated search tools are available:
|
||||
```
|
||||
No automated media sources are currently configured. Please provide a direct URL or asset library path.
|
||||
```
|
||||
|
||||
**Example (all sources available):**
|
||||
```
|
||||
I can help you find that image. Where would you like to search?
|
||||
|
||||
1. **Search using Data 360 hybrid search** — Semantic search across Salesforce CMS and connected DAMs
|
||||
2. **Search using keywords** — Search Salesforce CMS by keywords and taxonomies
|
||||
3. **Unsplash** — Free stock photos
|
||||
4. **Other** — Provide your own URL or path
|
||||
```
|
||||
|
||||
**Example (only keyword search available):**
|
||||
```
|
||||
I can help you find that image. Where would you like to search?
|
||||
|
||||
1. **Search using keywords** — Search Salesforce CMS by keywords and taxonomies
|
||||
2. **Other** — Provide your own URL or path
|
||||
```
|
||||
|
||||
**Example (no automated sources):**
|
||||
```
|
||||
No automated media sources are currently configured. Please provide:
|
||||
1. **Direct URL or asset library path**
|
||||
```
|
||||
|
||||
**Wait for the user to select** before proceeding.
|
||||
|
||||
## Executing the Selected Search Method
|
||||
|
||||
**⚠️ ONLY reach this step if the user has explicitly selected an option from your numbered list.**
|
||||
|
||||
If you haven't shown options yet, go back to the "Discovering Available Search Sources" section first.
|
||||
|
||||
After the user selects an option, execute the corresponding search method below.
|
||||
|
||||
### Search using keywords
|
||||
|
||||
**Tool:** `search_media_cms_channels`
|
||||
|
||||
**Process:**
|
||||
|
||||
1. **Analyze the query** — Understand what the user is searching for (subject, attributes, domain)
|
||||
|
||||
2. **Extract keywords** — Concrete nouns that would appear in image metadata
|
||||
- Use domain-specific synonyms
|
||||
- Maximum 10 terms
|
||||
- Examples:
|
||||
- "luxury apartments" → apartment, villa, penthouse, residence, condo
|
||||
- "company logo" → logo, brand, emblem, corporate logo
|
||||
- "bright room" → _(empty if no concrete nouns)_
|
||||
|
||||
3. **Extract taxonomies** — Descriptive qualities, styles, moods, categories
|
||||
- Only adjectives and attributes
|
||||
- Examples:
|
||||
- "luxury apartment with river view" → Luxury, Premium, Waterfront, Riverside, Panoramic
|
||||
- "bright spacious room" → Bright, Spacious, Open, Airy, Light
|
||||
- "car" → _(empty if no descriptive terms)_
|
||||
|
||||
4. **Determine locale** — Use format `en_US`, `es_MX`, `fr_FR` (default: `en_US`)
|
||||
|
||||
5. **Build the JSON payload** — Construct this exact structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"inputs": [{
|
||||
"searchKeyword": "keyword1 OR keyword2 OR keyword3",
|
||||
"taxonomyExpression": "{\"OR\": [\"Taxonomy1\", \"Taxonomy2\"]}",
|
||||
"searchLanguage": "en_US",
|
||||
"channelIds": "",
|
||||
"channelType": "PublicUnauthenticated",
|
||||
"contentTypeFqns": "sfdc_cms__image",
|
||||
"pageOffset": 0,
|
||||
"searchLimit": 5
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
**Field rules:**
|
||||
- `searchKeyword`: Join keywords with ` OR ` (space-OR-space). Use empty string if no keywords.
|
||||
- `taxonomyExpression`: Stringify JSON object `{"OR": ["term1", "term2"]}`. Use `"{}"` if no taxonomies.
|
||||
- `searchLanguage`: Locale with underscore (e.g., `en_US`)
|
||||
- `channelIds`: Always empty string
|
||||
- `channelType`: Always `"PublicUnauthenticated"`
|
||||
- `contentTypeFqns`: Always `"sfdc_cms__image"`
|
||||
- `pageOffset`: Start at `0`, increment by `searchLimit` for pagination
|
||||
- `searchLimit`: Default `5`, adjust if user requests more
|
||||
|
||||
**Examples:**
|
||||
|
||||
Query: "luxury apartment with river view"
|
||||
```json
|
||||
{
|
||||
"inputs": [{
|
||||
"searchKeyword": "apartment OR villa OR penthouse OR residence",
|
||||
"taxonomyExpression": "{\"OR\": [\"Luxury\", \"Premium\", \"Waterfront\", \"Riverside\"]}",
|
||||
"searchLanguage": "en_US",
|
||||
"channelIds": "",
|
||||
"channelType": "PublicUnauthenticated",
|
||||
"contentTypeFqns": "sfdc_cms__image",
|
||||
"pageOffset": 0,
|
||||
"searchLimit": 5
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
Query: "bright spacious room" (no concrete nouns)
|
||||
```json
|
||||
{
|
||||
"inputs": [{
|
||||
"searchKeyword": "",
|
||||
"taxonomyExpression": "{\"OR\": [\"Bright\", \"Spacious\", \"Open\", \"Airy\"]}",
|
||||
"searchLanguage": "en_US",
|
||||
"channelIds": "",
|
||||
"channelType": "PublicUnauthenticated",
|
||||
"contentTypeFqns": "sfdc_cms__image",
|
||||
"pageOffset": 0,
|
||||
"searchLimit": 5
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
Query: "car images" (no descriptive terms)
|
||||
```json
|
||||
{
|
||||
"inputs": [{
|
||||
"searchKeyword": "car OR automobile OR vehicle OR auto",
|
||||
"taxonomyExpression": "{}",
|
||||
"searchLanguage": "en_US",
|
||||
"channelIds": "",
|
||||
"channelType": "PublicUnauthenticated",
|
||||
"contentTypeFqns": "sfdc_cms__image",
|
||||
"pageOffset": 0,
|
||||
"searchLimit": 5
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
6. **Call the tool** with the exact JSON payload
|
||||
|
||||
### Search using Data 360 hybrid search
|
||||
|
||||
**Tool:** `search_electronic_media`
|
||||
|
||||
**Process:**
|
||||
|
||||
1. Use the user's query **as-is** — no keyword extraction or transformation needed
|
||||
2. Call `search_electronic_media`
|
||||
3. Pass the query to the tool's search parameter (check the tool's schema for the exact parameter name - likely `query` or `search_query`)
|
||||
|
||||
**Example:**
|
||||
- User query: "modern luxury apartment with natural lighting"
|
||||
- Tool call: `search_electronic_media(query="modern luxury apartment with natural lighting")`
|
||||
(Note: Check the tool's schema - parameter might be `query` or `search_query`)
|
||||
|
||||
### Unsplash
|
||||
|
||||
**Process:**
|
||||
|
||||
1. Extract simple, descriptive keywords from the user's query
|
||||
2. Call the Unsplash MCP tool with the search query
|
||||
3. Include photographer attribution in results
|
||||
|
||||
### Other (User-Provided URL)
|
||||
|
||||
Ask the user to provide:
|
||||
- Direct URL to the image
|
||||
- Asset library path
|
||||
- Specific system/location to check
|
||||
|
||||
## Presenting Search Results
|
||||
|
||||
Parse the tool response and present **ALL** results as numbered options:
|
||||
|
||||
```
|
||||
I found 4 images. Which one would you like to use?
|
||||
|
||||
1. **Luxury Apartment Exterior**
|
||||
URL: https://cms.example.com/media/luxury-apt-01.jpg
|
||||
Source: Salesforce CMS
|
||||
|
||||
2. **Modern High-Rise Building**
|
||||
URL: https://cms.example.com/media/highrise-02.jpg
|
||||
Source: Salesforce CMS
|
||||
|
||||
3. **Waterfront Residence**
|
||||
URL: https://cms.example.com/media/waterfront-03.jpg
|
||||
Source: Salesforce CMS
|
||||
|
||||
4. **Premium Condominium**
|
||||
URL: https://cms.example.com/media/condo-04.jpg
|
||||
Source: Salesforce CMS
|
||||
```
|
||||
|
||||
**Never auto-select an image.** Always wait for user choice.
|
||||
|
||||
## Applying the Selected Image
|
||||
|
||||
After the user chooses:
|
||||
|
||||
1. **Confirm** the selection with image name and URL
|
||||
2. **Apply** the URL to the user's code/component
|
||||
3. **Show** what was changed (file path and line number)
|
||||
4. **Offer** next steps:
|
||||
- Add alt text for accessibility
|
||||
- Adjust styling or dimensions
|
||||
- Find additional images
|
||||
- Optimize image loading
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Response |
|
||||
|---|---|
|
||||
| Tool unavailable | "The [source name] tool is unavailable. Would you like to try a different source?" |
|
||||
| Tool returns error | Show error message, offer retry with different terms or alternative source |
|
||||
| No results found | "No results found. Try broader keywords, removing descriptive terms, or a different source." |
|
||||
| Invalid user selection | Re-display options and ask again |
|
||||
|
||||
**Never silently fail.** Always inform the user and offer alternatives.
|
||||
|
||||
## Search Behavior Notes
|
||||
|
||||
**Search using keywords:**
|
||||
- Both keyword and taxonomy → results match keyword OR (keyword + taxonomy)
|
||||
- Empty keyword → search by taxonomy only
|
||||
- Empty taxonomy → search by keyword only
|
||||
- Use `pageOffset` for pagination (increment by `searchLimit`)
|
||||
|
||||
**Search using Data 360 hybrid search:**
|
||||
- Handles natural language queries
|
||||
- Semantic similarity matching
|
||||
- Searches across multiple connected systems
|
||||
|
||||
**Unsplash:**
|
||||
- Free to use under Unsplash License
|
||||
- Always include photographer credit
|
||||
- Note license terms when presenting results
|
||||
|
||||
## Key Principles
|
||||
|
||||
1. **Always discover sources first** — Never assume a tool exists
|
||||
2. **Present only available options** — Don't show unavailable sources
|
||||
3. **Wait for user selection** — Never auto-select a source or image
|
||||
4. **Show all results** — Let the user choose the best match
|
||||
5. **Confirm before applying** — Verify the selection before modifying code
|
||||
6. **Handle errors gracefully** — Provide clear feedback and alternatives
|
||||
Loading…
Reference in New Issue
Block a user