@salesforce/afv-skills 1.16.0 → 1.18.0

package/skills/configuring-code-analyzer/scripts/validate-config.sh

@@ -0,0 +1,153 @@
+#!/bin/bash
+# validate-config.sh
+# Validates a code-analyzer.yml configuration file.
+# Usage: bash <skill_dir>/scripts/validate-config.sh [config-file]
+#
+# If no config file is specified, looks for code-analyzer.yml in current directory.
+#
+# Exit codes:
+#   0 = Config is valid
+#   1 = Config has errors
+
+set -euo pipefail
+
+CONFIG_FILE="${1:-code-analyzer.yml}"
+
+echo "Validating: ${CONFIG_FILE}"
+echo ""
+
+# Check file exists
+if [ ! -f "$CONFIG_FILE" ]; then
+    echo "ERROR: Config file not found: ${CONFIG_FILE}"
+    echo ""
+    echo "Expected locations:"
+    echo "  - ./code-analyzer.yml"
+    echo "  - ./code-analyzer.yaml"
+    echo ""
+    echo "Generate one with: sf code-analyzer config --output-file code-analyzer.yml"
+    exit 1
+fi
+
+# Check file is not empty
+if [ ! -s "$CONFIG_FILE" ]; then
+    echo "ERROR: Config file is empty: ${CONFIG_FILE}"
+    exit 1
+fi
+
+# Basic YAML syntax check (if python3 available)
+if command -v python3 &> /dev/null; then
+    echo "Checking YAML syntax..."
+    if python3 -c "
+import yaml, sys
+try:
+    with open('${CONFIG_FILE}', 'r') as f:
+        config = yaml.safe_load(f)
+    if config is None:
+        print('WARNING: Config file is empty or contains only comments')
+        sys.exit(0)
+    if not isinstance(config, dict):
+        print('ERROR: Config must be a YAML mapping (dictionary)')
+        sys.exit(1)
+    print('YAML syntax: OK')
+except yaml.YAMLError as e:
+    print(f'ERROR: Invalid YAML syntax')
+    print(f'  {e}')
+    sys.exit(1)
+" 2>&1; then
+        echo ""
+    else
+        echo ""
+        echo "Fix YAML syntax errors before proceeding."
+        exit 1
+    fi
+else
+    echo "WARNING: python3 not found — skipping YAML syntax validation (install python3 for full checks)"
+fi
+
+# Validate known field names
+echo "Checking known fields..."
+VALID_TOP_LEVEL="config_root log_folder log_level rules engines ignores suppressions"
+
+if command -v python3 &> /dev/null; then
+    python3 -c "
+import yaml, sys
+
+with open('${CONFIG_FILE}', 'r') as f:
+    config = yaml.safe_load(f)
+
+if config is None:
+    sys.exit(0)
+
+valid_fields = set('${VALID_TOP_LEVEL}'.split())
+unknown = set(config.keys()) - valid_fields
+if unknown:
+    print(f'WARNING: Unknown top-level fields: {sorted(unknown)}')
+    print('  Valid fields: config_root, log_folder, log_level, rules, engines, ignores, suppressions')
+else:
+    print('Known fields: OK')
+
+# Check engines section
+if 'engines' in config and config['engines']:
+    valid_engines = {'pmd', 'cpd', 'eslint', 'regex', 'retire-js', 'flow', 'sfge', 'apexguru'}
+    configured_engines = set(config['engines'].keys())
+    unknown_engines = configured_engines - valid_engines
+    if unknown_engines:
+        print(f'WARNING: Unknown engine names: {sorted(unknown_engines)}')
+        print(f'  Valid engines: {sorted(valid_engines)}')
+    else:
+        print(f'Engines configured: {sorted(configured_engines)}')
+
+# Check ignores section
+if 'ignores' in config and config['ignores']:
+    if 'files' not in config['ignores']:
+        print('WARNING: ignores section should contain a \"files\" list')
+    elif not isinstance(config['ignores']['files'], list):
+        print('ERROR: ignores.files must be a list of glob patterns')
+        sys.exit(1)
+    else:
+        print(f'Ignore patterns: {len(config[\"ignores\"][\"files\"])} patterns configured')
+
+# Check rules section
+if 'rules' in config and config['rules']:
+    for engine, rules in config['rules'].items():
+        if rules and isinstance(rules, dict):
+            for rule_name, overrides in rules.items():
+                if overrides and isinstance(overrides, dict):
+                    if 'severity' in overrides:
+                        sev = overrides['severity']
+                        valid_sevs = [1, 2, 3, 4, 5, 'Critical', 'High', 'Moderate', 'Low', 'Info']
+                        if sev not in valid_sevs:
+                            print(f'WARNING: rules.{engine}.{rule_name}.severity = {sev} (expected 1-5 or Critical/High/Moderate/Low/Info)')
+
+print('')
+" 2>&1
+fi
+
+# Run sf code-analyzer config validation (if sf CLI available)
+echo ""
+echo "Running Code Analyzer validation..."
+if command -v sf &> /dev/null; then
+    if sf plugins --core 2>&1 | grep -qi "code-analyzer"; then
+        if sf code-analyzer config --config-file "$CONFIG_FILE" > /dev/null 2>&1; then
+            echo "Code Analyzer validation: PASSED"
+            echo ""
+            echo "Configuration is valid and ready to use."
+            exit 0
+        else
+            echo "Code Analyzer validation: FAILED"
+            echo ""
+            echo "Running with verbose output:"
+            sf code-analyzer config --config-file "$CONFIG_FILE" 2>&1 || true
+            exit 1
+        fi
+    else
+        echo "SKIP: Code Analyzer plugin not installed (cannot run full validation)"
+        echo "Install: sf plugins install @salesforce/plugin-code-analyzer"
+    fi
+else
+    echo "SKIP: sf CLI not available (cannot run full validation)"
+fi
+
+echo ""
+echo "Basic validation passed. Install Code Analyzer for full validation."
+exit 0

