Sf Soql

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:

• .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 → [sf-data](../sf-data/SKILL.md)
• embedding query logic inside broader Apex implementation → [sf-apex](../sf-apex/SKILL.md)
• debugging via logs rather than query shape → [sf-debug](../sf-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

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](../sf-data/SKILL.md)

---

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:

1. Query purpose
2. Final SOQL/SOSL
3. Why this shape was chosen
4. Optimization or security notes
5. Execution suggestion if needed

Suggested shape:

Query goal: 
Query: 
Design: 
Notes: 
Next step: 

---

Cross-Skill Integration

| Need | Delegate to | Reason | |---|---|---| | run the query against an org | [sf-data](../sf-data/SKILL.md) | execution and export | | embed the query in services/selectors | [sf-apex](../sf-apex/SKILL.md) | implementation context | | analyze slow-query symptoms from logs | [sf-debug](../sf-debug/SKILL.md) | runtime evidence | | wire query-backed UI | [sf-lwc](../sf-lwc/SKILL.md) | frontend integration |

---

Reference Map

Start here

• [references/soql-syntax-reference.md](references/soql-syntax-reference.md)
• [references/query-optimization.md](references/query-optimization.md)
• [references/cli-commands.md](references/cli-commands.md)

Specialized guidance

• [references/soql-reference.md](references/soql-reference.md)
• [references/anti-patterns.md](references/anti-patterns.md)
• [references/selector-patterns.md](references/selector-patterns.md)
• [references/field-coverage-rules.md](references/field-coverage-rules.md)
• [assets/](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 |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Jaganpro
• Source: Jaganpro/sf-skills
• License: MIT

Install and usage instructions live in the source repository linked above.