salesforce-soql-explorer-skill

salesforce-soql-explorer-skill

Read-only live SOQL execution against a connected Salesforce org under T1 least-privilege scope. This skill is a flashlight, not a filing cabinet. It queries evidence; it does not write, deploy, or mutate anything.

When This Skill Owns the Task

Use salesforce-soql-explorer-skill when the work requires live record evidence from a connected org:

• "Show me the Opportunity pipeline for Q3 in sandbox"
• "How many Contacts have no email address?"
• "What is the value of Account.BillingCountry for record 001Xx000001ABC?"
• "Count open Cases by priority for the service team"
• "Verify the field value changed after yesterday's data load"

Delegate elsewhere when:

| Situation | Skill to use | |---|---| | User pastes metadata XML or deployment export for review | salesforce-metadata-review-skill | | Schema or field definitions needed without record values | salesforce-metadata-fetcher-skill | | Request requires INSERT, UPDATE, DELETE, MERGE, or UPSERT | T3 — requires human approval via salesforce-live-guard-agent | | Large-volume export (> 2,000 records) or scheduled batch | salesforce-bulk-data-ops-skill | | Static code review of a .soql file or Apex selector | querying-soql (sf-skills) | | A change proposal emerges from findings | Escalate to salesforce-live-guard-agent | | Permission topology findings surface | Hand off to salesforce-permission-model-review-skill |

Required Context to Gather First

Before executing any query, confirm:

1. Target org alias — the --target-org value recognized by sf org list.

Never accept a raw instance URL or session token.

1. Org type — production or sandbox. Flag if production; apply stricter

scrutiny on field selection and result volume.

1. Target sObject — the API name (e.g., Account, Opportunity,

My_Custom_Object__c).

1. Fields needed — enumerate explicitly; do not use SELECT *.
2. Filter criteria — WHERE clause conditions, date ranges, owner scope.
3. Expected result volume — inform LIMIT choice.
4. Sensitivity classification — does the query touch PII fields (email,

phone, address, SSN, health, financial)? Regulated-vertical indicator (Health Cloud, Financial Services Cloud )? Encrypted fields (Shield PE / PMLE)?

If any of these are missing, ask before proceeding.

Recommended Workflow

Step 1 — Confirm org alias and reachability

sf org display --target-org <alias>

Verify: org type (production vs. sandbox), username, instance URL, OAuth Connected App. If the org type is production and the Connected App allowlist does not explicitly authorize this alias, stop (see Stop Conditions).

Step 2 — Confirm sObject exists and check FLS

sf sobject describe --sobject <SObjectName> --target-org <alias>

Confirm: the sObject exists, the Run As account has Read access, and the requested fields are accessible (not restricted by FLS). If any field is encrypted (Shield PE / PMLE), remove it from the query and note the redaction.

Step 3 — Generate the simplest correct query

Apply these constraints:

• Enumerate only required fields — no SELECT *
• Apply a selective WHERE clause using indexed fields (Id, Name, ExternalId,

lookup fields, standard indexed fields)

• Include LIMIT (default 200; reduce for PII-adjacent queries)
• Avoid formula fields or non-indexed fields in WHERE without a companion

indexed filter

Step 4 — Preview with LIMIT 5 first

sf data query \
  --query "SELECT <fields> FROM <SObject> WHERE <filter> LIMIT 5" \
  --target-org <alias> \
  --result-format json

Inspect output for: unexpected fields, encrypted placeholders, PII exposure, schema surprises. Confirm the shape matches the intent before expanding volume.

Step 5 — Execute with appropriate LIMIT

sf data query \
  --query "SELECT <fields> FROM <SObject> WHERE <filter> LIMIT <n>" \
  --target-org <alias> \
  --result-format json

Maximum interactive LIMIT: 2,000. For larger volumes, decline and route to salesforce-bulk-data-ops-skill.

Step 6 — Sanitize output

Apply redaction rules before emitting any output:

• Replace all 15/18-character Salesforce Ids with <org_id_placeholder> or

<record_id_placeholder> as appropriate.

• Replace user IDs (User.Id references, OwnerId, CreatedById, LastModifiedById)

with <user_id_placeholder>.

• Remove or mask any field that contains plaintext email, phone, SSN, or

financial account numbers unless the user has explicitly acknowledged the PII scope and the org is not regulated.

• Skip any encrypted field (Shield PE / PMLE) entirely — do not include

placeholder text that implies a value was present.

• Never emit OAuth tokens, refresh tokens, or session IDs.

Use jq for structured redaction:

sf data query \
  --query "SELECT Id, Name FROM Account LIMIT 5" \
  --target-org <alias> \
  --result-format json \
  | jq '.result.records[] | {Id: "<record_id_placeholder>", Name: .Name}'

Step 7 — Emit audit envelope

Every execution must produce a structured audit envelope (see Audit Envelope Schema below). Do not omit the envelope even if results are empty.

Step 8 — Hand off to review skill if findings warrant

If query results surface access anomalies, unexpected field values, or policy violations, hand off to the appropriate review skill with the sanitized results and the audit envelope as the input payload. Do not escalate raw unsanitized output.

Quality Scoring Rubric (100-point)

Score the query design and execution quality before emitting results. Threshold: 80+ acceptable, 60–79 emit with caveat, below 60 reject and request revision.

| Dimension | Points | What earns full marks | |---|---|---| | Selectivity | 30 | WHERE clause uses at least one indexed field; no full table scans on objects > 10k records | | Field minimality | 20 | Only required fields enumerated; no SELECT *; no encrypted fields included | | Governor limit awareness | 20 | LIMIT applied and appropriate to volume; no queries likely to exceed 50k row limit; aggregate used when count is the goal | | Redaction quality | 15 | All Salesforce IDs, user IDs, PII fields redacted per rules; audit envelope populated | | Audit envelope completeness | 15 | All required audit fields present; query text hash computed; timestamp accurate |

Scoring penalties:

• No WHERE clause on object with > 50k records: -20
• SELECT *: -15
• Missing LIMIT: -15
• Missing audit envelope: -20 (automatic caveat regardless of total score)
• Encrypted field included in output: immediate reject (score voided)

T1 Least-Privilege Contract

This skill operates exclusively at T1 — read-only runtime. The contract is:

• OAuth scopes used: api and refresh_token only. No full, web,

sfap_api, cdp_query_api, or any other scope.

• Run As account profile: System permissions: View Setup and Configuration

only. Object permissions: Read only on objects in scope. FLS restricted to non-PII, non-encrypted fields by default.

• Denied permissions (enforced at Connected App and profile level):
• Modify All Data
• View All Data (system-level bypass)
• View Encrypted Data
• Modify Metadata Through Metadata API Functions
• Author Apex
• Customize Application
• Manage Connected Apps
• Org allowlist: Enforced by Connected App IP restrictions and explicit

org alias allowlist. Skill verifies via sf org list that the target alias is in the authorized set before executing any query.

• No DML under any circumstances: This skill will not construct or execute

any statement containing INSERT, UPDATE, DELETE, MERGE, or UPSERT. Requests for DML must be refused and routed to the human approval path.

• Revocation: The least-privilege Run As account's refresh token can be

rotated to instantly revoke all access without affecting other integrations.

R