package/skills/connecting-datacloud/SKILL.md

@@ -43,7 +43,7 @@ Ask for or infer:
 ## Core Operating Rules
 
 - Verify the plugin runtime first; see [../orchestrating-datacloud/references/plugin-setup.md](../orchestrating-datacloud/references/plugin-setup.md).
-- Run the shared readiness classifier before mutating connections: `node ~/.claude/skills/orchestrating-datacloud/scripts/diagnose-org.mjs -o <org> --phase connect --json`.
+- Run the shared readiness classifier before mutating connections: `node ../orchestrating-datacloud/scripts/diagnose-org.mjs -o <org> --phase connect --json`.
 - Prefer read-only discovery before connection creation.
 - Suppress linked-plugin warning noise with `2>/dev/null` for standard usage.
 - Remember that `connection list` requires `--connector-type`.
@@ -59,7 +59,7 @@ Ask for or infer:
 
 ### 1. Classify readiness for connect work
 ```bash
-node ~/.claude/skills/orchestrating-datacloud/scripts/diagnose-org.mjs -o <org> --phase connect --json
+node ../orchestrating-datacloud/scripts/diagnose-org.mjs -o <org> --phase connect --json
 ```
 
 ### 2. Discover connector types

package/skills/creating-b2b-commerce-store/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: creating-b2b-commerce-store
 description: "Interactive workflow to create Commerce B2B Stores and retrieve storefront metadata. Use when users want to: create B2B Commerce stores, build Commerce storefronts, set up B2B stores from Vibes, retrieve Commerce metadata, deploy Commerce experiences, work with DigitalExperienceBundle for Commerce."
-Critical: "Agents must follow the interactive flow and NEVER create storefront metadata from scratch."
 compatibility: "Requires Commerce licenses, Experience Cloud, Salesforce CLI"
 metadata:
   version: "1.0"

package/skills/developing-agentforce/SKILL.md

@@ -4,7 +4,6 @@ description: "Build, modify, debug, and deploy agents with Agentforce Agent Scri
 compatibility: "Requires Agentforce license, API v66.0+, Einstein Agent User"
 metadata:
   version: "1.0"
-  last_updated: "2026-04-08"
 ---
 
 # Agent Script Skill

package/skills/generating-apex/SKILL.md

@@ -3,6 +3,7 @@ name: generating-apex
 description: "Primary Apex authoring skill for class generation, refactoring, and review. ALWAYS ACTIVATE when the user mentions Apex, .cls, triggers, or asks to create/refactor a class (service, selector, domain, batch, queueable, schedulable, invocable, DTO, utility, interface, abstract, exception, REST resource). Use this skill for requests involving SObject CRUD, mapping collections, fetching related records, scheduled jobs, batch jobs, trigger design, @AuraEnabled controllers, @RestResource endpoints, custom REST APIs, or code review of existing Apex."
 metadata:
   version: "1.0"
+  minApiVersion: "66.0"
 ---
 
 # Generating Apex

package/skills/generating-mermaid-diagrams/assets/datamodel/b2b-commerce-erd.md

@@ -22,7 +22,7 @@ Pre-built data model for Salesforce B2B Commerce using `flowchart LR` format wit
 Enrich diagram with live org data:
 
 ```bash
-python3 ~/.claude/skills/generating-mermaid-diagrams/scripts/query-org-metadata.py \
+python3 ../../scripts/query-org-metadata.py \
     --objects WebStore,WebCart,CartItem,BuyerGroup,BuyerAccount \
     --target-org myorg
 ```

package/skills/generating-mermaid-diagrams/assets/datamodel/campaigns-erd.md

