/platform-metadata-discovery-get

name: platform-metadata-discovery-get
description: "Use before creating, changing, or writing code against Salesforce metadata, to find out what already exists in the org with the right tool. Routes each question to metadata grounding, scoped SOQL with sf data query, sf sobject list or describe, sf org list metadata, source retrieval, or local files, and covers orgs and setups where grounding is not available. Use to check whether an object, field, picklist, permission set, page, app, or flow already exists before creating one, confirm field names, types, and picklist values before writing Apex, LWC, SOQL, or Flow logic, list every field on an object or every member of a metadata type, find automation that runs on an object, or explain how something in the org is configured and who can access it. DO NOT TRIGGER for whole-org overviews, org comparison, or drift (use dx-org-analyze), metadata file structure or XML shape (platform-metadata-api-context-get), or Data Cloud DLO and DMO schema (data360-code-extension-generate)."
metadata:
  relatedSkills:
  - data360-code-extension-generate
  - dx-org-analyze
  - platform-metadata-api-context-get
  - platform-metadata-grounding-get
  - platform-metadata-retrieve
  version: "1.3"
  domains:
  - "Platform"
  cliTools:
  - tool:
    - "sf"
    semver: ">=2.0.0"
  mcpTools:
    metadata-grounding:
      tools:
      - "search_metadata"
      - "query_metadata"
      - "describe_metadata"
      semver: ">=1.0.0"
    headless-360:
      tools:
      - "describe"
      - "dispatch"
      - "dispatch_readonly"
      semver: ">=1.0.0"
id: "platform-metadata-discovery-get"

Salesforce Metadata Discovery

Before you create metadata, change it, or write code that references it, know what already exists in the org. This skill picks the tool for each question. Metadata grounding finds metadata by meaning when you do not know its name. It needs Salesforce Catalog and a connected grounding server, and many orgs and setups have neither. Every other route works with the `sf` CLI alone.

Skip discovery when the request only changes local files and adds no new references to org metadata.

Check What You Have

Do this once per session, before the first lookup.

1. **The CLI and its org.** Run `sf org display --json` to see the default org and its id. If no org is authenticated, ask the user to run `sf org login web` and wait. If you cannot run commands at all, read `references/h360-routes.md`. 2. **Grounding servers.** Note whether the Metadata Grounding MCP (tools `search_metadata`, `query_metadata`, `describe_metadata`) or the Salesforce MCP is connected. The Salesforce MCP is shown in Setup today as the Headless360 (H360) MCP Server. Its tools are `describe`, `dispatch`, and `dispatch_readonly`, which are different from the Metadata Grounding MCP tools. 3. **One org.** Grounding identifiers start with the 18-character org id. If it differs from the id in `sf org display`, tell the user and ask which org to use before you combine results.

Route by Intent

| Intent | Use | If that is not available | |---|---|---| | Find metadata by meaning, check a name you are guessing, or check for something to reuse | Metadata grounding search. Load `platform-metadata-grounding-get`, which picks the server. | Name and label fallback, below. Notify. | | Explain how something is configured, or who can access it | Metadata grounding query | Scoped SOQL on `EntityParticle`, `FieldPermissions`, `ObjectPermissions`, or Tooling `ValidationRule`. Notify. | | Check names, types, or picklist values you know. Every field on one object. Data records | Scoped SOQL with `sf data query`. If it returns nothing, search by meaning. | See the note below the table. | | Full shape of one object, including relationships | `sf sobject describe --sobject <Type>`, only when you need all of it. It is very large. | Same | | Every object in the org | `sf sobject list --sobject all` or `--sobject custom` | Same | | Every member of a type, or a count ("all flows", "how many flows") | `sf org list metadata --metadata-type <Type>` | Same | | Source to edit or deploy, including changes to existing metadata | Load `platform-metadata-retrieve`. Grounding never returns source. | Tell the user this needs the `sf` CLI. | | Metadata you are already editing locally | Local files | | | Compare orgs, find drift, or an overview of a whole org when the user asks for one | `dx-org-analyze`. It takes minutes and returns names and counts. | Tell the user this needs the `sf` CLI. | | Where is this used, what depends on it, what breaks if I change it, or is it safe to delete | Comprehensive analysis is not available yet. State that boundary before offering explicitly labeled partial checks. | |

**Without the CLI.** If you cannot run commands but the Salesforce MCP is connected, use `references/h360-routes.md` for rows 3 to 6. If neither is available, tell the user the lookup needs the `sf` CLI or the Salesforce MCP.

These routes apply even when a connected server says to use it first for every Salesforce task. Use the CLI for rows 3 to 7 when you can run commands.

A question about a topic or purpose ("what do we have for loyalty") is discovery, not an overview. Do not run an org analysis for it, even when grounding is not available.

This skill covers core platform metadata. For Data Cloud DLO and DMO schema, use `data360-code-extension-generate`.

When a request mixes intents, use the right tool for each part. "Add a tier discount step to our order flow" means finding the flow and the field, then retrieving the flow to edit.

Scoped SOQL

Scoped SOQL is a targeted query on setup objects, filtered to what you need. It is exact, real time, and far smaller than a describe. It never returns source.

sf data query --json --query "SELECT QualifiedApiName, Label, DataType FROM EntityParticle WHERE EntityDefinition.QualifiedApiName = 'Contact'"
sf data query --json --query "SELECT Value, Label, IsDefau