sf-soql
jaganpro/sf-skills
SOQL/SOSL query generation, optimization, and performance scoring for Salesforce.
What is sf-soql?
Expert guidance for authoring, optimizing, and analyzing Salesforce SOQL and SOSL queries. Use this skill when writing or debugging queries, working with .soql files, or addressing relationship queries, aggregates, and performance concerns.
- Generate SOQL/SOSL from natural language requirements
- Optimize queries for selectivity and governor limits
- Analyze query shape and relationship patterns
- Score queries on a 100-point scale across 5 categories
- Identify anti-patterns and security concerns
- Validate field coverage and index usage
How to install sf-soql
npx skills add https://github.com/jaganpro/sf-skills --skill sf-soqlHow to use sf-soql
- 1.Provide the target object(s), required fields, filter criteria, and use case (display, automation, reporting, or Apex)
- 2.Receive a generated SOQL/SOSL query with design rationale and optimization notes
- 3.Review the 100-point score and any flagged anti-patterns or security concerns
- 4.Use the query directly or hand off to sf-data for execution or sf-apex for embedding
Use cases
- Convert a business requirement into an optimized SOQL query with proper filtering and relationships
- Refactor a slow query by analyzing selectivity and rewriting with indexed filters
- Design aggregate queries for rollups and counts instead of loading unnecessary records
- Build parent-to-child subqueries or child-to-parent traversals for related data
- Evaluate SOSL for text search across multiple objects
- Salesforce developers writing queries
- Architects designing query patterns for performance
- Teams optimizing existing slow queries
- Developers embedding queries in Apex or LWC
sf-soql FAQ
Use sf-soql to author and optimize the query shape. Use sf-data to execute the query against an org and export results.
Queries are scored across 5 categories: 90+ is production-ready, 80–89 is good with minor improvements, 70–79 has performance concerns, and <70 needs revision.
No. Always query only the fields you need to minimize data transfer and improve selectivity. Wildcard patterns should be avoided unless necessary.
Use aggregate queries (COUNT, SUM, GROUP BY) for rollups and summaries instead of fetching all records and post-processing in Apex.
Delegate to sf-apex for implementation context, but use sf-soql first to design the optimal query shape and ensure it avoids loops and unnecessary fields.
Full instructions (SKILL.md)
Source of truth, from jaganpro/sf-skills.
name: sf-soql description: > SOQL query generation, optimization, and analysis with 100-point scoring. 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 sf-data), Apex DML logic (use sf-apex), or report/dashboard queries. license: MIT metadata: version: "1.1.0" author: "Jag Valaiyapathy" scoring: "100 points across 5 categories"
sf-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 sf-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 → sf-data
- embedding query logic inside broader Apex implementation → sf-apex
- debugging via logs rather than query shape → sf-debug
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:
- sf-data
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:
Query goal: <summary>
Query: <soql or sosl>
Design: <relationship / aggregate / filter choices>
Notes: <selectivity, limits, security, governor awareness>
Next step: <run in sf-data or embed in Apex>
Cross-Skill Integration
| Need | Delegate to | Reason |
|---|---|---|
| run the query against an org | sf-data | execution and export |
| embed the query in services/selectors | sf-apex | implementation context |
| analyze slow-query symptoms from logs | sf-debug | runtime evidence |
| wire query-backed UI | sf-lwc | frontend integration |
Reference Map
Start here
Specialized guidance
- references/soql-reference.md
- references/anti-patterns.md
- references/selector-patterns.md
- references/field-coverage-rules.md
- assets/
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 |
Related skills
More from jaganpro/sf-skills and the wider catalog.
sf-testing
Run Apex tests, analyze coverage, and fix failures with structured test-fix loops.
sf-vlocity-build-deploy
>
sf-ai-agentforce
>
sf-ai-agentforce-observability
>
transitions-dev
Production-ready CSS transitions for web apps. Use when implementing notification badges, dropdowns, modals, panel reveals, page transitions, card resizes, number pop-ins, text swaps, icon swaps, success checks, avatar group hovers, or error state shakes. Triggers on "add a transition", "animate the dropdown", "make the modal open smoothly", "swap icon", "page slide", "stagger animation", "open / close transition", "make it animate", "tween the size", "fade between", "smooth open", "smooth close", "success animation", "checkmark animation", "confirmation animation", "form error", "shake on invalid", "validation feedback", "hover lift", "avatar stack hover", "chip group hover".
transitions-dev
Production-ready CSS transitions for web apps—21 portable, namespaced snippets with motion tokens.