@@ -21,7 +21,7 @@ Pre-built data model for Salesforce Campaigns using `flowchart LR` format with c
 Enrich diagram with live org data:
 
 ```bash
-python3 ~/.claude/skills/generating-mermaid-diagrams/scripts/query-org-metadata.py \
+python3 ../../scripts/query-org-metadata.py \
     --objects Campaign,CampaignMember,CampaignInfluence,Lead,Contact,Opportunity \
     --target-org myorg
 ```

package/skills/generating-mermaid-diagrams/assets/datamodel/consent-erd.md

@@ -24,7 +24,7 @@ Pre-built data model for Salesforce Consent Management (GDPR/Privacy) using `flo
 Enrich diagram with live org data:
 
 ```bash
-python3 ~/.claude/skills/generating-mermaid-diagrams/scripts/query-org-metadata.py \
+python3 ../../scripts/query-org-metadata.py \
     --objects Individual,ContactPointEmail,ContactPointPhone,DataUsePurpose,ContactPointConsent \
     --target-org myorg
 ```

package/skills/generating-mermaid-diagrams/assets/datamodel/files-erd.md

@@ -21,7 +21,7 @@ Pre-built data model for Salesforce Files (Content) using `flowchart LR` format
 Enrich diagram with live org data:
 
 ```bash
-python3 ~/.claude/skills/generating-mermaid-diagrams/scripts/query-org-metadata.py \
+python3 ../../scripts/query-org-metadata.py \
     --objects ContentDocument,ContentVersion,ContentDocumentLink,ContentWorkspace \
     --target-org myorg
 ```

package/skills/generating-mermaid-diagrams/assets/datamodel/forecasting-erd.md

@@ -21,7 +21,7 @@ Pre-built data model for Salesforce Collaborative Forecasts using `flowchart LR`
 Enrich diagram with live org data:
 
 ```bash
-python3 ~/.claude/skills/generating-mermaid-diagrams/scripts/query-org-metadata.py \
+python3 ../../scripts/query-org-metadata.py \
     --objects ForecastingItem,ForecastingQuota,Opportunity,OpportunitySplit \
     --target-org myorg
 ```

package/skills/generating-mermaid-diagrams/assets/datamodel/fsl-erd.md

@@ -25,7 +25,7 @@ Pre-built data model for Salesforce Field Service (formerly Field Service Lightn
 Enrich diagram with live org data:
 
 ```bash
-python3 ~/.claude/skills/generating-mermaid-diagrams/scripts/query-org-metadata.py \
+python3 ../../scripts/query-org-metadata.py \
     --objects WorkOrder,WorkOrderLineItem,ServiceAppointment,ServiceResource,ServiceTerritory \
     --target-org myorg
 ```

package/skills/generating-mermaid-diagrams/assets/datamodel/party-model-erd.md

@@ -20,7 +20,7 @@ Pre-built data model for Salesforce Party Model used in Industry Clouds (Financi
 Enrich diagram with live org data:
 
 ```bash
-python3 ~/.claude/skills/generating-mermaid-diagrams/scripts/query-org-metadata.py \
+python3 ../../scripts/query-org-metadata.py \
     --objects Account,Contact,AccountContactRelation,AccountContactRole \
     --target-org myorg
 ```

package/skills/generating-mermaid-diagrams/assets/datamodel/quote-order-erd.md

@@ -23,7 +23,7 @@ Pre-built data model for Salesforce Quotes and Orders using `flowchart LR` forma
 Enrich diagram with live org data:
 
 ```bash
-python3 ~/.claude/skills/generating-mermaid-diagrams/scripts/query-org-metadata.py \
+python3 ../../scripts/query-org-metadata.py \
     --objects Opportunity,Quote,QuoteLineItem,Order,OrderItem,Product2,Contract \
     --target-org myorg
 ```

package/skills/generating-mermaid-diagrams/assets/datamodel/revenue-cloud-erd.md

@@ -22,7 +22,7 @@ Pre-built data model for Salesforce Revenue Cloud (CPQ, Billing, Subscription Ma
 Enrich diagram with live org data:
 
 ```bash
-python3 ~/.claude/skills/generating-mermaid-diagrams/scripts/query-org-metadata.py \
+python3 ../../scripts/query-org-metadata.py \
     --objects ProductCatalog,ProductCategory,ProductSellingModel,PriceAdjustmentSchedule \
     --target-org myorg
 ```

package/skills/generating-mermaid-diagrams/assets/datamodel/sales-cloud-erd.md

@@ -22,7 +22,7 @@ Pre-built data model for Salesforce Sales Cloud using `flowchart LR` format with
 Enrich diagram with live org data:
 
 ```bash
