W-21685788: Expand using-webapp-salesforce-data guidance by channiganfsu · Pull Request #101 · forcedotcom/afv-library

channiganfsu · 2026-03-24T18:38:59Z

References: Contributing guide · Skill authoring guide · Agent Skills spec

What changed

Updated the using-webapp-salesforce-data skill to better cover common web app data access workflows with Salesforce. This expands the main SKILL.md, adds focused supporting docs for schema introspection, read query generation, mutation query generation, query testing, and React webapp integration, and moves graphql-search.sh into scripts/ to match the expected skill layout.

Why

The skill needed more complete and actionable guidance for agents building UI-driven Salesforce integrations. This fills gaps around discovering schema, generating safe GraphQL queries and mutations, testing data access patterns, and wiring Salesforce data into web app components while keeping the core skill concise and moving detailed guidance into supporting docs.

Notes

The update also incorporates prior PR feedback by tightening wording, improving formatting, and aligning the skill more closely with the companion using-salesforce-data guidance. I did not run additional automated validation locally during PR creation, so CI should be the source of truth for the skill structure and spec checks.

Skills

Manual checklist

Description quality

Describes what the skill does and the expected output
Includes relevant Salesforce domain keywords (Apex, LWC, SOQL, metadata types, etc.)
Trigger phrases are specific enough for Vibes to select this skill reliably

Instructions

Clear goal statement
Step-by-step workflow
Validation rules for generated output
Defined output / artifact

Context efficiency

Core instructions are concise — supporting material lives in templates/, examples/, or docs/ subdirectories
No unnecessary background explanation in the body

Automated checks

Enforced by CI (npm run validate:skills) per the Agent Skills spec:

Directory is one level deep, named in kebab-case (max 64 chars), contains SKILL.md
Frontmatter name matches directory name; description is present, ≥ 20 words, ≤ 1024 characters, and includes trigger language
Body is non-empty and under 500 lines
Name uses gerund form ⚠ (warning — does not block merge)

@W-21685788@

Add detailed reference docs for schema introspection, read query generation, mutation query generation, query testing, and webapp integration patterns. Made-with: Cursor

…ipts/ Relocate the schema search script from the skill root into a dedicated scripts/ directory for better organization. Made-with: Cursor

…rce-data - Add GraphQL Non-Negotiable Rules section (6 critical platform rules) - Fix mutation template to include allOrNone wrapper - Add doc cross-references (schema introspection, query generation, testing, webapp integration) - Add deploying-webapp-to-salesforce skill cross-reference - Update script paths from .a4drules/... to scripts/graphql-search.sh - Expand checklist with allOrNone, pagination, and error handling items - Add two named webapp integration patterns (external .graphql, inline gql) Made-with: Cursor

jodarove

can you also include the changes to the graphql-search.sh from https://github.com/salesforce-experience-platform-emu/webapps/pull/345/changes?

jodarove · 2026-03-24T18:48:17Z

skills/using-webapp-salesforce-data/references/mutation-query-generation.md

@@ -0,0 +1,140 @@
+# Mutation Query Generation


should the folder name for these be "references" or maybe "assets" instead of "docs"? https://agentskills.io/specification#directory-structure

good catch, will update to references (I see that in other skills as well)

jodarove · 2026-03-24T18:58:09Z

skills/using-webapp-salesforce-data/SKILL.md

+
+1. **Schema is the single source of truth** — Every entity name, field name, and type must be confirmed via the schema search script before use in a query. Never guess — Salesforce field names are case-sensitive, relationships may be polymorphic, and custom objects use suffixes (`__c`, `__e`). See [Schema Introspection](docs/schema-introspection.md) for entity identification and iterative lookup procedures.
+
+2. **`@optional` on all record fields** (read queries) — Salesforce field-level security (FLS) causes queries to fail entirely if the user lacks access to even one field. The `@optional` directive (v65+) tells the server to omit inaccessible fields instead of failing. Apply it to every scalar field, parent relationship, and child relationship. Consuming code must use optional chaining (`?.`) and nullish coalescing (`??`).


