--- name: platform-soql-query description: "SOQL query generation, optimization, and analysis with 100-point scoring. Use this skill when the user needs SOQL/SOSL authoring or optimization: natural-language-to-query generation, relationship queries, aggregates, query-plan analysis, and performance or safety improvements for Salesforce queries. TRIGGER when: user writes, optimizes, or debugs SOQL/SOSL queries, touches .soql files, or asks about relationship queries, aggregates, or query performance. DO NOT TRIGGER when: bulk data operations (use platform-data-manage), Apex DML logic (use platform-apex-generate), or report/dashboard queries." allowed-tools: | Bash Read Write mcp__plugin_salesforce-development_salesforce-lsp__validate_soql mcp__plugin_salesforce-development_salesforce-lsp__complete_soql mcp__plugin_salesforce-development_salesforce-lsp__check_soql_selectivity mcp__plugin_salesforce-development_salesforce-lsp__extract_soql_from_apex mcp__plugin_salesforce-development_salesforce-lsp__refresh_org_schema metadata: cliTools: - tool: ["jq"] semver: ">=1.6.0" - tool: ["python3"] semver: ">=3.10.0" - tool: ["sf"] semver: ">=2.0.0" relatedSkills: - "experience-lwc-generate" - "platform-apex-generate" - "platform-apex-logs-debug" - "platform-apex-test-run" - "platform-data-manage" version: "1.1" mcpTools: salesforce-lsp: tools: - validate_soql - complete_soql - check_soql_selectivity - extract_soql_from_apex - refresh_org_schema semver: ">=0.1.0" --- # platform-soql-query: Salesforce SOQL Query Expert Use this skill when the user needs **SOQL/SOSL authoring or optimization**: natural-language-to-query generation, relationship queries, aggregates, query-plan analysis, and performance/safety improvements for Salesforce queries. ## When This Skill Owns the Task Use `platform-soql-query` when the work involves: - `.soql` files - query generation from natural language - relationship queries and aggregate queries - query optimization and selectivity analysis - SOQL/SOSL syntax and governor-aware design Delegate elsewhere when the user is: - performing bulk data operations → [platform-data-manage](../platform-data-manage/SKILL.md) - embedding query logic inside broader Apex implementation → [platform-apex-generate](../platform-apex-generate/SKILL.md) - debugging via logs rather than query shape → [platform-apex-logs-debug](../platform-apex-logs-debug/SKILL.md) --- ## Required Context to Gather First Ask for or infer: - target object(s) - fields needed - filter criteria - sort / limit requirements - whether the query is for display, automation, reporting-like analysis, or Apex usage - whether performance / selectivity is already a concern --- ## Recommended Workflow ### 1. Generate the simplest correct query Prefer: - only needed fields - clear WHERE criteria - reasonable LIMIT when appropriate - relationship depth only as deep as necessary While drafting, call `mcp__plugin_salesforce-development_salesforce-lsp__complete_soql` with the partial query to get schema-aware completion of object, field, and relationship names against the connected org — this avoids guessing API names that then fail validation. On error envelope or unavailable (`{error:

}` / tool not registered), skip completion and rely on the syntax reference in `references/soql-syntax-reference.md`.

When the query already lives inside an Apex class (optimizing or debugging embedded SOQL rather than authoring new), call `mcp__plugin_salesforce-development_salesforce-lsp__extract_soql_from_apex` with the `.cls` file to pull the SOQL strings out before analyzing them, so you optimize the exact query the class runs.

### 2. Choose the right query shape
| Need | Default pattern |
|---|---|
| parent data from child | child-to-parent traversal |
| child rows from parent | subquery |
| counts / rollups | aggregate query |
| records with / without related rows | semi-join / anti-join |
| text search across objects | SOSL |

### 3. Validate with LSP tools (REQUIRED)

**REQUIRED:** Before running a SOQL query against the org or recommending it for production use:

1. **Call `mcp__plugin_salesforce-development_salesforce-lsp__validate_soql`** with the query string to check syntax and catch parse errors before execution.
   - On success (`{ok: true}`), proceed. **A clean parse is not a clean query.** `validate_soql` is parser-only — it accepts objects, fields, and relationships that do not exist in the target org. A successful parse means the syntax is well-formed, NOT that the identifiers resolve.
   - **Fail closed on an uncertain result.** If the call timed out, was retried, or its result is otherwise uncertain, do NOT treat it as a successful validation — fall back to step 2 and record `validate_soql=unavailable: timeout`.
   - On error envelope (`{error: }`), record `validate_soql=unavailable: ` and fall back to step 2.
   - On unavailable (tool not registered), record `validate_soql=unavailable: lsp_not_present` and fall back to step 2.

2. **Verify identifiers against org schema (REQUIRED, even when the parse succeeds).** Confirm every object, field, and relationship in the query actually exists in the target org before recommending it — a well-formed parse over a nonexistent field must not be reported as valid.
   - **Authoritative check — describe or a bounded probe. Do NOT execute the user's full query to verify schema** (it may be unbounded and retrieve large result sets). Instead:
     - **Preferred:** `sf sobject describe --sobject