-python3 ~/.claude/skills/generating-mermaid-diagrams/scripts/query-org-metadata.py \
+python3 ../../scripts/query-org-metadata.py \
     --objects Account,Contact,Lead,Opportunity,Product2,Campaign \
     --target-org myorg
 ```

package/skills/generating-mermaid-diagrams/assets/datamodel/salesforce-erd.md

@@ -56,7 +56,7 @@ Use `flowchart LR` (left-to-right) for data model diagrams. This format supports
 Enrich diagrams with live org data:
 
 ```bash
-python3 ~/.claude/skills/generating-mermaid-diagrams/scripts/query-org-metadata.py \
+python3 ../../scripts/query-org-metadata.py \
     --objects Account,Contact,Opportunity,Case \
     --target-org myorg
 ```

package/skills/generating-mermaid-diagrams/assets/datamodel/scheduler-erd.md

@@ -23,7 +23,7 @@ Pre-built data model for Salesforce Scheduler (Lightning Scheduler) using `flowc
 Enrich diagram with live org data:
 
 ```bash
-python3 ~/.claude/skills/generating-mermaid-diagrams/scripts/query-org-metadata.py \
+python3 ../../scripts/query-org-metadata.py \
     --objects ServiceAppointment,ServiceResource,ServiceTerritory,WorkType \
     --target-org myorg
 ```

package/skills/generating-mermaid-diagrams/assets/datamodel/service-cloud-erd.md

@@ -23,7 +23,7 @@ Pre-built data model for Salesforce Service Cloud using `flowchart LR` format wi
 Enrich diagram with live org data:
 
 ```bash
-python3 ~/.claude/skills/generating-mermaid-diagrams/scripts/query-org-metadata.py \
+python3 ../../scripts/query-org-metadata.py \
     --objects Account,Contact,Case,Entitlement,ServiceContract,Asset \
     --target-org myorg
 ```

package/skills/generating-mermaid-diagrams/assets/datamodel/territory-management-erd.md

@@ -20,7 +20,7 @@ Pre-built data model for Salesforce Enterprise Territory Management (Territory2)
 Enrich diagram with live org data:
 
 ```bash
-python3 ~/.claude/skills/generating-mermaid-diagrams/scripts/query-org-metadata.py \
+python3 ../../scripts/query-org-metadata.py \
     --objects Territory2Model,Territory2,Territory2Type,UserTerritory2Association,ObjectTerritory2Association \
     --target-org myorg
 ```

package/skills/generating-mermaid-diagrams/references/erd-conventions.md

@@ -210,7 +210,7 @@ style std fill:#f0f9ff,stroke:#0369a1,stroke-dasharray:5
 Use the provided Python script for efficient metadata queries:
 
 ```bash
-python3 ~/.claude/skills/generating-mermaid-diagrams/scripts/query-org-metadata.py \
+python3 ../scripts/query-org-metadata.py \
     --objects Account,Contact,Lead,Opportunity,Case \
     --target-org myorg \
     --output table

package/skills/generating-mermaid-diagrams/references/preview-guide.md

@@ -14,10 +14,7 @@ After generating the diagram, offer the user a localhost preview for real-time i
 2. Start preview server (runs in background):
    ```bash
    # From installed skill folder:
-   python ~/.claude/skills/generating-mermaid-diagrams/scripts/mermaid_preview.py start --file /tmp/mermaid-preview.mmd
-
-   # Or from project folder (if working locally):
-   python [project-root]/skills/generating-mermaid-diagrams/scripts/mermaid_preview.py start --file /tmp/mermaid-preview.mmd
+   python ../scripts/mermaid_preview.py start --file /tmp/mermaid-preview.mmd
    ```
 
 3. Provide URL to user:
@@ -37,7 +34,7 @@ After generating the diagram, offer the user a localhost preview for real-time i
 
 When user is done:
 ```bash
-python ~/.claude/skills/generating-mermaid-diagrams/scripts/mermaid_preview.py stop
+python ../scripts/mermaid_preview.py stop
 ```
 
 ## Preview Server Features

package/skills/harmonizing-datacloud/SKILL.md

@@ -40,7 +40,7 @@ Ask for or infer:
 ## Core Operating Rules
 
 - Inspect DMO schema before creating mappings.
-- Run the shared readiness classifier before mutating harmonization assets: `node ~/.claude/skills/orchestrating-datacloud/scripts/diagnose-org.mjs -o <org> --phase harmonize --json`.
+- Run the shared readiness classifier before mutating harmonization assets: `node ../orchestrating-datacloud/scripts/diagnose-org.mjs -o <org> --phase harmonize --json`.
 - Prefer `dmo list --all` when browsing the catalog, but use first-page `dmo list` for fast readiness checks.
 - Use `query describe` or `dmo get --json` instead of inventing unsupported describe flows.
 - Treat identity resolution runs as asynchronous and verify results after execution.
@@ -52,7 +52,7 @@ Ask for or infer:
 
 ### 1. Classify readiness for harmonize work
 ```bash
