How to install querying-soql
npx skills add https://github.com/forcedotcom/sf-skills --skill querying-soqlFull instructions (SKILL.md)
Source of truth, from forcedotcom/sf-skills.
name: querying-soql 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 handling-sf-data), Apex DML logic (use generating-apex), or report/dashboard queries." metadata: version: "1.1"
querying-soql: 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 querying-soql when the work involves:
.soqlfiles- 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 → handling-sf-data
- embedding query logic inside broader Apex implementation → generating-apex
- debugging via logs rather than query shape → debugging-apex-logs
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
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. Optimize for selectivity and safety
Check:
- indexed / selective filters
- no unnecessary fields
- no avoidable wildcard or scan-heavy patterns
- security enforcement expectations
4. Validate execution path if needed
If the user wants runtime verification, hand off execution to:
High-Signal Rules
- never use
SELECT *style thinking; query only required fields - do not query inside loops in Apex contexts
- prefer filtering in SOQL rather than post-filtering in Apex
- use aggregates for counts and grouped summaries instead of loading unnecessary records
- evaluate wildcard usage carefully; leading wildcards often defeat indexes
- account for security mode / field access requirements when queries move into Apex
Output Format
When finishing, report in this order:
- Query purpose
- Final SOQL/SOSL
- Why this shape was chosen
- Optimization or security notes
- Execution suggestion if needed
Suggested shape — use references/soql-syntax-reference.md for exact syntax:
Query goal: <summary>
Query: <soql or sosl>
Design: <relationship / aggregate / filter choices>
Notes: <selectivity, limits, security, governor awareness>
Next step: <run in handling-sf-data or embed in Apex>
Cross-Skill Integration
| Need | Delegate to | Reason |
|---|---|---|
| run the query against an org | handling-sf-data | execution and export |
| embed the query in services/selectors | generating-apex | implementation context |
| analyze slow-query symptoms from logs | debugging-apex-logs | runtime evidence |
| wire query-backed UI | generating-lwc-components | frontend integration |
Score Guide
| Score | Meaning |
|---|---|
| 90+ | production-optimized query |
| 80–89 | good query with minor improvements possible |
| 70–79 | functional but performance concerns remain |
| < 70 | needs revision before production use |
Reference File Index
| File | When to read |
|---|---|
references/soql-syntax-reference.md | Syntax, operators, date literals, relationship query patterns |
references/query-optimization.md | Selectivity rules, indexing strategy, governor limits, security patterns |
references/soql-reference.md | Quick reference — operators, date functions, aggregate functions, WITH clauses |
references/anti-patterns.md | Common SOQL mistakes and their fixes — read before finalizing any query |
references/selector-patterns.md | Apex selector layer patterns — read when embedding queries in Apex classes |
references/field-coverage-rules.md | Field coverage validation — read when generating SOQL used inside Apex code |
references/cli-commands.md | sf CLI query execution, bulk export, query plan commands |
assets/basic-queries.soql | Starter query examples for common objects |
assets/relationship-queries.soql | Parent-to-child and child-to-parent relationship query patterns |
assets/aggregate-queries.soql | COUNT, SUM, GROUP BY, ROLLUP query patterns |
assets/optimization-patterns.soql | Selective filter and index-aware query patterns |
assets/bulkified-query-pattern.cls | Apex Map-based bulk query pattern for trigger contexts |
assets/selector-class.cls | Full selector class implementation template |
scripts/post-tool-validate.py | Post-write hook — runs static SOQL validation and live query plan analysis after .soql file edits |
Related skills
More from forcedotcom/sf-skills and the wider catalog.
generating-apex
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.
generating-apex-test
Generate and validate Apex test classes with TestDataFactory patterns, bulk testing (251+ records), mocking strategies, assertion best practices, and disciplined test-fix loops. Use this skill when creating new Apex test classes, improving test coverage, debugging and fixing failing Apex tests, running test execution and coverage analysis, or implementing testing patterns for triggers, services, controllers, batch jobs, queueables, and integrations. Triggers on *Test.cls, *_Test.cls files, sf apex run test workflows, coverage reports, test-fix loops. Do NOT trigger for production Apex code (use generating-apex) or Jest/LWC tests.
generating-lwc-components
Lightning Web Components with PICKLES methodology and 165-point scoring. Use this skill when the user creates or edits LWC components, builds wire service patterns, or writes Jest tests for LWC. TRIGGER when: user creates/edits LWC components, touches lwc/**/*.js, .html, .css, .js-meta.xml files, or asks about wire service, SLDS, or Jest LWC tests. DO NOT TRIGGER when: Apex classes (use generating-apex), Aura components, or Visualforce.
generating-flow
Generate Salesforce Flows using the MCP tool execute_metadata_action. Use when the user asks to create, build, or generate a flow — including Screen, Autolaunched, Record-Triggered (before/after-save), Scheduled. Also trigger for flow-like requests such as \"when a record is created\", \"trigger daily at\", \"send an email when\", \"update the field when\", \"automate\", \"workflow\", or \"flow XML/metadata\". This is the only skill for Salesforce Flow generation.
generating-custom-object
Use this skill when users need to create, generate, or validate Salesforce Custom Object metadata. Trigger when users mention custom objects, creating objects, object metadata, .object files, sharing models, name fields, or validation rules on objects. Also use when users say things like \"create a custom object\", \"generate object metadata\", \"set up an object for...\", or when they're troubleshooting object deployment errors especially around sharing models and Master-Detail relationships. Always use this skill for any custom object metadata work.
generating-custom-field
Use this skill when users need to create, generate, or validate Salesforce Custom Field metadata. Trigger when users mention custom fields, field types, Roll-up Summary fields, Master-Detail relationships, Lookup relationships, formula fields, picklists, or field metadata. Also use when users encounter field deployment errors, especially around Roll-up Summary format, Master-Detail constraints, or formula issues. Always use this skill for any custom field metadata work, field generation, or field troubleshooting.