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.
Fixing violations, explaining rules, suppression management → use dx-code-analyzer-run skill
Creating custom rules → use dx-code-analyzer-custom-rule-create skill
Tool Usage Rules
Allowed: Bash (sf, java, node, python3, git, npm), Read, Write, Edit
Forbidden: MCP tools, Agent tool, Web tools, other skills, which, find, locate, searching for binaries
Core Principle: YAML Only When Customizing
Code Analyzer works out of the box with NO config file — all defaults are built into the tool. The code-analyzer.yml file is ONLY created when the user explicitly requests a customization.
Rules:
Do NOT create code-analyzer.yml proactively — only when user asks to change something
Do NOT duplicate built-in defaults — only write entries that intentionally override behavior
Always place at project root — where sfdx-project.json or sf-project.json lives
The CLI auto-discovers it — sf code-analyzer run from project root automatically picks up code-analyzer.yml in that directory. No --config-file flag needed.
User says "configure code analyzer" with no specifics? → Ask what they want to customize. Don't create an empty or boilerplate file.
Workflow:
User requests a customization (e.g., "disable PMD", "ignore test files", "increase SFGE memory")
Check if code-analyzer.yml exists at project root
If NO → create it at project root with ONLY the requested override
If YES → read it, then edit in the requested change
Validate with sf code-analyzer config
Step 1: Understand Intent and Map to Config Sections
The user can request ANY combination of configuration changes in natural language. Your job is to:
Parse what they want — may be one thing or many things combined
Map each request to the correct section(s) of code-analyzer.yml
Create the file if it doesn't exist, then apply all changes
The code-analyzer.yml Structure (what you can write/edit)
config_root:.# Root for relative path resolutionlog_folder:<path># Where logs are writtenlog_level:<1-5># 1=Error, 2=Warn, 3=Info, 4=Debug, 5=Fineignores:# Files/folders excluded from scanningfiles: [<globpatterns>]
engines:# Per-engine settings<engine_name>:disable_engine:<bool><engine_specific_keys>:...rules:# Per-rule overrides<engine_name>:<rule_name>:severity:<1-5>tags: [<strings>]
disabled:<bool>suppressions:# Bulk suppression configurationdisable_suppressions:<bool>"<file_or_folder_path>":-rule_selector:"<selector>"max_suppressed_violations:<number|null>reason:"<why>"
Mapping Principle
Any user request maps to one or more sections above. Parse the intent and edit the right section(s):
Intent Category
Maps To
Examples of What User Might Say
Setup / Install
Step 2 (prerequisites + install)
"set up", "install", "get started", "new laptop", "from scratch"
Diagnose / Fix
Step 2A (systematic debug)
"not working", "broken", "fix my setup", "scan fails", "getting errors"
Engine control
engines.<name>.disable_engine
"disable X", "turn off Y", "only use Z", "enable all"
Engine tuning
engines.<name>.<property>
"increase memory", "change heap", "use my eslint config", "set tokens to 50"
File exclusions
ignores.files
"exclude", "ignore", "skip", "don't scan X"
Rule severity
rules.<engine>.<rule>.severity
"make X critical", "promote", "demote", "change severity"
BEFORE editing anything, check if code-analyzer.yml exists at project root:
ls code-analyzer.yml code-analyzer.yaml 2>/dev/null
File does NOT exist → Create it at project root with ONLY the user's requested override(s)
File exists → Read it, then Edit to add/modify the requested section(s)
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
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.
Examples of fuzzy → exact resolution needed:
"Disable the ApexDoc rule" → lookup confirms ApexDoc (engine: pmd)
"Demote no-console to low" → lookup confirms no-console (engine: eslint)
Give user ONE command at a time, wait for confirmation before continuing
After fix succeeds, proceed to run the full scan automatically
Step 3: Create or Edit code-analyzer.yml
Only triggered when user requests a customization. Never create proactively.
Creating (file doesn't exist)
Choose one of the two approaches below — do not run both:
Option A — Auto-generate from project type (recommended for first-time setup):
Run bash "<skill_dir>/scripts/generate-config.sh". This detects Apex, LWC, and Flow markers and produces a minimal code-analyzer.yml suited to the project. Skip to the "After any create/edit, validate" section.
Note: The script exits with an error if code-analyzer.yml already exists. Delete the existing file first if you need to regenerate.
Option B — Write manually (when the user has specific customizations in mind):
Read the appropriate example config as a reference for structure:
For Apex-only projects, read <skill_dir>/examples/apex-project-config.yml
For LWC-only projects, read <skill_dir>/examples/lwc-project-config.yml
For full-stack (Apex + LWC + Flows), read <skill_dir>/examples/fullstack-project-config.yml
Write the file at project root using the Write tool. Include ONLY the user's requested changes:
# Example: user said "ignore test files and increase SFGE memory"# → Write to project root (where sfdx-project.json lives):
Do NOT add config_root, log_folder, or any other field the user didn't ask for.
Editing (file already exists)
Read the file, then use the Edit tool to add/modify only the relevant section. Preserve everything else.
After any create/edit, validate:
Run bash "<skill_dir>/scripts/validate-config.sh" to validate YAML syntax and schema correctness, or use the CLI directly:
sf code-analyzer config
(No --config-file needed — the CLI auto-discovers code-analyzer.yml in CWD.)
If user says "configure code analyzer" with no specifics
Ask: "What would you like to customize? For example: ignore certain files, change rule severities, tune engine settings, or disable engines you don't need."
Edit the rules section in code-analyzer.yml. Each rule can have severity, tags, and disabled overrides:
rules:pmd:ApexCRUDViolation:severity:1# Promote to CriticalAvoidGlobalModifier:disabled:true# Turn off entirelyApexDoc:severity:5# Demote to Infotags: ["Documentation"]
eslint:no-console:severity:4# Demote to Lowno-unused-vars:severity:2# Promote to High
⚠️ CRITICAL: A misspelled or partial rule name in code-analyzer.yml is SILENTLY IGNORED — no error, the override just won't apply.
When users reference rules by approximate names (e.g., "the doc rule", "CRUD violation", "hardcoded values"), resolve to exact names BEFORE writing YAML:
sf code-analyzer rules --rule-selector all 2>&1 | grep -i "<USER_KEYWORD>"
1 match → use that exact name + its engine for the YAML path
Multiple matches → ask user which one they meant
0 matches → try broader keywords or inform user
Skip the lookup only when the name is unambiguous and exact (e.g., "ApexDoc", "no-console", "no-unused-vars").
For detailed matching strategies, common fuzzy→exact mappings, and engine identification: Read <skill_dir>/references/rule-name-resolution.md.
Step 7: Engine-Specific Settings
Edit the engines section. Most common overrides:
engines:sfge:java_max_heap_size:"4g"# <200 classes→"2g", 200-500→"4g", 500+→"6g"/"8g"java_thread_count:4java_thread_timeout:900000eslint:auto_discover_eslint_config:true# Use project's own ESLint configeslint_config_file:"./eslint.config.mjs"pmd:custom_rulesets: ["./config/custom-pmd-rules.xml"]
java_classpath_entries: ["./lib/custom-rules.jar"]
cpd:minimum_tokens: { apex:100, javascript:100 }
apexguru:target_org:"my-org-alias"flow:python_command:"python3"# 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.
Step 8: CI/CD Pipeline Setup
Detect CI system from workspace (.github/workflows/ → GitHub Actions, Jenkinsfile → Jenkins, etc.). Read <skill_dir>/references/ci-cd-templates.md for templates. Use <skill_dir>/examples/ci-github-actions.yml as GitHub Actions base. Key flags: --severity-threshold 2 (gate), --output-file results.sarif (GitHub scanning), --config-file code-analyzer.yml.
Step 9: View Current Configuration
sf code-analyzer config # Show effective config
sf code-analyzer config --rule-selector pmd:Security # Specific rules
sf code-analyzer config --include-unmodified-rules # All defaults
Cross-Skill Integration
This skill works together with dx-code-analyzer-run. The AI agent should seamlessly hand off between them:
When dx-code-analyzer-run delegates HERE:
If a user says "scan my code" / "run code analyzer" but it fails (CLI missing, plugin not installed, or scan errors out), dx-code-analyzer-run delegates to this skill. In that case:
Run the diagnose and fix flow (Step 2A) — find what's broken, fix it
After everything works, automatically proceed to run the scan — do not stop and ask. The user's original intent was to scan.
Hand execution back to dx-code-analyzer-run behavior (build command, execute, parse results).
When THIS skill hands off to dx-code-analyzer-run:
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. "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.
Rules / Constraints
Constraint
Rationale
Only create YAML when user requests a customization
Defaults work without any file — don't create boilerplate
Place YAML at project root only
CLI auto-discovers code-analyzer.yml from CWD
Write only overrides, never duplicate defaults
Keep file minimal and intentional
Use Write tool to create, Edit tool to modify
Preserves existing settings
Validate after every change
sf code-analyzer config catches YAML errors
Ask before installing prerequisites
Never auto-install without consent
Never delete existing config without asking
User may have custom settings
After setup, offer to scan
Close the loop — config without scan is incomplete
Gotchas
Issue
Solution
Config not picked up
Must be code-analyzer.yml in CWD or use --config-file
YAML validation fails
Spaces only (no tabs), check colon spacing
SFGE out of memory
Increase java_max_heap_size in engines section
ESLint rules missing
Set auto_discover_eslint_config: true
For full troubleshooting, read <skill_dir>/references/troubleshooting.md.
Reference File Index
<skill_dir> is the absolute path to the directory containing this SKILL.md file.
File
Purpose
<skill_dir>/scripts/check-prerequisites.sh
Environment check
<skill_dir>/scripts/generate-config.sh
Auto-detect project type and generate config
<skill_dir>/scripts/validate-config.sh
Validate YAML after changes
<skill_dir>/references/config-schema.md
Full YAML schema documentation
<skill_dir>/references/diagnostic-flow.md
Step 2A: layered diagnostic procedure and fix table
<skill_dir>/references/rule-name-resolution.md
Step 6.1: fuzzy rule name lookup strategies and mappings