not related to your pr (let's add it to the back burner): i would love to tweak this, @optional on everything may be too extreme and masks real permission misconfigurations during development, fields critical to business logic (Id, fields used in filtering/routing) should fail loudly, not silently return undefined

yup, I replied to this in the webapps PR, and also agreed we should tweak it (but in a follow up PR)

jodarove · 2026-03-24T19:00:28Z

skills/using-webapp-salesforce-data/docs/schema-introspection.md

+Run the search script from the **SFDX project root** to get all relevant schema info in one step:
+
+```bash
+bash .a4drules/skills/using-salesforce-data/graphql-search.sh <EntityName>


let's use the new path

grr, how'd this get missed?

jodarove · 2026-03-24T19:01:33Z

skills/using-webapp-salesforce-data/references/schema-introspection.md

+
+The schema reflects the **current org state**. Custom objects and fields appear only after metadata is deployed.
+
+- **Before** running `npm run graphql:schema`: Deploy all metadata and assign permission sets. Invoke the `deploying-to-salesforce` skill for the full sequence.


is this skill valid? the only one i see in the repository is deploying-webapp-to-salesforce

I guess my search ignored the files in the docs folder, I guess I only updated this in the SKILL.md file

jodarove · 2026-03-24T19:02:29Z

skills/using-webapp-salesforce-data/SKILL.md

 | Connect REST | `sdk.fetch` | `/services/data/v{ver}/connect/file/upload/config` — file upload config |
 | Einstein LLM | `sdk.fetch` | `/services/data/v{ver}/einstein/llm/prompt/generations` — AI text generation |

-**Not supported:**


should we leave this section? it is valid

I removed it for now, it's a bit of that negative constraint situation. If we say what is supported, an attempt of doing anything else is working outside our guidelines. I don't want to even put the idea in the agents "head" 😄

based on Claudes defense, I'll revert this for now, and we can examine further later

jodarove · 2026-03-24T19:08:32Z

skills/using-webapp-salesforce-data/references/webapp-integration.md

+
+Responses follow `uiapi.query.ObjectName.edges[].node`; fields use `{ value }`.
+
+## Conditional Field Selection


is this section repeated? what's the best place to have it?

good question, but it doesn't make sense to have it in here. I also got feedback that things like the @include and @Skip directives are well known by agents, and not necessary, we can remove entirely if you agree

let's put it in the backlog, and try these changes for now.

jodarove · 2026-03-24T19:35:55Z

skills/using-webapp-salesforce-data/SKILL.md

 ---
 name: using-webapp-salesforce-data
-description: "Salesforce data access for reading, writing, and querying records via REST, GraphQL, Apex, or Platform SDK. Use when the user wants to fetch, search, filter, sort, display, create, update, delete, or attach files to Salesforce records (standard objects like Accounts, Contacts, Opportunities, Cases, Quotes, or any custom object) in a web app or UI component (React, Angular, Vue, etc.); call Chatter, Connect, or Apex REST APIs; or invoke AuraEnabled Apex methods from an external app. Does not apply to authentication/OAuth setup, schema changes (adding fields, relationships), Bulk/Tooling/Metadata API usage, declarative automation (Flows, Process Builder), general LWC/Apex coding guidance without a specific data operation, or Salesforce admin/configuration tasks."
+description: "Salesforce data access for reading, writing, and querying records via REST, GraphQL, Apex, or Platform SDK. Use when the user wants to fetch, search, filter, sort, display, create, update, delete, or attach files to Salesforce records (standard objects like Accounts, Contacts, Opportunities, Cases, Quotes, or any custom object) in a web app or UI component (React, Angular, Vue, etc.); call Chatter, Connect, or Apex REST APIs."


we removed the not supported section, claude really likes the "not supported" section, here's what it says:

▎ "...Does not apply to authentication/OAuth setup, schema changes (adding fields, relationships), Bulk/Tooling/Metadata API usage, declarative automation (Flows, Process Builder), general LWC/Apex coding guidance without a specific data operation, or Salesforce admin/configuration tasks." The PR truncates the description to end at: ▎ "...call Chatter, Connect, or Apex REST APIs." Why the exclusions matter: Skills use progressive disclosure — at discovery time, the agent only sees name + description to decide whether to activate a skill. The "Does not apply to..." clause acts as a negative trigger, telling the agent "don't pick me for these scenarios." Without it, consider a user saying "add a Industry field to the Account object." That involves schema changes (metadata). With the exclusions, the agent reads "Does not apply to...schema changes (adding fields, relationships)" and skips this skill, correctly routing to something like generating-custom-field. Without the exclusions, the agent sees "Salesforce data access...Account...web app" and might incorrectly activate this data-access skill. The same applies to "set up OAuth for my app" (authentication), "create a Flow that updates Contacts" (declarative automation), or "write an Apex utility class" (general coding without a data operation). These are all plausible false-positive activations. In short: positive triggers say "pick me when X," negative triggers say "not me when Y." Both are needed for reliable skill selection, especially in a library with 27+ skills that have overlapping domain vocabulary.

fair assessment, and also when considering the scale of skills in this repo

Made-with: Cursor

This reverts commit f439b7a.

jodarove

lgtm! let's include the latest changes to graphql-search.sh from https://github.com/salesforce-experience-platform-emu/webapps/pull/345/changes

jodarove

@channiganfsu see my latest comments

jodarove · 2026-03-26T18:58:36Z

skills/using-webapp-salesforce-data/SKILL.md

@@ -1,3 +1,3 @@
 ---
 name: using-webapp-salesforce-data
 description: "Salesforce data access for reading, writing, and querying records via REST, GraphQL, Apex, or Platform SDK. Use when the user wants to fetch, search, filter, sort, display, create, update, delete, or attach files to Salesforce records (standard objects like Accounts, Contacts, Opportunities, Cases, Quotes, or any custom object) in a web app or UI component (React, Angular, Vue, etc.); call Chatter, Connect, or Apex REST APIs; or invoke AuraEnabled Apex methods from an external app. Does not apply to authentication/OAuth setup, schema changes (adding fields, relationships), Bulk/Tooling/Metadata API usage, declarative automation (Flows, Process Builder), general LWC/Apex coding guidance without a specific data operation, or Salesforce admin/configuration tasks."


I have played a looot, on seeing when the skill is picked. this description, give us a good chance (see Drew's tool output), now, to be fair, it does not always get picked (it scapes me why); but in afv, now i see it show up a bit; and for sure when: either when asking which skills can we use for the prompt, or by adding a small modification to a rule (check this pr):

Suggested change

description: "Salesforce data access in web apps (React/Angular/Vue) — GraphQL queries, REST calls, CRUD, and record fetching via the Data SDK. MUST USE when the task involves ANY of: fetching, querying, displaying, loading, showing, pulling, listing, or integrating Salesforce data into a component; GraphQL queries or mutations against Salesforce (write, optimize, debug, fix, or triage); CRUD operations — create/insert, read/get, update, or delete ANY Salesforce record (Account, Contact, Opportunity, Case, Lead, Quote, custom objects, junction objects, many-to-many relationship tables); searching, filtering (by any field — status, owner, email, date, picklist), sorting, or paginating through records; using sdk-data, createDataSDK, gql tag, NodeOfConnection, or GraphQL directives (@optional, @required); calling Connect REST, Apex REST, UI API, or Einstein LLM endpoints via sdk.fetch; fetching current user info or User object data; exploring org schema, querying object metadata, or looking up fields/relationships (e.g., \"what fields are on Case\"); wiring up or adding data fetching to a React/Angular/Vue component; triaging, debugging, or investigating GraphQL issues — empty data, ValidationError, DataFetchingException, missing fields, HTTP 200 with errors, \"fix this query,\" \"why is my query not working.\" Does NOT apply to: LWC (@wire, getRecord, lightning/uiRecordApi, imperative Apex); server-side Apex (triggers, classes, batch jobs); authentication/OAuth; schema changes (adding fields/objects); Bulk/Tooling/Metadata/Composite API; declarative automation (Flows, Process Builder); dashboards or reports (unless fetching underlying data); or conceptual Salesforce explanations without a concrete data-fetching task."

The description is outside the bounds of what is considered best practice for skill descriptions. Here is what /skill-creator had to say about it:

Based on the skill-creator's guidance, this description has some strengths but several issues:

What works

Clear about the skill's domain (Salesforce data access in web apps)

Includes both positive triggers and explicit exclusions

Mentions specific technologies and error patterns users might encounter

What doesn't

Way too long. The skill-creator says metadata (name + description) should be ~100 words. This is 250+. Descriptions are always loaded into context, so every token here costs across
every conversation — even when the skill isn't relevant.

Heavy-handed MUSTs and ALL CAPS. The skill-creator specifically flags this as an anti-pattern:

▎ If you find yourself writing ALWAYS or NEVER in all caps, that's a yellow flag — reframe and explain the reasoning so that the model understands why the thing you're asking for is
important.

"MUST USE when the task involves ANY of:" is exactly what the guide warns against.

Exhaustive keyword enumeration feels overfitty. Listing every synonym ("fetching, querying, displaying, loading, showing, pulling, listing, integrating") and every object type
("Account, Contact, Opportunity, Case, Lead, Quote") tries to brute-force triggering rather than conveying the concept. The model understands that "show me accounts" is data fetching —
you don't need to enumerate every verb and noun.

The exclusion list is too detailed for a description. Seven bullet points of negatives belong in the SKILL.md body, not the description.

A tighter alternative

Something like:

▎ Salesforce data access in web apps (React/Angular/Vue) using the Data SDK — GraphQL queries/mutations, REST calls, CRUD operations, record fetching, filtering, and pagination. Use
this skill whenever a component needs to fetch, display, or modify Salesforce records, or when debugging GraphQL issues (empty data, validation errors, broken queries). Also covers
schema exploration and org metadata lookups. Does not apply to LWC wire adapters, server-side Apex, or Salesforce admin/declarative tools.

That's ~70 words, covers the same ground conceptually, and trusts the model to generalize from "fetch, display, or modify" without needing every synonym listed.

I know the "trusts the model" is what we are having a big problem with right now, but I'd hesitate to want to go with such a large description

sure, we can leave it as is.

jodarove · 2026-03-26T19:03:37Z

skills/using-webapp-salesforce-data/references/webapp-integration.md

@@ -0,0 +1,221 @@
+# Webapp Integration
+
+## When to Use


🫤 , i think we may be asking too much of gpt5. these references were too much during my testings; i have gotten the best results by condensing the references into the skill.md; attached the one i have been using.

SKILL.md

channiganfsu added 5 commits March 24, 2026 14:15

feat(using-webapp-salesforce-data): add supporting documentation

101de85

Add detailed reference docs for schema introspection, read query generation, mutation query generation, query testing, and webapp integration patterns. Made-with: Cursor

refactor(using-webapp-salesforce-data): move graphql-search.sh to scr…

c707d76

…ipts/ Relocate the schema search script from the skill root into a dedicated scripts/ directory for better organization. Made-with: Cursor

fix: remove negative constraints from frontmatter and body

f439b7a

fix: pr feedback

4a361d8

channiganfsu changed the title ~~feat: expand using-webapp-salesforce-data guidance~~ W-21685788: Expand using-webapp-salesforce-data guidance Mar 24, 2026

jodarove reviewed Mar 24, 2026

View reviewed changes

channiganfsu added 2 commits March 24, 2026 15:51

refactor(using-webapp-salesforce-data): rename docs to references

ea7e913

Made-with: Cursor

Revert "fix: remove negative constraints from frontmatter and body"

7e41d24

This reverts commit f439b7a.

jodarove approved these changes Mar 24, 2026

View reviewed changes

channiganfsu added 2 commits March 24, 2026 16:22

fix: update graphql schema search script

6683687

fix: update skill name for deploying to salesforce

900cffa

jodarove reviewed Mar 26, 2026

View reviewed changes


		1. Schema is the single source of truth — Every entity name, field name, and type must be confirmed via the schema search script before use in a query. Never guess — Salesforce field names are case-sensitive, relationships may be polymorphic, and custom objects use suffixes (`__c`, `__e`). See [Schema Introspection](docs/schema-introspection.md) for entity identification and iterative lookup procedures.

		2. `@optional` on all record fields (read queries) — Salesforce field-level security (FLS) causes queries to fail entirely if the user lacks access to even one field. The `@optional` directive (v65+) tells the server to omit inaccessible fields instead of failing. Apply it to every scalar field, parent relationship, and child relationship. Consuming code must use optional chaining (`?.`) and nullish coalescing (`??`).


		The schema reflects the current org state. Custom objects and fields appear only after metadata is deployed.

		- Before running `npm run graphql:schema`: Deploy all metadata and assign permission sets. Invoke the `deploying-to-salesforce` skill for the full sequence.


		Responses follow `uiapi.query.ObjectName.edges[].node`; fields use `{ value }`.

		## Conditional Field Selection

Conversation

channiganfsu commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changed

Why

Notes

Skills

Manual checklist

Automated checks

Uh oh!

jodarove left a comment

Choose a reason for hiding this comment

Uh oh!

jodarove Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jodarove left a comment

Choose a reason for hiding this comment

Uh oh!

jodarove left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

channiganfsu commented Mar 24, 2026 •

edited

Loading

jodarove Mar 24, 2026 •

edited

Loading