/experience-lds-graphql-generate

name: experience-lds-graphql-generate
description: "Use ALWAYS when a prompt mentions GraphQL, lightning/uiGraphQLApi, @wire(graphql, ...), or gql template tags in an LWC context — even if the surface ask is \"build an LWC\". Owns the ENTIRE flow: introspect the org's LDS GraphQL schema, identify entities/fields, construct the schema-validated gql query or mutation, wire it into the LWC via lightning/uiGraphQLApi, verify against a connected org. REQUIRED whenever a prompt asks to render, list, or edit Salesforce records (Account, Contact, Case, custom objects) via GraphQL — the .html and .js scaffolding IS in scope. DO NOT delegate to experience-lwc-generate: that skill has NO GraphQL schema introspection, NO create_lds_graphql_read_query binding, and defaults to getRecord/getRelatedListRecords wire adapters which will not satisfy a GraphQL prompt. DO NOT TRIGGER only if the prompt forbids GraphQL, chooses UIAPI/Apex (use experience-lds-best-practices-apply), or asks for data requirements (use experience-lds-data-requirements-generate)."
metadata:
  relatedSkills:
    - "experience-lds-best-practices-apply"
    - "experience-lds-data-requirements-generate"
    - "experience-lwc-generate"
  version: "1.0"
  domains: ["Experience", "Platform"]
  cliTools:
    - tool: ["python3"]
      semver: ">=3.8"
    - tool: ["sf"]
      semver: ">=2.0.0"

<!-- adk-managed-skill -->

Building LDS GraphQL

Generate schema-validated Salesforce LDS GraphQL queries (read or mutation), either as standalone queries or wired into a Lightning Web Component via the `lightning/graphql` adapters. The skill encodes the schema-as-source-of-truth workflow end-to-end. Two bundled bash scripts handle the org-aware steps — `scripts/fetch-lds-graphql-schema.sh` for schema introspection and `scripts/test-lds-graphql-query.sh` for live-org validation.

When to Use

• User wants to create, modify, or integrate a Salesforce GraphQL query (standard objects, custom objects, or setup objects).
• Building or updating an LWC that consumes/mutates LDS data through GraphQL.
• Introspecting an org's schema before writing a query.
• Validating a generated query end-to-end against a connected org.

Do NOT use this skill for:

• REST-based UI API (use LDS wire adapters; see `experience-lds-best-practices-apply`).
• Apex callouts or custom GraphQL endpoints — this skill is LDS-scoped.
• Data-requirements discovery — that's `experience-lds-data-requirements-generate`.

Prerequisites

• A connected Salesforce org (username or alias). User must confirm it before schema fetch — never assume.
• Salesforce CLI / `sf` available in the shell for the schema fetch.
• Decision on:
• **Namespace** — `uiapi` (default: standard + custom objects) or `setup` (setup objects like permission sets, profiles).
• **Query type** — `read` (default) or `mutation`.
• **Output format** — `standalone` (raw GraphQL + variables) or `LWC integration` (full component wiring).

Core Rules

These apply to every step — they are the rules this skill enforces:

1. **Sequential execution** — Steps 1→6 run in order. Every step is mandatory unless its triggering conditions are not met. 2. **Hard stop on failure** — A failed step blocks subsequent steps until remediation is complete. 3. **Schema is the single source of truth** — Every entity name, field name, field type, and relationship must come from `schema.graphql` introspection. Never use common Salesforce knowledge (e.g., do not assume `Owner` is a `User` — it may be polymorphic). 4. **Report each step** — Use the provided templates before advancing. 5. **Error reporting** — Categorize errors; never echo raw tool output into the chat.

Workflow

The full normative workflow lives in [references/generation-guide.md](references/generation-guide.md). Read it before starting. Read-query specifics are in [references/generation-query.md](references/generation-query.md); mutation specifics are in [references/generation-mutation.md](references/generation-mutation.md).

Step 1 — General query information

Collect and echo back:

Query type:       [read | mutation]
Namespace:        [uiapi | setup]
Output format:    [standalone | LWC integration]

If any is unclear, ask once and wait.

Step 2 — Acquire the schema

1. Ask for the `usernameOrAlias`. If a default is inferred from context, present it and wait for explicit confirmation. 2. Run `scripts/fetch-lds-graphql-schema.sh USERNAME_OR_ALIAS [OUTPUT_PATH] [API_VERSION]` with the confirmed alias. The script writes the SDL to `schema.graphql` (or the path you pass) so the schema never enters the chat context. If a non-empty `schema.graphql` already exists at `OUTPUT_PATH`, the script exits early (set `LDS_FETCH_FORCE=1` to re-fetch). 3. On failure: **hard stop**, report category, ask user to resolve org access, then retry.

Using the schema file

The schema is 265,000+ lines. **NEVER** read the whole file — use targeted `grep` calls only.

• Object type: `^type <ObjectName> implements Record` with `-A 100`.
• Filter: `^input <ObjectName>_Filter` with `-A 50`.
• OrderBy: `^input <ObjectName>_OrderBy` with `-A 30`.
• Mutation input: `^input <ObjectName>(Create|Update)Input` with `-A 50`.

**Search budget**: max 4–5 grep calls per entity. Plan before executing.

Step 3 — Entity identification

1. Entity names are PascalCase. 2. If names aren't given, extract candidates from `^type <Name> implements Record` matches. 3. If any entity is still unresolved, ask the user and wait. 4. Report:

   Identified entities:
   - EntityName (Field1, Field2, ...)
   Unknown entities:
   - <textual name>
   Step 3 status: SUCCESS | FAILED

5. If `Unknown entities` is non-empty → status `FAILED` → ask for clarification → restart Step 3.

Step 4 — Iterative entity introspection

Iteration limit: **3 cycles** (primary entity → references → child relationships). Hard-stop after 3.

Per cycle:

1. Remove already-introspected entitie