skill description improvements

clavery · clavery · commit 81ffd499cde5 · 2026-01-22T14:58:49.000-05:00
diff --git a/.claude/skills/skill-authoring/SKILL.md b/.claude/skills/skill-authoring/SKILL.md
@@ -31,7 +31,43 @@ description: Brief description of what the skill does
 ```
 
 - **name**: Unique identifier (lowercase, hyphens)
-- **description**: One-line summary (loaded at startup for all skills)
+- **description**: Rich description for skill discovery (1-1024 characters)
+
+### Writing Effective Descriptions
+
+The description field is **critical for skill discovery** by coding agents. It should include:
+
+1. **What the skill does** - Core functionality
+2. **When to use it** - Trigger scenarios
+3. **Keywords** - Task-oriented phrases that help agents connect questions to skills
+
+**Format:**
+```yaml
+description: "[What it does]. Use when [scenarios]. Keywords/phrases."
+```
+
+**Good examples:**
+```yaml
+# Task-oriented phrases help agents connect "how do I" questions
+description: Search and read B2C Commerce Script API documentation and XSD schemas. Use when writing B2C scripts, looking up classes like URLUtils/ProductMgr/CustomerMgr, or answering "how do I" questions about generating URLs, querying products, processing orders, or any dw.* API task.
+
+# Include common error scenarios
+description: View and debug B2C CLI configuration. Use when authentication fails, connection errors occur, wrong instance is used, or you need to verify dw.json settings, environment variables, or OAuth credentials.
+
+# Disambiguation helps agents choose the right skill
+description: Run and monitor existing jobs, import/export site archives. Use when executing batch jobs, importing site data, or checking job status. For creating new job code, use b2c-custom-job-steps instead.
+```
+
+**Bad examples:**
+```yaml
+# Too brief - no discovery keywords
+description: Using the b2c CLI for documentation
+
+# Action-oriented instead of problem-oriented
+description: Using the b2c CLI to search and read Script API documentation
+```
+
+**Key insight:** Include **task-oriented phrases** ("generating URLs", "querying products") not just class names, since users ask about tasks they want to accomplish.
 
 ### Instructions Body
 
@@ -40,21 +76,13 @@ The body contains markdown instructions that tell the agent how to perform the t
 ```markdown
 ---
 name: my-skill
-description: Does something useful
+description: Does something useful. Use when [scenarios]. Keywords: [task phrases].
 ---
 
 # Skill Title
 
 Brief overview of what this skill helps accomplish.
 
-## When to Use
-
-Describe scenarios when this skill applies.
-
-## How to Use
-
-Step-by-step instructions or patterns.
-
 ## Examples
 
 Concrete examples demonstrating usage.
