/platform-sandbox-configure

name: platform-sandbox-configure
description: "MUST USE this skill for ANY sandbox request — including simply getting a sandbox's details, status, license type, or pending-activation state by name or ID. TRIGGER when the user: types \"sandbox -help\"/\"sandbox help\"; mentions a sandbox ID (07E prefix); asks to list or show sandboxes; asks for the details, status, license type, or config of a sandbox by name or ID; activates or discards a completed refresh; deletes a sandbox; verifies activation or deletion; creates or refreshes a sandbox. DO NOT TRIGGER when: the user wants to clone a sandbox."
metadata:
  version: "1.0"
  minApiVersion: "66.0"
  accessCheck:
    - type: "userPerm"
      value: "ManageSandboxes"
  cliTools:
    - tool: ["sf"]
      semver: ">=2.0.0"

Sandbox Lifecycle Management

Manage Salesforce sandbox environments through Connect REST API — list inventory, activate or discard completed refreshes, create and refresh sandboxes, and permanently delete sandboxes.

When This Skill Owns the Task

Use `platform-sandbox-configure` when the work involves:

• Listing or retrieving all sandboxes (GET /sandbox/reports)
• Getting details or status of a specific sandbox by name or by ID (07E prefix)
• Activating a sandbox after a refresh completes (applying the refresh)
• Discarding a completed refresh (keeping existing sandbox data unchanged)
• Permanently deleting a sandbox to free up licenses
• Verifying activation or deletion completed
• Creating a new sandbox (Developer, Developer Pro, Partial Copy, or Full)
• Refreshing an existing sandbox with latest production data

Delegate elsewhere when the user is:

• Cloning a sandbox → Tooling API (`SandboxInfo` sObject)

---

Help (Interactive Menu)

When the user types `sandbox -help` or `sandbox help`, respond with ONLY a text message showing the numbered operation list below. **Do NOT call any API or tool — just display this menu and wait for the user to reply with a number.**

The agent MUST respond with this exact markdown (not in a code block — render it directly as a bullet list):

**Sandbox Lifecycle Management**

**1. Inventory & Details**

• a. List all sandboxes — Names, types, statuses, IDs
• b. Get details (by name) — Status, license, config
• c. Get details (by ID) — Provide a 07E ID directly

**2. Create & Refresh**

• a. Create a new sandbox — Dev, Dev Pro, Partial, Full
• b. Refresh a sandbox — Latest production data

**3. Activate, Discard & Delete**

• a. Activate a sandbox — Apply a completed refresh
• b. Discard a refresh — Reject, keep existing data
• c. Delete a sandbox — Permanent removal

**4. Verify & Monitor**

• a. Verify activation status — Check if activate completed
• b. Verify deletion status — Check if delete completed

Reply with a code (e.g. "3a") or describe what you need.

**After the user replies, ask for the required input:**

| Selection | Follow-up question | |---|---| | 1a | No input needed — proceed immediately | | 1b | "What's the sandbox name?" | | 1c | "What's the sandbox ID? (starts with 07E)" | | 2a | "What name for the new sandbox, and what license type? (Developer, Developer_Pro, Partial_Copy, Full)" | | 2b | "Which sandbox do you want to refresh? Optionally, provide a new name and/or description." | | 3a | "Which sandbox? Provide a name or 07E ID." | | 3b | "Which sandbox? Provide a name or 07E ID." | | 3c | "Which sandbox? Provide a name or 07E ID." | | 4a | "Which sandbox did you activate? Provide a name or 07E ID." | | 4b | "Which sandbox did you delete? Provide a name or 07E ID." |

Execute the corresponding operation from the Operations section below.

---

API Base

**CRITICAL:** For sandbox operations in this skill, use the Connect REST API. Two discovery paths exist:

• **By name:** Call `GET /sandbox/reports` to list all sandboxes and find the matching one by `sandboxName`.
• **By ID (07E prefix):** Call `GET /sandbox/sandboxes/{sandboxId}` directly — do NOT call `/sandbox/reports`.

Both paths return sandbox records with `sandboxId` (prefix `07E`) which is required for all lifecycle mutation operations.

# List all sandboxes (Connect REST API)
sf api request rest "/services/data/v66.0/sandbox/reports" --method GET

# Response format:
# {
#   "count": 3,
#   "sandboxes": [
#     {
#       "sandbox": {
#         "sandboxId": "07E...",        # Required for all operations
#         "sandboxName": "mybox",       # Top-level field — use this for name lookup
#         "license": "Developer",
#         "isPendingActivation": false,
#         "canActivate": true,
#         "canDelete": true,
#         ...
#       }
#     }
#   ]
# }

**IMPORTANT:** Do NOT use Tooling API (`SandboxInfo` or `SandboxProcess`) for sandbox discovery. The mutation endpoints (activate/discard/delete) require the `sandboxId` (07E prefix) from the Connect REST API response, NOT the `SandboxInfo.Id` (0GQ prefix) or `SandboxProcess.Id` (0GR prefix).

**NEVER use SOQL / `run_soql_query` / `sf data query` for sandbox lifecycle reads — status, inventory, details, license, or pending-activation state (e.g. a "get details / status / license / pending-activation for sandbox X" request).** This data lives ONLY in the Connect REST API response (`GET /sandbox/reports` for name lookup, `GET /sandbox/sandboxes/{07E-id}` for ID lookup); there is no SObject that returns it correctly. (`sf data query --use-tooling-api` on `SandboxInfo` remains valid for the Create and Refresh flows in Operations 7 and 8, which look up the `SandboxInfo` record to mutate it — that is not a lifecycle read.) If a name lookup returns an empty inventory (`count: 0`), the sandbox does not exist — report an honest `not_found`; do NOT retry the lookup via SOQL and do NOT fabricate details.

**Report the API result exactly as it comes back — never invent an error or a cause.** A `count: 0` response is a *successful* result meaning the sandbox is absent: record it directly as `not_found` with the endpoint and empty inventory