/dx-org-manage

name: dx-org-manage
description: "INVOKE this skill to execute Salesforce org operations: create 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 (Developer/Enterprise edition, from definition file (.json), from snapshot, or from org shape), create an org snapshot, or open a Salesforce org. Trigger phrases include: 'create a snapshot', 'create snapshot of my scratch org', 'take a snapshot', 'create scratch org', 'create a Developer edition scratch org', 'new scratch org', 'spin up an org', 'create org from snapshot', 'scratch-def.json', 'project-scratch-def.json', 'open my Salesforce org', 'open org in browser', 'get me the URL'. Do NOT use for switching default org (use dx-org-switch) or deploying metadata (use platform-metadata-deploy)."
metadata:
  version: "1.1"
  minApiVersion: "60.0"
  relatedSkills:
    - "dx-org-switch"
    - "platform-metadata-deploy"
  cliTools:
    - 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, `snapshot-result.json` for snapshot creation, or `org-url-result.json` for open operations. This is the generated output — write it without asking. Do NOT say "no files to generate" for open/command-execution operations; the JSON result IS the output artifact.

---

Creating Scratch Orgs

**REQUIRED steps — execute in order:**

**Step 1. Identify creation method** from user request:

• Contains "definition file" or path to `.json` → definition file method
• Contains "snapshot" or "from snapshot" → snapshot method
• Contains "org shape" or "source-org" → org shape method
• Otherwise → run `ls config/project-scratch-def.json config/scratch-def.json 2>/dev/null | head -1` to detect a definition file. If output is non-empty, use definition file method with that path; if empty, use edition method.

**Step 2. Check Dev Hub:**

sf config get target-dev-hub --json

• If no Dev Hub is set, advise: `sf org login web --set-default-dev-hub`
• Do NOT proceed until a Dev Hub is confirmed.

**Step 3. Build and execute the command** based on method:

**Definition file:**

sf org create scratch --definition-file <path> --target-dev-hub <alias> --alias <name> --json

**Edition only:**

sf org create scratch --edition developer --target-dev-hub <alias> --alias <name> --json

**From snapshot:**

sf org create scratch --snapshot <snapshot-name> --target-dev-hub <alias> --alias <name> --json

**From org shape:**

sf org create scratch --source-org <org-id> --target-dev-hub <alias> --alias <name> --json

**Apply these flags when requested:**

• `--duration-days <days>` — default 7, max 30
• `--set-default` — make this the default org
• `--no-track-source` — disable source tracking (for CI/CD)

**Step 4. MANDATORY - Run org list and write output:** After the org is created, you MUST run this command:

sf org list --json

Then: 1. Parse the JSON result and find the `scratchOrgs` array 2. Find the entry where `username` matches the username from Step 3's creation result 3. Extract that complete org object (it will include: alias, username, orgId, instanceUrl, loginUrl, isDefaultUsername, connectedStatus, lastUsed, etc.) 4. Report to the user:

• Created scratch org.
• Alias: [alias from the org list entry]
• Username: [username]
• Org ID: [orgId]

5. If an output directory is available (per the output artifacts rule above), write ONLY that extracted org object (NOT the full creation result) to `<output-dir>/scratch-org-result.json`

Example: If `sf org list --json` returns `{"result": {"scratchOrgs": [{"alias": "feature-dev", "username": "test@example.com", "orgId": "00D...", ...}]}}`, write just the inner org object `{"alias": "feature-dev", "username": "test@example.com", "orgId": "00D...", ...}` to the file.

Do NOT write the creation command's output. Do NOT suggest verification steps to the user.

**Error handling:**

• "Snapshot not found" → suggest `sf org list snapshot --target-dev-hub <alias>`
• "No default Dev Hub" → advise `sf org login web --set-default-dev-hub`

**When you need more detail:**

• For available features, settings, and definition file structure → load `references/definition_file_options.md`
• For edition selection guidance and comparison → load `references/edition_types.md`
• For snapshot workflow and post-creation usage → load `references/snapshot_usage.md`
• For complete scratch org creation workflow → load `references/creating-scratch-org.md`

---

Creating Snapshots

**REQUIRED steps — execute in order:**

**Step 1. Get inputs:**

• Source org: scratch org ID or alias (from user)
• Snapshot name: unique name (from user)
• Description: optional (from user)

**Step 2. Determine Dev Hub:**

• If user specifies a Dev Hub (alias or username) → use that value
• Otherwise, check for default:

sf config get target-dev-hub --json

• If no default Dev