-node ~/.claude/skills/orchestrating-datacloud/scripts/diagnose-org.mjs -o <org> --phase harmonize --json
+node ../orchestrating-datacloud/scripts/diagnose-org.mjs -o <org> --phase harmonize --json
 ```
 
 ### 2. Inspect the catalog

package/skills/implementing-ui-bundle-agentforce-conversation-client/SKILL.md

@@ -1,8 +1,7 @@
 ---
 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 UI Bundle project. Covers styling (colors, fonts, spacing, borders), layout (inline vs floating, width, height, dimensions), and props (agentId, agentLabel, headerEnabled, showHeaderIcon, showAvatar, styleTokens). TRIGGER when: project contains a uiBundles/*/src/ directory and the task involves adding or modifying a chat widget, chatbot, or conversational AI; files under uiBundles/*/src/ import AgentforceConversationClient; user asks to add any chat or agent functionality to a page. DO NOT TRIGGER when: user wants to create a custom agent, chatbot, or chat widget component from scratch; the project has no uiBundles directory."
+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 UI Bundle project. TRIGGER when: project contains a uiBundles/*/src/ directory and the task involves adding or modifying a chat widget, chatbot, or conversational AI; files under uiBundles/*/src/ import AgentforceConversationClient; user asks to add any chat or agent functionality to a page. DO NOT TRIGGER when: user wants to create a custom agent, chatbot, or chat widget component from scratch; the project has no uiBundles directory."
 metadata:
-  author: ACC Components
   version: "1.1"
   package: "@salesforce/ui-bundle-template-feature-react-agentforce-conversation-client"
   sdk-package: "@salesforce/agentforce-conversation-client"

package/skills/investigating-agentforce-d360/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: investigating-agentforce-d360
-description: "Data Cloud 360° view of a single Agentforce session. Pulls 24 STDM + GenAI DMO rows via the DC Query REST API, assembles a hierarchical session tree (Interaction → Step → Generation → GatewayRequest), renders a human-readable summary with transcript + per-turn topic/action invocations + LLM generations + tool calls + audit chain. TRIGGER when user asks to trace, inspect, summarize, or describe a specific Agentforce session by session id (Agent Session UUID `019d…` or MessagingSession id `0Mw…`). Also triggers on session discovery — find/list/search sessions by time, agent, channel, outcome, or conversation text — when the user has no session id yet. DO NOT TRIGGER for design-time architecture questions (use investigating-agentforce-architecture instead) or for runtime perf/latency/SLO questions that require platform telemetry beyond Data Cloud."
+description: "Data Cloud 360° view of a single Agentforce session. TRIGGER when user asks to trace, inspect, summarize, or describe a specific Agentforce session by session id (Agent Session UUID `019d…` or MessagingSession id `0Mw…`). Also triggers on session discovery — find/list/search sessions by time, agent, channel, outcome, or conversation text — when the user has no session id yet. DO NOT TRIGGER for design-time architecture questions (use investigating-agentforce-architecture instead) or for runtime perf/latency/SLO questions that require platform telemetry beyond Data Cloud."
 metadata:
   version: "1.0"
 ---

package/skills/managing-cdc-enablement/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: managing-cdc-enablement
+description: "Use to enable Salesforce Change Data Capture (CDC) on a standard or custom object, configure a custom event channel, set a filter expression, or add enrichment fields. TRIGGER broadly on any of: 'enable CDC', 'enable Change Data Capture', 'turn on CDC', 'subscribe X to change events', 'only emit events for', 'filter change events', 'enrich change events', 'create a custom event channel'; or any mention of CDC, change events, PlatformEventChannel, PlatformEventChannelMember, EnrichedField, ChangeEvents channel, enrichment fields, change event filter; or when the user wants a downstream system to receive Salesforce data changes; or when the user touches .platformEventChannelMember-meta.xml / .platformEventChannel-meta.xml files. SKIP when publishing platform events, Pub/Sub API or REST/SOAP (use building-sf-integrations), or ManagedEventSubscription (out of scope for CDC). Always use this skill for CDC channel-membership metadata."
+metadata:
+  version: "1.0"
+---
+
+# Managing Change Data Capture Enablement
+
+Generate the metadata that subscribes Salesforce objects to Change Data Capture: `PlatformEventChannelMember` files for the default `ChangeEvents` channel or a custom channel, and `PlatformEventChannel` files for new custom channels. Covers enrichment fields, filter expressions, and the canonical naming and value formats that the Metadata API actually accepts (which differ from values that appear in many internal test fixtures and code-search hits).
+
+## Scope
+
+- **In scope**: Generating `PlatformEventChannelMember` and `PlatformEventChannel` metadata for CDC. Subscribing standard objects, custom objects, or both. Configuring enrichment fields. Configuring filter expressions. Defining custom data channels.
+- **Out of scope**: Publishing custom platform events (PE) — that's a different metadata type (`PlatformEvent`). Pub/Sub API or external Kafka/Bayeux configuration. Pricing/limits guidance — refer the user to the [CDC Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.change_data_capture.meta/change_data_capture/). Programmatic event-bus subscribers in Apex.
+
+---
+
+## Clarifying Questions
+
+Before generating, confirm with the user if not already clear:
+
+- Which entity (or entities) need CDC enablement? Standard, custom, or both?
+- Default channel (`ChangeEvents`) or a custom channel? If custom, what's the channel label?
+- Any enrichment fields needed? (Lookup IDs that the consumer needs even when they didn't change.)
+- Any filter expression needed? (A SOQL-WHERE-clause body that gates which change events emit.)
+
+---
+
+## Required Inputs
+
+Gather or infer before proceeding:
+
+- **Source entity API name(s)** — e.g. `Account`, `Lead`, `Order__c`. The skill internally translates this to the **ChangeEvent entity name** (see Workflow step 2).
+- **Channel** — either `ChangeEvents` (default) or the developer name of a custom channel ending in `__chn`.
+- **Enrichment fields (optional)** — list of field API names on the source object whose values should be included in every change event.
+- **Filter expression (optional)** — a predicate over fields on the change event payload (e.g. `Status__c != null`).
+
+Defaults unless specified:
+- Channel: `ChangeEvents` (the default CDC channel — no path prefix).
+- Enrichment fields: none.
+- Filter expression: none.
+
+If the user provides a clear, complete request, generate immediately without unnecessary back-and-forth.
+
+---
+
+## Workflow
+
+All steps are sequential. Do not skip or reorder.
+
+**Before generating anything, know the only valid CDC metadata types:** CDC is expressed entirely through `PlatformEventChannelMember` (one per subscribed entity) and `PlatformEventChannel` (only for custom channels). Do NOT use `<ChangeDataCapture>`, `.changeDataCapture-meta.xml`, `changeDataCapture/` directories, `EnableChangeDataCapture`, or `ManagedEventSubscription` — these are not in scope for CDC. If you find yourself writing any of them, stop and use a `PlatformEventChannelMember` file instead.
+
+1. **Identify the channel** — if the user names a custom channel, you'll generate a `PlatformEventChannel` file (see step 4). Otherwise use the literal value `ChangeEvents` for the default channel.
+
+2. **Translate source entity to ChangeEvent entity name** — `<selectedEntity>` is the **ChangeEvent** type, NOT the source object:
+
+   | Source object | `<selectedEntity>` value |
+   |---|---|
+   | `Account` | `AccountChangeEvent` |
+   | `Lead` | `LeadChangeEvent` |
+   | `Contact` | `ContactChangeEvent` |
+   | `Order__c` (custom) | `Order__ChangeEvent` |
+   | `MyThing__c` (custom) | `MyThing__ChangeEvent` |
+
+   For standard objects: append `ChangeEvent`. For custom objects: replace the trailing `__c` with `__ChangeEvent` (the double-underscore is preserved).
+
+3. **Generate the channel-member file** — one file per `(entity, channel)` pair. **The filename and fullName always use a SINGLE underscore between the entity stem and `ChangeEvent`** — this is independent of how `selectedEntity` is formatted in the XML body. For custom objects, drop the `__c` from the source name when forming the filename:
+
+   | Source object | Filename (and fullName) | `<selectedEntity>` (in XML) |
+   |---|---|---|
+   | `Account` | `Account_ChangeEvent.platformEventChannelMember-meta.xml` | `AccountChangeEvent` |
+   | `Lead` | `Lead_ChangeEvent.platformEventChannelMember-meta.xml` | `LeadChangeEvent` |
+   | `Order__c` | `Order_ChangeEvent.platformEventChannelMember-meta.xml` (NOT `Order__ChangeEvent`) | `Order__ChangeEvent` |
+   | `MyThing__c` | `MyThing_ChangeEvent.platformEventChannelMember-meta.xml` (NOT `MyThing__ChangeEvent`) | `MyThing__ChangeEvent` |
+
+   The custom-object case is the easiest place to slip — the filename uses single underscore, the `selectedEntity` keeps its double underscore. Read `assets/PlatformEventChannelMember-template.xml` as the structural template.
+
+4. **For a custom channel**, generate a `PlatformEventChannel` file — required if any member references a non-default channel. Derive a DeveloperName from the user's label: strip spaces and non-alphanumeric characters, convert to CamelCase, then **always** append the literal suffix `__chn`. The filename and the channel's `<eventChannel>` reference must use this exact form, otherwise the deploy fails with `Invalid channel name`:
+
+   | User says | DeveloperName | Filename |
+   |---|---|---|
+   | `Partner Sync` | `PartnerSync__chn` | `PartnerSync__chn.platformEventChannel-meta.xml` (NOT `Partner_Sync...` or `PartnerSync...`) |
+   | `Order Updates` | `OrderUpdates__chn` | `OrderUpdates__chn.platformEventChannel-meta.xml` |
+   | `data sync` | `DataSync__chn` | `DataSync__chn.platformEventChannel-meta.xml` |
+
+   Members on this channel reference it by the same DeveloperName: `<eventChannel>PartnerSync__chn</eventChannel>`. Read `assets/PlatformEventChannel-template.xml`.
+
+5. **Add enrichment fields** if requested — repeat the `<enrichedFields><name>FIELD_API_NAME</name></enrichedFields>` block for each field. The name must be a **single-hop API name on the source entity** — verified working with: standard lookup IDs (`OwnerId`, `ParentId`), custom lookup fields (`MyLookup__c`), and custom non-relationship fields (`Region__c`, `Status__c`). Relationship traversals like `Owner.Name` or `Parent.Account.Industry` are rejected by deploy with "The selected field, X.Y, isn't valid".
+
+6. **Add a filter expression** if requested — wrap the predicate in `<filterExpression>...</filterExpression>`. The body is a WHERE-clause body without the `WHERE` keyword (e.g. `Status__c != null`, not `WHERE Status__c != null`). For supported operators, field types, and pitfalls, read `references/filter-expressions.md`.
+
+---
+
+## Rules / Constraints
+
+| Constraint | Rationale |
+|---|---|
+| `<selectedEntity>` is the ChangeEvent type name, not the source object name | The Metadata API binds the member to a ChangeEvent entity — passing `Account` directly fails with "invalid event in selectedEntity". |
+| Member fullName uses **single** underscore: `Account_ChangeEvent` | The double-underscore form (`Account__ChangeEvent`) is parsed as `<namespace>__<name>` and rejected: "Cannot create a new component with the namespace: Account". |
+| Default channel value is exactly `ChangeEvents` — no path prefix | Older fixtures and some docs show `data/ChangeEvents`; the deploy returns "Unable to find the specified channel" for that value. |
+| Enrichment field names are single-hop API names on the source entity | Standard (`OwnerId`), custom lookup (`MyLookup__c`), and custom non-relationship (`Region__c`) all validate. Traversals like `Owner.Name` are rejected: "The selected field, X.Y, isn't valid". |
+| `<filterExpression>` body has no `WHERE` keyword | Deploy returns "filter expression has syntax errors: unexpected token: 'WHERE'". |
+| Filter cannot reference `IsDeleted` or do relationship traversal (`Owner.Username`) | Deploy rejects with "field is invalid". |
+| DateTime fields support **only equality** in filters (`=`, `!=`) — not `<` / `>` | Deploy returns "Only equality operators are supported for this field type or value". Use a named date literal: `LastModifiedDate = TODAY`. |
+| Filter RHS must be a literal — no field-to-field comparison | `BillingCity = ShippingCity` returns "unexpected token: 'ShippingCity'". |
+| Compound fields (e.g. `BillingAddress`) require dotted component access in filter | `BillingAddress.City = 'X'` deploys; flat `BillingCity` is rejected as "field is invalid"; raw `BillingAddress` is rejected as "has to be used with a component field". Note this is the OPPOSITE of `<enrichedFields>`, which uses flat names. |
+| Custom channel filename ends with `__chn` before the meta-xml suffix | Salesforce's MDAPI naming convention; mismatch causes deploy ambiguity. |
+| Custom channel XML must include `<channelType>data</channelType>` | Without `data`, the channel is rejected for CDC (other types exist for streaming/event channels). |
+| Source custom objects must already exist (or be deployed in the same transaction) | The ChangeEvent entity for `Foo__c` doesn't exist until `Foo__c` does; member deploy fails otherwise. |
+| Never generate a `PlatformEventChannel` file for the default `ChangeEvents` channel | The default channel is system-provided. Reference it via `<eventChannel>ChangeEvents</eventChannel>` on members, but only custom (`__chn`) channels need a channel-meta file. |
+| `PlatformEventChannelMember` accepts ONLY four elements: `<enrichedFields>`, `<eventChannel>`, `<filterExpression>`, `<selectedEntity>` | Adding `<description>`, `<isActive>`, `<masterLabel>`, or any other element fails XML schema validation: "Element {...} invalid at this location". Stick to the four documented elements. |
+| `PlatformEventChannel` accepts ONLY two elements: `<channelType>` and `<label>` | Adding `<masterLabel>`, `<description>`, etc. produces "Element {...}masterLabel invalid at this location in type PlatformEventChannel". Use `<label>`, not `<masterLabel>`. |
+| Generated metadata files only — never run `sf project deploy start` from this skill | This skill produces artifacts; deployment is a separate lifecycle concern. |
+
+---
+
+## Gotchas
+
+| Issue | Resolution |
+|---|---|
+| `Unable to find the specified channel` | Set `<eventChannel>ChangeEvents</eventChannel>` (no `data/` prefix). |
+| `The PlatformEventChannelMember can't be created because it references an invalid event in the "selectedEntity" field` | Use the ChangeEvent name, not the source object: `AccountChangeEvent`, not `Account`. |
+| `Cannot create a new component with the namespace: <Object>` | Rename the file to use a single underscore: `Account_ChangeEvent...`, not `Account__ChangeEvent...`. |
+| `The selected field, X.Y, isn't valid` (in `<enrichedFields>`) | Replace `Owner.Name` with `OwnerId`. CDC enriches the lookup automatically; only single-hop field API names validate. |
+| `filter expression has syntax errors: unexpected token: 'WHERE'` | Remove the `WHERE` keyword. The body is the predicate only. |
+| `The BillingCity field in the filter expression is invalid` (or any flat Address component) | Use the compound dotted form: `BillingAddress.City`, not `BillingCity`. See `references/filter-expressions.md` for the full compound-field matrix. |
+| Custom-object member fails with "ChangeEvent doesn't exist" | The source object isn't deployed yet. Ensure the `Foo__c` object metadata is in the same deploy or already in the org. |
+| `DUPLICATE_VALUE` on second deploy | The member is already subscribed. Either delete first or skip — CDC doesn't support upsert on members directly. |
+| `sf infra error (TypeInferenceError, DeployMetadata): Could not infer a metadata type` for a `.changeDataCapture-meta.xml` file | That file extension and metadata type don't exist. Replace the `changeDataCapture/<Entity>.changeDataCapture-meta.xml` file with a `platformEventChannelMembers/<Entity>_ChangeEvent.platformEventChannelMember-meta.xml` file. |
+| User says "subscribe Order__c" but means standard `Order` | Confirm — `OrderChangeEvent` (standard) and `Order__ChangeEvent` (custom) are different entities. |
+
+---
+
+## Output Expectations
+
+Deliverables:
+- One `force-app/.../platformEventChannelMembers/<Entity>_ChangeEvent.platformEventChannelMember-meta.xml` per subscribed entity.
+- One `force-app/.../platformEventChannels/<DevName>__chn.platformEventChannel-meta.xml` per custom channel (if any).
+
+File structure follows the templates in `assets/`.
+
+After receiving the generated files, the user can verify them with `sf project deploy start --dry-run -d <path> --target-org <alias>` before deploying. If a dry-run surfaces an unfamiliar error, `references/deploy-troubleshooting.md` maps the common deploy errors to their metadata-side fixes.
+
+---
+
+## Cross-Skill Integration
+
+| Need | Delegate to |
+|---|---|
+| Generate the source custom object | `generating-custom-object` skill |
+| Generate custom fields referenced by enrichment or filter | `generating-custom-field` skill |
+| Build a permission set for users who consume change events | `generating-permission-set` skill |
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|---|---|
+| `assets/PlatformEventChannelMember-template.xml` | Step 3 — starting structure for a channel member |
+| `assets/PlatformEventChannel-template.xml` | Step 4 — starting structure for a custom channel |
+| `references/filter-expressions.md` | Step 6 — for the supported operators and field-type matrix when writing a filter expression |
+| `references/deploy-troubleshooting.md` | When a user reports a dry-run deploy error and asks for help diagnosing it |

