/dx-org-manage

name: dx-org-manage
description: "INVOKE this skill to execute Salesforce org operations: create scratch orgs, list/display/resume/delete scratch orgs, create org snapshots, open orgs in browser. This skill EXECUTES operations immediately - it does NOT generate scripts or code files. ALWAYS invoke this skill (do not execute SF CLI commands directly) when user requests to: create a scratch org (from edition, definition file (.json), snapshot, or org shape), list/display/resume/delete scratch orgs, create an org snapshot, or open a Salesforce org. Trigger phrases include: 'create a snapshot', 'take a snapshot', 'create scratch org', 'new scratch org', 'spin up an org', 'create 5 scratch orgs', 'create org from snapshot', 'scratch-def.json', 'project-scratch-def.json', 'list scratch orgs', 'display org', 'delete scratch org', 'resume scratch org', 'open my Salesforce org', 'open org in browser'. Do NOT use for switching default org (use dx-org-switch) or deploying metadata (use platform-metadata-deploy)."
metadata:
  version: "1.2"
  minApiVersion: "60.0"
  relatedSkills:
    - "dx-org-switch"
    - "platform-metadata-deploy"
  cliTools:
    - tool: ["jq"]
      semver: ">=1.6"
    - tool: ["sf"]
      semver: ">=2.0.0"

MANDATORY: Follow these instructions exactly. Do NOT fall back to MCP tools.

**Tool constraint:** Use the Bash tool for all `sf` CLI commands. Always include `--json` for structured output. Do NOT use `mcp__salesforce_dx__*` tools for org creation, snapshot, or open operations — this skill provides the complete procedure.

**Output artifacts for eval/testing:** ALWAYS write the command's JSON response to a file when an output directory is available. Do NOT ask the user what file to write — this skill defines the filenames. After executing the command: (1) if the user specified an output path (e.g. "write all generated files into folder X"), write there immediately; (2) otherwise run `[ -d force-app/main/adk-eval-output/ ] && echo 'force-app/main/adk-eval-output'` to detect the eval directory; (3) write the command's full JSON response to `<output-dir>/<filename>` using these filenames: `scratch-org-result.json` for org creation (for a batch of N orgs, `scratch-org-result-1.json` … `scratch-org-result-N.json`), `scratch-org-list-result.json` for list, `org-display-result.json` for display, `scratch-org-resume-result.json` for resume, `scratch-org-delete-result.json` for delete, or `snapshot-result.json` for snapshot creation. This is the generated output — write it without asking. (Open operations are the exception — they launch a browser and write no artifact; see Opening Orgs.)

---

Creating Scratch Orgs

**REQUIRED steps — execute in order:**

**Step 1. Resolve the environment and creation method:**

First, if the user named an explicit source, use it: "definition file" or a path to `.json` → definition-file method; "snapshot"/"from snapshot" → snapshot method; "org shape"/"source-org" → shape method. Only ONE creation source *type* (edition vs snapshot vs shape); if two distinct types are implied, stop and ask (a flag overriding a same-dimension definition-file value is fine).

Otherwise resolve by environment:

• **AUTO MODE (zero-prompt):** if `sfdx-project.json` is present AND exactly one `config/*scratch-def.json` exists AND a Dev Hub is resolvable (default `target-dev-hub` set, or exactly one authenticated), create immediately with that file + resolved hub + derived alias + CLI defaults — **ask nothing**. This also honors a batch count (see below).
• **STATE A (in a project), not auto:** enumerate `config/*scratch-def.json` — 0 files → default `--edition developer` (or author one if features/settings are wanted, see below); 1 file → use it; many → **ask which one** (never silently pick).
• **STATE B (no `sfdx-project.json`):** do NOT block and do NOT silently create a throwaway — present the guided 3-way choice (point to a project / scaffold one via `sf template generate project --name <name>` / create a throwaway here, then guide the source). See `references/scratch-org-create.md`.

**Batch — "create N scratch orgs":** there is no native count flag — loop the create command N times with N distinct aliases (`<base>-1` … `<base>-N`, each collision-guarded so it never re-points an existing org). Report each org and write one artifact per org. On a mid-loop Dev Hub limit error, surface the CLI's error unchanged and report which orgs already succeeded.

**Definition-file authoring:** if features/settings are requested and no suitable file exists, author a new purpose-named definition file (seed-then-modify; documented fields only; no-clobber), show it, and create from it. **In a non-interactive/eval context, author the file AND proceed to create without waiting** for edit confirmation. Details in `references/scratch-org-create.md` and `references/definition_file_options.md`.

**Step 2. Resolve the Dev Hub to a concrete value — then pass it explicitly.** Resolve it **once** to an actual username or alias and pass that exact value via `--target-dev-hub` on every command in Step 3. Resolution order:

1. **A Dev Hub the user named explicitly** → use it verbatim. 2. **Else the default:** the non-empty `result[0].value` from `sf config get target-dev-hub --json`.

   sf config get target-dev-hub --json

3. **Else the single authenticated Dev Hub.** Run **this exact command** — do NOT hand-write your own filter. A Dev Hub can appear in **any** of the `sf org list` buckets (`devHubs`, `nonScratchOrgs`, `other`, `sandboxes`, `scratchOrgs`); a filter that checks only one bucket (e.g. only `.other[]`) misses it and makes you think no hub exists:

   sf org list --json | jq -r '[.result.devHubs[]?, .result.nonScratchOrgs[]?, .result.other[]?, .result.sandboxes[]?, .result.scratchOrgs[]?] | map(select(.isDevHub == true).username) | unique | .[]'

• **Exactly one** username printed → use it.
• **Zero** printed → no hub is authenti