/dx-org-snapshot-manage

name: dx-org-snapshot-manage
description: "ALWAYS USE THIS SKILL to create, check the status of, list, or delete scratch org snapshots. A snapshot is a point-in-time copy of a scratch org's metadata AND data, referenced by name in the `snapshot` field of a scratch org definition file. Use when the user asks to create/take a snapshot, check a snapshot's status or creation progress, list/show/view existing snapshots (including filtering for snapshots expiring soon), or delete/remove a snapshot. Requires a Dev Hub with Scratch Org Snapshots enabled. DO NOT TRIGGER for creating org shapes (use dx-org-shape-manage) or for creating scratch orgs, including from an existing snapshot via `--snapshot` (use dx-org-manage)."
metadata:
  version: "1.0"
  domains: ["Developer Experience"]
  minApiVersion: "60.0"
  relatedSkills:
    - "dx-org-manage"
    - "dx-org-shape-manage"
  cliTools:
    - tool: ["sf"]
      semver: ">=2.0.0"
    - tool: ["jq"]
      semver: ">=1.6"
  accessCheck:
    - type: "orgPref"
      value: "ScratchOrgSnapshotPref"

dx-org-snapshot-manage

Coordinates the full lifecycle of Salesforce scratch org snapshots — **create**, **get** (status), **list**, and **delete** — via `sf org create snapshot`, `sf org get snapshot`, `sf org list snapshot`, and `sf org delete snapshot`. A snapshot is a point-in-time copy of a scratch org (its metadata **and** data) that you reference by name in a scratch org definition file to spin up new orgs from saved state.

---

Tool Restrictions

**Use ONLY the Bash tool** to execute the `sf org ... snapshot` commands. Do NOT use MCP tools — ignore them completely.

**Output artifacts for eval/testing:** ALWAYS write the command's complete 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 each command: (1) if the user specified an output path, 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, unmodified JSON response to `<output-dir>/<filename>` using these filenames: `create-snapshot-result.json`, `get-snapshot-result.json`, `list-snapshots-result.json`, or `delete-snapshot-result.json`. This is the generated output — write it without asking. (4) If no output directory can be found by either check, include the command's complete, unmodified JSON response verbatim (e.g. in a fenced code block) in your final reply instead of skipping the artifact.

---

Relationship to Other Skills

This skill owns the **full snapshot lifecycle** — create, get status, list, and delete. It does not create scratch orgs.

• **Any snapshot operation** (create, status, list, delete, expiry check) → this skill.
• **Create a scratch org, including from an existing snapshot** (`--snapshot <name>`) → `dx-org-manage`.
• **Org shapes** (baseline config without data, `sf org create/list/delete shape`) → `dx-org-shape-manage`. Shapes and snapshots are different artifacts with different commands — see the comparison below.

| | Snapshot (this skill) | Org Shape (`dx-org-shape-manage`) | |--|----------|-----------| | Captures | Full point-in-time copy: metadata **and** data | Baseline config only: features, limits, edition, Metadata API settings | | Commands | `sf org create/get/list/delete snapshot` | `sf org create/list/delete shape` | | Referenced via | `snapshot` (name) in the scratch def file | `sourceOrg` (org ID) in the scratch def file | | Prerequisite | **Dev Hub** has Scratch Org Snapshots enabled | **Source org** has Org Shape for Scratch Orgs enabled | | Operates against | A **Dev Hub** (`--target-dev-hub`) | The **source org** (`--target-org`) |

---

Scope

• **In scope**: Creating (`sf org create snapshot`), getting status (`sf org get snapshot`), listing (`sf org list snapshot`), and deleting (`sf org delete snapshot`) scratch org snapshots
• **Out of scope**: Creating org shapes (`dx-org-shape-manage`), creating scratch orgs — including from a snapshot (`dx-org-manage`)

---

Required Inputs

Infer from the user's request:

• **Operation**: create, get, list, or delete (see Workflow step 1)
• **Dev Hub**: Username or alias of the Dev Hub that owns the snapshots. Passed via `--target-dev-hub` (`-v`); optional if the `target-dev-hub` config variable is set. **All four commands** operate against a Dev Hub, never `--target-org`.
• **Source org** (create only): Scratch org ID (starts with `00D`), username, or alias to snapshot. Passed via `--source-org` (`-o`).
• **Snapshot name** (create only): A unique name for the snapshot, **max 15 characters**. Passed via `--name` (`-n`).
• **Snapshot name or ID** (get & delete only): Name, or ID (starts with `0Oo`), of the snapshot. Passed via `--snapshot` (`-s`).
• **Description** (create, optional): Documents snapshot contents.
• **Expiry threshold in days** (expiring-soon listing only): There is no CLI flag for this — it's a client-side filter on `ExpirationDate` (see Command Patterns).

---

Workflow

1. **Identify the operation** and match it to the command pattern below. 2. **Resolve the Dev Hub** — if `--target-dev-hub` isn't provided, check the default with `sf config get target-dev-hub`. Never fabricate a placeholder Dev Hub name (e.g. `my-dev-hub`) — an unresolved hub is a hard stop; advise `sf org login web --set-default-dev-hub` instead. 3. **For create, confirm the source org and snapshot name** — the source must be a scratch org; the name must be unique in the Dev Hub and ≤15 characters. 4. **Execute via Bash tool** with the `--json` flag. 5. **Report the result** (see Output Expectations and the example files).

Command Patterns

| Operation | User intent | Execute via Bash tool | |-----------|-------------|------------------------| | **Create** | Create snapshot with name only | `sf org create snapshot --source-org <orgId\|alias> --name <SnapshotName> -