package/skills/managing-cdc-enablement/assets/PlatformEventChannel-template.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<PlatformEventChannel xmlns="http://soap.sforce.com/2006/04/metadata">
+    <channelType>data</channelType>
+    <label>My Custom Channel</label>
+</PlatformEventChannel>

package/skills/managing-cdc-enablement/assets/PlatformEventChannelMember-template.xml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<PlatformEventChannelMember xmlns="http://soap.sforce.com/2006/04/metadata">
+    <!-- Optional: add one <enrichedFields><name>FIELD_API_NAME</name></enrichedFields> per field. Single-hop API names only (e.g. OwnerId, ParentId, MyLookup__c, Region__c). -->
+
+    <!-- Default CDC channel: ChangeEvents (no path prefix). For a custom channel, use its DeveloperName, e.g. PartnerSync__chn. -->
+    <eventChannel>ChangeEvents</eventChannel>
+    <!-- Optional: add <filterExpression>YOUR_PREDICATE</filterExpression> if needed (predicate body only, no WHERE keyword). -->
+
+    <!-- ChangeEvent entity name. Standard: <Object>ChangeEvent. Custom: replace __c with __ChangeEvent. -->
+    <selectedEntity>AccountChangeEvent</selectedEntity>
+</PlatformEventChannelMember>