@@ -64,6 +92,8 @@ Concrete examples demonstrating usage.
 - [Detailed Reference](references/REFERENCE.md) - Link to additional docs
 ```
 
+Note: The description frontmatter is the **only** discovery mechanism. "When to Use" sections in the body are not used for discovery. Put all discovery-relevant information in the description.
+
 ## Progressive Disclosure
 
 Structure skills for efficient context usage:
diff --git a/plugins/b2c-cli/skills/b2c-code/SKILL.md b/plugins/b2c-cli/skills/b2c-code/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: b2c-code
-description: Using the b2c CLI for code version deployment and management
+description: Deploy and manage code versions on B2C Commerce instances. Use when uploading cartridges, activating code versions, watching for file changes during development, or syncing local code to sandbox.
 ---
 
 # B2C Code Skill
diff --git a/plugins/b2c-cli/skills/b2c-config/SKILL.md b/plugins/b2c-cli/skills/b2c-config/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: b2c-config
-description: Using the b2c CLI to view and debug current configuration for instance, SCAPI, oauth and MRT settings.
+description: View and debug B2C CLI configuration and understand where credentials come from. Use when authentication fails, connection errors occur, wrong instance is used, or you need to verify dw.json settings, environment variables (SFCC_*), or OAuth credentials are loaded correctly.
 ---
 
 # B2C Config Skill
diff --git a/plugins/b2c-cli/skills/b2c-docs/SKILL.md b/plugins/b2c-cli/skills/b2c-docs/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: b2c-docs
-description: Using the b2c CLI to search and read Script API documentation and XSD schemas
+description: Search and read B2C Commerce Script API documentation and XSD schemas. Use when writing B2C scripts, looking up classes like URLUtils/ProductMgr/CustomerMgr, or answering "how do I" questions about generating URLs, querying products, processing orders, or any dw.* API task. Also use for import/export XML format reference.
 ---
 
 # B2C Docs Skill
diff --git a/plugins/b2c-cli/skills/b2c-ecdn/SKILL.md b/plugins/b2c-cli/skills/b2c-ecdn/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: b2c-ecdn
-description: Using the b2c CLI for eCDN (embedded Content Delivery Network) management
+description: Manage eCDN (embedded Content Delivery Network) settings. Use when purging cache, configuring WAF rules, managing SSL certificates, setting rate limits, or creating CDN zones for storefronts.
 ---
 
 # B2C eCDN Skill
diff --git a/plugins/b2c-cli/skills/b2c-job/SKILL.md b/plugins/b2c-cli/skills/b2c-job/SKILL.md
@@ -1,7 +1,6 @@
 ---
 name: b2c-job
-description: Using the b2c CLI to run and monitor existing jobs, import/export site archives (IMPEX). Use this for executing jobs, not creating new job step code.
-keywords: [run job, execute job, import data, export data, site archive, IMPEX, job status, job log]
+description: Run and monitor existing jobs, import/export site archives (IMPEX). Use when executing batch jobs, importing site data, running search indexing, checking job status, or viewing job logs. For creating new job code, use b2c-custom-job-steps instead.
 ---
 
 # B2C Job Skill
diff --git a/plugins/b2c-cli/skills/b2c-mrt/SKILL.md b/plugins/b2c-cli/skills/b2c-mrt/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: b2c-mrt
-description: Using the b2c CLI for Managed Runtime (MRT) project and deployment management
+description: Deploy and manage Managed Runtime (MRT) PWA storefronts. Use when deploying bundles, managing environments, setting environment variables, configuring redirects, or working with CDN for PWA Kit projects.
 ---
 
 # B2C MRT Skill
diff --git a/plugins/b2c-cli/skills/b2c-ods/SKILL.md b/plugins/b2c-cli/skills/b2c-ods/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: b2c-ods
-description: Using the b2c CLI for on-demand sandbox (ODS) management
+description: Create and manage on-demand sandboxes (ODS). Use when provisioning development instances, starting/stopping sandboxes, checking sandbox status, or managing sandbox lifecycle. Only create or delete sandboxes when explicitly requested.
 ---
 
 # B2C ODS Skill
diff --git a/plugins/b2c-cli/skills/b2c-scapi-custom/SKILL.md b/plugins/b2c-cli/skills/b2c-scapi-custom/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: b2c-scapi-custom
-description: Using the b2c CLI for Custom SCAPI endpoint management
+description: Check Custom SCAPI endpoint registration status. Use when verifying custom API deployment, debugging "endpoint not found" errors, or checking if code activation registered new APIs. For creating new custom APIs, use b2c-custom-api-development instead.
 ---
 
 # B2C SCAPI Custom APIs Skill
diff --git a/plugins/b2c-cli/skills/b2c-scapi-schemas/SKILL.md b/plugins/b2c-cli/skills/b2c-scapi-schemas/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: b2c-scapi-schemas
-description: Using the b2c CLI to browse and retrieve SCAPI schema specifications
+description: Browse and retrieve SCAPI OpenAPI schemas. Use when exploring available SCAPI endpoints, checking API request/response formats, understanding SCAPI data models, or finding the right API for a task.
 ---
 
 # B2C SCAPI Schemas Skill
diff --git a/plugins/b2c-cli/skills/b2c-site-import-export/SKILL.md b/plugins/b2c-cli/skills/b2c-site-import-export/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: b2c-site-import-export
-description: Using the B2C CLI for site archive import/export with metadata XML patterns
+description: Work with site archive structure and metadata XML patterns. Use when adding custom attributes, system object extensions, site preferences, or understanding import/export XML schemas. Covers directory structure and XML file formats for site archives.
 ---
 
 # Site Import/Export Skill
diff --git a/plugins/b2c-cli/skills/b2c-sites/SKILL.md b/plugins/b2c-cli/skills/b2c-sites/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: b2c-sites
-description: Using the b2c CLI for storefront sites listing and inspection
+description: List and inspect storefront sites on B2C Commerce instances. Use when finding site IDs, checking site configuration, or listing available sites. Helpful for determining site context when running other commands.
 ---
 
 # B2C Sites Skill
diff --git a/plugins/b2c-cli/skills/b2c-slas/SKILL.md b/plugins/b2c-cli/skills/b2c-slas/SKILL.md
@@ -1,13 +1,13 @@
 ---
 name: b2c-slas
-description: Using the b2c CLI for SLAS (Shopper Login and API Access Service) client management
+description: Manage SLAS (Shopper Login and API Access Service) clients. Use when configuring shopper authentication, creating API clients for PWA/headless, managing OAuth scopes (including custom scopes like c_loyalty), or debugging token issues.
 ---
 
 # B2C SLAS Skill
 
 Use the `b2c` CLI plugin to manage SLAS (Shopper Login and API Access Service) API clients and credentials.
 
-## When to Use This Skill
+## When to Use
 
 Common scenarios requiring SLAS client management:
 
diff --git a/plugins/b2c-cli/skills/b2c-webdav/SKILL.md b/plugins/b2c-cli/skills/b2c-webdav/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: b2c-webdav
-description: Using the b2c CLI for WebDAV file operations (listing, upload, download, logs)
+description: List, upload, download, and manage files on B2C Commerce instances via WebDAV. Use when reading error logs (customerror, debug), downloading job logs, uploading to IMPEX directories, or managing files in cartridges/catalogs/static folders.
 ---
 
 # B2C WebDAV Skill
diff --git a/plugins/b2c/skills/b2c-business-manager-extensions/SKILL.md b/plugins/b2c/skills/b2c-business-manager-extensions/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: b2c-business-manager-extensions
-description: Guide for creating Business Manager extension cartridges in Salesforce B2C Commerce
+description: Create Business Manager extension cartridges for B2C Commerce. Use when building admin tools, BM menu items, or custom BM pages (bm_* cartridges). Covers bm_extensions.xml, menu items, dialog actions, and form extensions.
 ---
 
 # Business Manager Extensions Skill
diff --git a/plugins/b2c/skills/b2c-controllers/SKILL.md b/plugins/b2c/skills/b2c-controllers/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: b2c-controllers
-description: Guide for creating storefront controllers in Salesforce B2C Commerce (SFRA and classic patterns)
+description: Create storefront controllers in SFRA or classic B2C Commerce patterns. Use when building pages, handling form submissions, creating AJAX endpoints, or working with server.get/server.post, res.render, res.json, and middleware chains. Also covers URLUtils for URL generation.
 ---
 
 # Controllers Skill
diff --git a/plugins/b2c/skills/b2c-custom-api-development/SKILL.md b/plugins/b2c/skills/b2c-custom-api-development/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: b2c-custom-api-development
-description: Guide for developing SCAPI Custom APIs on Salesforce B2C Commerce
+description: Develop Custom SCAPI endpoints for B2C Commerce. Use when creating REST APIs, defining api.json routes, writing schema.yaml (OAS 3.0), or building headless commerce integrations. Covers cartridge structure, endpoint implementation, and OAuth scope configuration.
 ---
 
 # Custom API Development Skill
diff --git a/plugins/b2c/skills/b2c-custom-caches/SKILL.md b/plugins/b2c/skills/b2c-custom-caches/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: b2c-custom-caches
-description: Custom cache definition and usage with CacheMgr and Cache classes
+description: Implement custom caching with CacheMgr in B2C Commerce. Use when adding application-level caching, cache invalidation, or optimizing performance with custom cache regions. Covers cache definition JSON, CacheMgr API, and cache entry lifecycle.
 ---
 
 # B2C Custom Caches
diff --git a/plugins/b2c/skills/b2c-custom-job-steps/SKILL.md b/plugins/b2c/skills/b2c-custom-job-steps/SKILL.md
@@ -1,7 +1,6 @@
 ---
 name: b2c-custom-job-steps
-description: Guide for creating custom job steps for batch processing, imports, exports, scheduled tasks, and data sync in Salesforce B2C Commerce. Use this when writing new job code.
-keywords: [create job, new job, batch job, scheduled job, import job, export job, data sync, bulk processing, steptypes.json, job step code]
+description: Create custom job steps for B2C Commerce batch processing. Use when writing scheduled tasks, data sync jobs, import/export scripts, or any server-side batch processing code. Covers steptypes.json, chunk-oriented processing, and task-oriented execution. For running existing jobs, use b2c-job instead.
 ---
 
 # Custom Job Steps Skill
@@ -10,7 +9,7 @@ This skill guides you through **creating new custom job steps** for Salesforce B
 
 > **Running an existing job?** If you need to execute jobs or import site archives via CLI, use the `b2c-cli:b2c-job` skill instead.
 
-## When to Use This Skill
+## When to Use
 
 - Creating a **new scheduled job** for batch processing
 - Building a **data import job** (customers, products, orders)
diff --git a/plugins/b2c/skills/b2c-forms/SKILL.md b/plugins/b2c/skills/b2c-forms/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: b2c-forms
-description: Guide for creating forms with validation in Salesforce B2C Commerce (SFRA patterns)
+description: Create forms with validation in SFRA patterns for B2C Commerce. Use when building checkout forms, account forms, or any form with field definitions, validation rules, and error handling. Covers form XML definitions, server-side validation, and template rendering.
 ---
 
 # Forms Skill
diff --git a/plugins/b2c/skills/b2c-hooks/SKILL.md b/plugins/b2c/skills/b2c-hooks/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: b2c-hooks
-description: Hook registration, HookMgr, OCAPI/SCAPI hooks, and system extension points
+description: Implement hooks using HookMgr and extension points in B2C Commerce. Use when extending OCAPI/SCAPI behavior, handling system events like order calculation, or registering custom hook implementations. Covers hooks.json, dw.ocapi hooks, and custom extension points.
 ---
 
 # B2C Commerce Hooks
diff --git a/plugins/b2c/skills/b2c-isml/SKILL.md b/plugins/b2c/skills/b2c-isml/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: b2c-isml
-description: Guide for working with ISML templates in Salesforce B2C Commerce
+description: Work with ISML templates in B2C Commerce. Use when writing storefront templates, using isprint/isset/isloop tags, understanding ISML expressions (${...}), or creating custom template modules. Covers tag syntax, expression language, and template includes.
 ---
 
 # ISML Skill
diff --git a/plugins/b2c/skills/b2c-localization/SKILL.md b/plugins/b2c/skills/b2c-localization/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: b2c-localization
-description: Guide for localizing templates, forms, and content in Salesforce B2C Commerce
+description: Localize templates, forms, and content in B2C Commerce. Use when adding translations, working with resource bundles (*.properties files), using Resource.msg, or implementing multi-locale support. Covers locale folders, string externalization, and date/currency formatting.
 ---
 
 # Localization Skill
diff --git a/plugins/b2c/skills/b2c-logging/SKILL.md b/plugins/b2c/skills/b2c-logging/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: b2c-logging
-description: Guide for implementing logging in Salesforce B2C Commerce scripts
+description: Implement logging in B2C Commerce scripts using dw.system.Logger. Use when adding debug output, error tracking, or custom log files to server-side code. Covers getLogger, log categories, log levels (debug, info, warn, error, fatal), and custom named log files.
 ---
 
 # Logging Skill
diff --git a/plugins/b2c/skills/b2c-metadata/SKILL.md b/plugins/b2c/skills/b2c-metadata/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: b2c-metadata
-description: Guide for working with site metadata XML in Salesforce B2C Commerce
+description: Work with B2C Commerce site metadata XML for custom attributes and object types. Use when defining custom attributes on products/orders/customers, creating custom object types, or setting site preferences via XML import. Covers system-objecttype-extensions.xml and custom-objecttype-definitions.xml.
 ---
 
 # Metadata Skill
diff --git a/plugins/b2c/skills/b2c-page-designer/SKILL.md b/plugins/b2c/skills/b2c-page-designer/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: b2c-page-designer
-description: Guide for creating Page Designer pages and components in Salesforce B2C Commerce
+description: Create Page Designer pages and components in B2C Commerce. Use when building visual merchandising tools, content slots, or experience API integrations. Covers page types, component types, regions, and attribute definitions.
 ---
 
 # Page Designer Skill
diff --git a/plugins/b2c/skills/b2c-webservices/SKILL.md b/plugins/b2c/skills/b2c-webservices/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: b2c-webservices
-description: Guide for implementing web service integrations in Salesforce B2C Commerce
+description: Implement web service integrations in B2C Commerce using LocalServiceRegistry. Use when calling external APIs, configuring service credentials in services.xml, handling HTTP requests/responses, or implementing circuit breakers. Covers HTTP, SOAP, FTP, and SFTP services.
 ---
 
 # Web Services Skill
