@salesforce/afv-skills 1.27.0 → 1.29.0

package/skills/agentforce-architecture-analyze/scripts/tests/test_write_emit_ctx.py

@@ -32,9 +32,9 @@ from . import _bootstrap  # noqa: F401
 
 
 def _tools_dir() -> pathlib.Path:
-    """Absolute path to the skill's tools/ dir — where the scripts live."""
+    """Absolute path to the skill's scripts/ dir — where the emit helpers live."""
     here = pathlib.Path(__file__).resolve()
-    return here.parent.parent.parent / "tools"
+    return here.parent.parent
 
 
 def _run_script(script_name: str, env: dict) -> subprocess.CompletedProcess:
@@ -439,7 +439,7 @@ class EmitResultPositionalSafetyTests(unittest.TestCase):
 
     def test_build_block_happy_path_auto_promotes_without_asserting(self):
         """Sanity: the assertion does NOT fire under normal operation."""
-        # Force import of emit_result from the tools/ dir.
+        # Force import of emit_result from the scripts/ dir.
         import importlib.util
         spec = importlib.util.spec_from_file_location(
             "emit_result_mod", _tools_dir() / "emit_result.py",

package/skills/agentforce-architecture-analyze/{tools → scripts}/write_emit_ctx.py

@@ -83,7 +83,7 @@ import sys
 
 # local, dependency-free token scrub mirroring the patterns in
 # `scripts/rest_client.redact_text`. Keeping the redactor inline preserves
-# the tools/ <-> scripts/ decoupling (tools/ is stdlib-only by policy) and
+# the scripts/ emit helpers (stdlib-only by policy) and
 # avoids adding a sys.path hop on every write_emit_ctx invocation. The two
 # implementations must stay in sync; the shared regex shapes are:
 # * Authorization: Bearer <token>

package/skills/agentforce-observe/references/stdm-queries.md

@@ -24,9 +24,9 @@ Methods:
 mkdir -p <project-root>/force-app/main/default/classes
 
 # Copy from the skill's apex directory
-cp ../apex/AgentforceOptimizeService.cls \
+cp ../assets/apex/AgentforceOptimizeService.cls \
    <project-root>/force-app/main/default/classes/
-cp ../apex/AgentforceOptimizeService.cls-meta.xml \
+cp ../assets/apex/AgentforceOptimizeService.cls-meta.xml \
    <project-root>/force-app/main/default/classes/
 ```
 

package/skills/automation-flow-generate/SKILL.md

@@ -189,7 +189,7 @@ When no custom objects needed:
         - `referenceTo`: (Lookup only) The target object API name
 - Include only objects and fields that are relevant to the flow being generated
 
-## 🎯 Mandatory Enhancement Rules
+## Mandatory Enhancement Rules
 - **userPrompt**: REQUIRED.
     - If the user requests a **single flow**: use the user's prompt as-is.
     - If the user requests **multiple flows**: you MUST **split** the request and write a **separate, focused `userPrompt` for each individual flow**. Each `userPrompt` must describe only ONE flow. Do NOT pass the entire multi-flow request as a single `userPrompt`. See the multiple flows section below for examples.

package/skills/design-systems-slds-apply/SKILL.md

@@ -85,7 +85,7 @@ If no LBC exists (or not using LWC), select an SLDS Blueprint. See [references/c
 
 ## Hook Naming Traps
 
-SLDS hook families do NOT all follow the same naming pattern. Agents frequently invent hooks that don't exist by assuming `{prefix}-{number}` works universally. **Always verify a hook exists** via the bundled `search-hooks.cjs` script or `metadata/hooks-index.json` before using it.
+SLDS hook families do NOT all follow the same naming pattern. Agents frequently invent hooks that don't exist by assuming `{prefix}-{number}` works universally. **Always verify a hook exists** via the bundled `search-hooks.cjs` script or `assets/hooks-index.json` before using it.
 
 ### Trap 1: Font size hooks are NOT numbered
 
@@ -130,10 +130,10 @@ Run the appropriate search command **before** emitting any SLDS artifact:
 
 | Artifact | Verification command | Source of truth |
 |----------|---------------------|-----------------|
-| Styling hook (`--slds-g-*`) | `node scripts/search-hooks.cjs --prefix "<hook-name>"` | `metadata/hooks-index.json` |
-| Utility class (`slds-*`) | `node scripts/search-utilities.cjs --search "<class-name>"` | `metadata/utilities-index.json` |
-| Blueprint / CSS class | `node scripts/search-blueprints.cjs --search "<pattern>"` then read the YAML | `metadata/blueprints/components/*.yaml` |
-| Icon | `node scripts/search-icons.cjs --query "<description>"` | `metadata/icon-metadata.json` |
+| Styling hook (`--slds-g-*`) | `node scripts/search-hooks.cjs --prefix "<hook-name>"` | `assets/hooks-index.json` |
+| Utility class (`slds-*`) | `node scripts/search-utilities.cjs --search "<class-name>"` | `assets/utilities-index.json` |
+| Blueprint / CSS class | `node scripts/search-blueprints.cjs --search "<pattern>"` then read the YAML | `assets/blueprints/components/*.yaml` |
+| Icon | `node scripts/search-icons.cjs --query "<description>"` | `assets/icon-metadata.json` |
 
 If the search returns no match: **do not use the artifact.** Find an alternative from the search results or build custom with verified hooks.
 
@@ -187,10 +187,10 @@ This skill bundles comprehensive SLDS knowledge. Read files as needed -- don't r
 
 | Folder | Content | Index |
 |--------|---------|-------|
-| `guidance/overviews/` | Foundational concepts (color, spacing, typography, etc.) | [guidance/README.md](guidance/README.md) |
-| `guidance/styling-hooks/` | Hook categories with detailed usage | [guidance/README.md](guidance/README.md) |
-| `guidance/utilities/` | 27 utility class categories | [guidance/README.md](guidance/README.md) |
-| `guidance/slds-development-guide.md` | Full SLDS development guide | -- |
+| `references/overviews/` | Foundational concepts (color, spacing, typography, etc.) | [references/README.md](references/README.md) |
+| `references/styling-hooks/` | Hook categories with detailed usage | [references/README.md](references/README.md) |
+| `references/utilities/` | 27 utility class categories | [references/README.md](references/README.md) |
+| `references/slds-development-guide.md` | Full SLDS development guide | -- |
 
 ### Raw Metadata (structured data for lookup)
 
@@ -198,10 +198,10 @@ This skill bundles comprehensive SLDS knowledge. Read files as needed -- don't r
 
 | File | Content | Lines |
 |------|---------|-------|
-| `metadata/blueprints/components/*.yaml` | 85 blueprint specs (classes, variants, a11y, HTML) | ~50-200 each |
-| `metadata/hooks-index.json` | 523 hooks with values and CSS properties | ~6,300 |
-| `metadata/icon-metadata.json` | 1,732 icons with synonyms for search | ~38,500 |
-| `metadata/utilities-index.json` | 1,147 utility classes with CSS rules | ~6,900 |
+| `assets/blueprints/components/*.yaml` | 85 blueprint specs (classes, variants, a11y, HTML) | ~50-200 each |
+| `assets/hooks-index.json` | 523 hooks with values and CSS properties | ~6,300 |
+| `assets/icon-metadata.json` | 1,732 icons with synonyms for search | ~38,500 |
+| `assets/utilities-index.json` | 1,147 utility classes with CSS rules | ~6,900 |
 
 ---
 
@@ -219,7 +219,7 @@ Identify:
 
 1. **If LWC**: Check the [Lightning Component Library](https://developer.salesforce.com/docs/component-library/overview/components) for an LBC
 2. **Search blueprints**: `node scripts/search-blueprints.cjs --search "<pattern>"`
-3. **Read the blueprint YAML**: `metadata/blueprints/components/<name>.yaml` for exact classes, modifiers, states, and accessibility requirements
+3. **Read the blueprint YAML**: `assets/blueprints/components/<name>.yaml` for exact classes, modifiers, states, and accessibility requirements
 4. **No match?** Build custom with hooks (see Phase 3)
 
 Details: [references/component-selection.md](references/component-selection.md)
@@ -249,7 +249,7 @@ npx @salesforce-ux/slds-linter@latest lint <component-path>
 
 The linter catches hardcoded values, class overrides, and deprecated tokens. **Fix all violations before proceeding.** Do not rationalize violations as acceptable.
 
-**Step 2: Verify no invented hooks.** Confirm every `--slds-g-*` hook in the output exists in `metadata/hooks-index.json`. Cross-reference against the T051 check in [checklists.md](checklists.md).
+**Step 2: Verify no invented hooks.** Confirm every `--slds-g-*` hook in the output exists in `assets/hooks-index.json`. Cross-reference against the T051 check in [checklists.md](checklists.md).
 
 **Step 3: Run through [checklists.md](checklists.md)** for the checks the linter cannot automate:
 - All `var(--slds-g-*)` have fallback values (T002)

package/skills/design-systems-slds-apply/checklists.md

@@ -22,7 +22,7 @@ Code produced by this skill should score high on T-series checks.
 | **Shadow hooks** | Shadows use `var(--slds-g-shadow-*)` | T040 |
 | **Border radius hooks** | Border radius uses `var(--slds-g-radius-*)` | T041 |
 | **Color hooks numbered** | Every `--slds-g-color-*` hook ends in a number (no bare `on-surface`, `on-accent`, etc.) | T050 |
-| **No invented hooks** | Every hook referenced actually exists in `metadata/hooks-index.json` | T051 |
+| **No invented hooks** | Every hook referenced actually exists in `assets/hooks-index.json` | T051 |
 | **No hardcoded colors** | No hex, rgb, or named colors (linter also catches this) | linter |
 | **No class overrides** | No `.slds-*` class overrides (linter also catches this) | linter |
 | **No deprecated tokens** | No `--lwc-*` tokens (linter also catches this) | linter |

package/skills/design-systems-slds-apply/examples.md

@@ -24,7 +24,7 @@ node scripts/search-blueprints.cjs --search "modal"
 # Found: Modals (category: Overlay, root: slds-modal)
 ```
 
-**Read blueprint YAML** for class details: `metadata/blueprints/components/modals.yaml`
+**Read blueprint YAML** for class details: `assets/blueprints/components/modals.yaml`
 
 Key takeaway: `LightningModal` handles the `slds-modal`, `slds-backdrop`, and ARIA attributes automatically. No need to apply blueprint classes manually in LWC.
 
@@ -99,8 +99,8 @@ node scripts/search-blueprints.cjs --search "badge"
 ```
 
 **Read YAMLs:**
-- `metadata/blueprints/components/cards.yaml` -- classes: `slds-card`, `slds-card__header`, `slds-card__body`, `slds-card__footer`
-- `metadata/blueprints/components/badges.yaml` -- classes: `slds-badge`, modifiers: `slds-badge_lightest`, `slds-badge_inverse`
+- `assets/blueprints/components/cards.yaml` -- classes: `slds-card`, `slds-card__header`, `slds-card__body`, `slds-card__footer`
+- `assets/blueprints/components/badges.yaml` -- classes: `slds-badge`, modifiers: `slds-badge_lightest`, `slds-badge_inverse`
 
 ### Phase 3: Apply Styling
 

package/skills/design-systems-slds-apply/references/component-selection.md

@@ -68,7 +68,7 @@ node scripts/search-blueprints.cjs --name "modals"
 
 ### How to read a blueprint YAML
 
-Each file in `metadata/blueprints/components/{name}.yaml` contains:
+Each file in `assets/blueprints/components/{name}.yaml` contains:
 
 ```yaml
 name: "Modals"
@@ -107,6 +107,6 @@ Rules for custom components:
 
 ## Deep Reference
 
-- Full blueprint details: `guidance/blueprints-index.md`
-- All blueprint YAMLs: `metadata/blueprints/components/`
+- Full blueprint details: `references/blueprints-index.md`
+- All blueprint YAMLs: `assets/blueprints/components/`
 - LBC documentation: [Lightning Component Library](https://developer.salesforce.com/docs/component-library/overview/components)

package/skills/design-systems-slds-apply/references/icons-decision-guide.md

@@ -119,6 +119,6 @@ Key classes:
 
 ## Deep Reference
 
-- Icon implementation guidance: `guidance/icons-guidance.md`
-- Icons overview: `guidance/overviews/icons.md`
-- Full icon metadata (1,732 icons with synonyms): `metadata/icon-metadata.json`
+- Icon implementation guidance: `references/icons-guidance.md`
+- Icons overview: `references/overviews/icons.md`
+- Full icon metadata (1,732 icons with synonyms): `assets/icon-metadata.json`

package/skills/design-systems-slds-apply/{guidance → references}/slds-development-guide.md

@@ -158,13 +158,13 @@ export default class MyModal extends LightningModal {
 
 ## Core Rules
 
-### Do ✅
+### Do
 - Follow hierarchy: LBC → Blueprints → Styling Hooks → Custom CSS
 - Use `var(--slds-g-*)` with fallbacks for all themeable values
 - Create custom classes (e.g., `my-*`) instead of overriding `.slds-*`
 - Verify components/hooks exist before implementing
 
-### Don't ❌
+### Don't
 - Hard-code colors, spacing, or typography
 - Override `.slds-*` classes directly
 - Use deprecated `--lwc-*` tokens as primary values

package/skills/design-systems-slds-apply/references/styling-decision-guide.md

@@ -24,7 +24,7 @@ Component hooks are scoped to specific Lightning Base Components. To find availa
 2. **Browser DevTools**: Render the LBC, inspect the element, and look for `--slds-c-*` properties in the computed styles
 3. **Known patterns**: Component hooks follow `--slds-c-{component}-{property}-{state}` naming, e.g., `--slds-c-button-success-shadow-hover`
 
-There is no centralized metadata file for `--slds-c-*` hooks — they are documented per-component. Some examples exist in `guidance/overviews/shadows.md` and `guidance/styling-hooks/index.md`.
+There is no centralized metadata file for `--slds-c-*` hooks — they are documented per-component. Some examples exist in `references/overviews/shadows.md` and `references/styling-hooks/index.md`.
 
 ---
 
@@ -46,7 +46,7 @@ Always use `var()` with a fallback value:
 
 The fallback in `var(--slds-g-*, fallback)` is used when the hook isn't loaded (e.g., outside Lightning Experience, in static HTML previews, or during SSR). Use the **light-mode default** value:
 
-1. **Look up the value in `metadata/hooks-index.json`** — each hook has a `value` field showing its resolved default
+1. **Look up the value in `assets/hooks-index.json`** — each hook has a `value` field showing its resolved default
 2. **Use the search script**: `node scripts/search-hooks.cjs --prefix "--slds-g-color-surface-"` shows values
 3. **Common defaults**: `#ffffff` for surfaces, `#181818` for text, `1rem` for spacing-4, `0.25rem` for radius-border-2
 
@@ -218,11 +218,11 @@ Some dimension values have no SLDS hook (e.g., `min-width: 7rem` for label align
 
 ## Deep Reference
 
-- Styling hooks index: `guidance/styling-hooks/index.md`
-- Color hooks deep dive: `guidance/styling-hooks/color/`
-- Color overview (85-5-10 rule): `guidance/overviews/color.md`
-- Spacing overview: `guidance/overviews/spacing.md`
-- Typography hooks: `guidance/styling-hooks/typography.md`
-- Borders overview: `guidance/overviews/borders.md`
-- Shadows overview: `guidance/overviews/shadows.md`
-- All 523 hooks searchable: `metadata/hooks-index.json`
+- Styling hooks index: `references/styling-hooks/index.md`
+- Color hooks deep dive: `references/styling-hooks/color/`
+- Color overview (85-5-10 rule): `references/overviews/color.md`
+- Spacing overview: `references/overviews/spacing.md`
+- Typography hooks: `references/styling-hooks/typography.md`
+- Borders overview: `references/overviews/borders.md`
+- Shadows overview: `references/overviews/shadows.md`
+- All 523 hooks searchable: `assets/hooks-index.json`

package/skills/design-systems-slds-apply/{guidance → references}/styling-hooks/index.md

@@ -245,7 +245,7 @@ font-size: var(--slds-g-font-size-base); /* Or use rem values */
 
 ## Critical Rules
 
-### ✅ DO:
+### DO:
 
 - Reference hooks with `var()`: `color: var(--slds-g-color-accent-1);`
 - Use numbered spacing: `spacing-4` not `spacing-medium`
@@ -254,7 +254,7 @@ font-size: var(--slds-g-font-size-base); /* Or use rem values */
 - Pair container colors with on-colors for text/icons
 - Follow the 50-point rule for text contrast, 40-point rule for UI elements
 
-### ❌ DON'T:
+### DON'T:
 
 - Reassign hook values: `--slds-g-color-accent-1: #ff0000;` ❌
 - Use private hooks (`--_slds-*` or `--slds-s-*`)

package/skills/design-systems-slds-apply/references/utilities-quick-ref.md

@@ -120,6 +120,6 @@ node scripts/search-utilities.cjs --pattern "slds-p-around_*"
 
 ## Deep Reference
 
-- Utility index: `guidance/utilities/index.md`
-- Individual category guides: `guidance/utilities/{category}.md`
-- Full metadata (1,147 classes): `metadata/utilities-index.json`
+- Utility index: `references/utilities/index.md`
+- Individual category guides: `references/utilities/{category}.md`
+- Full metadata (1,147 classes): `assets/utilities-index.json`

package/skills/design-systems-slds-apply/scripts/search-blueprints.cjs

@@ -13,7 +13,7 @@
 const fs = require('fs');
 const path = require('path');
 
-const BLUEPRINTS_DIR = path.join(__dirname, '..', 'metadata', 'blueprints', 'components');
+const BLUEPRINTS_DIR = path.join(__dirname, '..', 'assets', 'blueprints', 'components');
 
 function loadBlueprints() {
   const blueprints = [];
@@ -67,7 +67,7 @@ function run() {
     console.log(`Category: ${bp.category}`);
     console.log(`Root class: ${bp.rootClass}`);
     console.log(`Description: ${bp.description}`);
-    console.log(`\nFull YAML: metadata/blueprints/components/${bp.file}.yaml`);
+    console.log(`\nFull YAML: assets/blueprints/components/${bp.file}.yaml`);
     console.log('\nRead the full YAML file for classes, modifiers, states, accessibility, and example HTML.');
     return;
   }

package/skills/design-systems-slds-apply/scripts/search-hooks.cjs

@@ -15,7 +15,7 @@
 const fs = require('fs');
 const path = require('path');
 
-const INDEX_PATH = path.join(__dirname, '..', 'metadata', 'hooks-index.json');
+const INDEX_PATH = path.join(__dirname, '..', 'assets', 'hooks-index.json');
 
 function loadHooks() {
   if (!fs.existsSync(INDEX_PATH)) {

package/skills/design-systems-slds-apply/scripts/search-icons.cjs

@@ -13,7 +13,7 @@
 const fs = require('fs');
 const path = require('path');
 
-const ICONS_PATH = path.join(__dirname, '..', 'metadata', 'icon-metadata.json');
+const ICONS_PATH = path.join(__dirname, '..', 'assets', 'icon-metadata.json');
 
 function loadIcons() {
   if (!fs.existsSync(ICONS_PATH)) {

package/skills/design-systems-slds-apply/scripts/search-utilities.cjs

@@ -13,8 +13,8 @@
 const fs = require('fs');
 const path = require('path');
 
-const INDEX_PATH = path.join(__dirname, '..', 'metadata', 'utilities-index.json');
-const GUIDANCE_DIR = path.join(__dirname, '..', 'guidance', 'utilities');
+const INDEX_PATH = path.join(__dirname, '..', 'assets', 'utilities-index.json');
+const GUIDANCE_DIR = path.join(__dirname, '..', 'references', 'utilities');
 
 function loadUtilities() {
   if (!fs.existsSync(INDEX_PATH)) {
@@ -100,7 +100,7 @@ function run() {
 
     const guidePath = path.join(GUIDANCE_DIR, `${catKey}.md`);
     if (fs.existsSync(guidePath)) {
-      console.log(`\nDetailed guidance: guidance/utilities/${catKey}.md`);
+      console.log(`\nDetailed guidance: references/utilities/${catKey}.md`);
     }
     return;
   }

package/skills/dx-code-analyzer-configure/SKILL.md

@@ -1,15 +1,32 @@
 ---
 name: dx-code-analyzer-configure
-description: "Set up, configure, and troubleshoot Salesforce Code Analyzer for any project. Handles installation, prerequisite checks, diagnosing broken setups, creating and editing code-analyzer.yml overrides, engine-specific settings, ignore patterns, severity overrides, and CI/CD pipeline setup. TRIGGER when: user says 'set up code analyzer', 'configure code analyzer', 'install code analyzer', 'code analyzer not working', 'fix my setup', 'scan is failing', 'check my setup', 'is code analyzer installed', 'enable/disable engine', 'exclude files', 'change severity', 'set up GitHub Actions', 'set up CI/CD', 'add code analyzer to pipeline', 'make pipeline fail', 'update my workflow', 'quality gate', 'fail on violations', 'scan changed files only', 'add SARIF', 'code-analyzer.yml', 'ESLint config', 'increase SFGE memory', or reports errors running Code Analyzer. DO NOT TRIGGER when: user wants to run a scan (use dx-code-analyzer-run), fix violations, explain rules, create custom rules, or suppress violations."
+description: "Set up, configure, and troubleshoot Salesforce Code Analyzer for any project. Handles installation, prerequisite checks, diagnosing broken setups, creating and editing code-analyzer.yml overrides, engine-specific settings, ignore patterns, severity overrides, and CI/CD pipeline setup. TRIGGER when: user says 'set up code analyzer', 'configure code analyzer', 'install code analyzer', 'code analyzer not working', 'fix my setup', 'scan failing', 'check my setup', 'enable/disable engine', 'exclude files', 'change severity', 'set up GitHub Actions', 'set up CI/CD', 'add to pipeline', 'pipeline fail', 'update my workflow', 'quality gate', 'fail on violations', 'scan changed files only', 'add SARIF', 'code-analyzer.yml', 'ESLint config', 'increase SFGE memory', or reports errors running Code Analyzer. DO NOT TRIGGER when: user wants to run a scan (use dx-code-analyzer-run), fix violations, explain rules, create custom rules (use dx-code-analyzer-custom-rule-create), or suppress violations."
 metadata:
   version: "1.0"
-  argument-hint: "[--check-prerequisites] [--generate-config] [--engine pmd|eslint|cpd|retire-js|regex|flow|sfge|apexguru] [--ci github-actions|jenkins]"
+  relatedSkills:
+    - "dx-code-analyzer-run"
+    - "dx-code-analyzer-custom-rule-create"
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+    - tool: ["java"]
+      semver: ">=11.0.0"
+    - tool: ["node"]
+      semver: ">=18.0.0"
+    - tool: ["python3"]
+      semver: ">=3.10.0"
+    - tool: ["git"]
+      semver: ">=2.0.0"
+    - tool: ["npm"]
+      semver: ">=9.0.0"
 ---
 
 # Configuring Code Analyzer Skill
 
 ## Overview
 
+> **Ecosystem:** This skill is part of a 3-skill Code Analyzer suite — `dx-code-analyzer-run` (scans & results) · `dx-code-analyzer-configure` (setup, config, CI/CD) · `dx-code-analyzer-custom-rule-create` (custom rule authoring).
+
 This skill manages the `code-analyzer.yml` configuration file — the single source of truth for how Code Analyzer behaves in a project. All customization (engines, rules, ignores, suppressions) is done by creating or editing this file. If the file doesn't exist, this skill creates it in the current working directory.
 
 ---
@@ -26,8 +43,9 @@ This skill manages the `code-analyzer.yml` configuration file — the single sou
 - Environment validation and troubleshooting
 
 **Out of scope:**
-- Running scans (use `dx-code-analyzer-run` skill)
-- Fixing violations, explaining rules, creating custom rules, suppression management
+- Running scans → use `dx-code-analyzer-run` skill
+- Fixing violations, explaining rules, suppression management → use `dx-code-analyzer-run` skill
+- Creating custom rules → use `dx-code-analyzer-custom-rule-create` skill
 
 ---
 
@@ -127,7 +145,7 @@ ls code-analyzer.yml code-analyzer.yaml 2>/dev/null
 
 The CLI auto-discovers `code-analyzer.yml` in the current directory. Since scans run from project root, the file must live there.
 
-### ⚠️ Rule Name Resolution — ALWAYS Before Writing YAML
+### Rule Name Resolution — ALWAYS Before Writing YAML
 
 When a user references rules by partial, descriptive, or approximate names (e.g., "the doc rule", "CRUD violation", "console rule", "hardcoded values"), you MUST resolve to exact rule names using the lookup in **Step 6.1** BEFORE writing any YAML. The `code-analyzer.yml` file silently ignores rule names that don't exactly match — there is no error, the override just won't apply.
 
@@ -381,14 +399,10 @@ engines:
     target_org: "my-org-alias"
   flow:
     python_command: "python3"
-  regex:
-    custom_rules:
-      NoHardcodedIds:
-        regex: "/[a-zA-Z0-9]{15,18}/"
-        file_extensions: [".cls", ".trigger"]
-        description: "Detects hardcoded Salesforce record IDs"
-        severity: 2
-        tags: ["Security"]
+  # regex.custom_rules — use the dx-code-analyzer-custom-rule-create skill to create these.
+  # Never hand-write regex patterns into code-analyzer.yml: quotes/backslashes
+  # inside YAML cause parsing failures. The create-regex-rule.js script handles
+  # serialization correctly and must always be used for regex rule creation.
 ```
 
 For full property list per engine, read `<skill_dir>/references/config-schema.md`.
@@ -427,9 +441,13 @@ If a user says "scan my code" / "run code analyzer" but it fails (CLI missing, p
 
 After any successful configuration action, offer to run a scan (e.g., "Setup complete! Want me to run a scan?", "Config updated — want to scan and verify?"). If user says yes, proceed with `dx-code-analyzer-run` behavior.
 
+### When THIS skill hands off to `dx-code-analyzer-custom-rule-create`:
+
+If the user asks to create a custom rule while you are working on configuration (e.g., "also add a rule that bans System.debug", "set up a PMD XPath rule"), delegate to `dx-code-analyzer-custom-rule-create`. When that skill finishes, the `custom_rulesets` or `eslint_config_file` pointer in `code-analyzer.yml` may need to be set — that edit belongs here, in this skill.
+
 ### When user intent spans BOTH skills:
 
-Handle end-to-end: "not working" → Diagnose → Fix → Scan. "Set up and scan" → Install → Scan. "Disable ESLint and scan Apex" → Edit config → Run with `--rule-selector pmd`. Always follow through to the user's final intent.
+Handle end-to-end: "not working" → Diagnose → Fix → Scan. "Set up and scan" → Install → Scan. "Disable ESLint and scan Apex" → Edit config → Run with `--rule-selector pmd`. "Configure custom rules and scan" → dx-code-analyzer-custom-rule-create → wire config → dx-code-analyzer-run. Always follow through to the user's final intent.
 
 ---