/dx-org-shape-manage

name: dx-org-shape-manage
description: "ALWAYS USE THIS SKILL to create, list, or delete org shapes. An org shape is a captured baseline configuration (features, limits, edition, and Metadata API settings) of a source org, without its data or metadata. Use when the user asks to create/make/take an org shape, capture or replicate an org's configuration/edition/limits, list/show/view existing org shapes (including INACTIVE/superseded ones) or their IDs and status, or delete/remove org shapes for a source org. Requires a source org with Dev Hub and Org Shape for Scratch Orgs enabled. DO NOT TRIGGER for creating/checking/listing/deleting snapshots (use dx-org-snapshot-manage) or for creating scratch orgs (use dx-org-manage)."
metadata:
  version: "1.0"
  domains: ["Developer Experience"]
  relatedSkills:
    - "dx-org-manage"
    - "dx-org-snapshot-manage"
  cliTools:
    - tool: ["sf"]
      semver: ">=2.0.0"
  accessCheck: "(OrgPreferences.ScratchOrgManagementPref) && (OrgPreferences.ShapeExportPref)"

dx-org-shape-manage

Coordinates the full lifecycle of Salesforce org shapes — **create**, **list**, and **delete** — via `sf org create shape`, `sf org list shape`, and `sf org delete shape`. An org shape captures the baseline setup of a source org (features, limits, edition, and Metadata API settings) **without** its data or metadata.

---

Tool Restrictions

**Use ONLY the Bash tool** to execute the `sf org ... shape` 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 (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, unmodified JSON response (including the `status`/`result`/`warnings` wrapper) to `<output-dir>/<filename>` using these filenames: `create-shape-result.json` for shape creation, `list-shapes-result.json` for listing shapes, `list-shapes-inactive-result.json` for the inactive-shapes SOQL query, or `delete-shapes-result.json` for shape deletion. This is the generated output — write it without asking. Do NOT say "no files to generate" for these operations; the JSON result IS the output artifact.

---

Scope

• **In scope**: Creating (`sf org create shape`), listing (`sf org list shape`), listing including inactive shapes for a specific source org (SOQL against `ShapeRepresentation`), and deleting (`sf org delete shape`) org shapes
• **Out of scope**: Creating/checking/listing/deleting snapshots (use `dx-org-snapshot-manage`), creating scratch orgs (use `dx-org-manage`)

---

Required Inputs

Infer from the user's request:

• **Operation**: create, list, list-including-inactive, or delete (see Workflow step 1)
• **Source org** (create, delete, & list-including-inactive): Username or alias of the org to shape / whose shapes to delete or query. Passed via `--target-org`. Plain listing (Active/InProgress only) needs no source org.

Notes:

• There is **no** `--name` or `--description` flag — a shape is identified by the source org's ID, not a custom name.
• There is **no** `--target-dev-hub` flag — the shape commands operate on the source org directly, not a Dev Hub.

---

Workflow

1. **Identify the operation** and match it to the command pattern below. 2. **For create/delete, confirm the source org** — identify the username/alias. If not provided, check the default with `sf config get target-org`. 3. **Execute via Bash tool** with the `--json` flag. 4. **Report the result** (see Output Expectations and the example files).

Command Patterns

| Operation | User intent | Execute via Bash tool | |-----------|-------------|------------------------| | **Create** | Create shape from an org | `sf org create shape --target-org <alias> --json` | | **Create** | Create shape from the default target org | `sf org create shape --json` | | **List** | List all org shapes + IDs/status (Active/InProgress only) | `sf org list shape --json` | | **List** | Save the list to a file | `sf org list shape --json > tmp/MyOrgShapeList.json` | | **List (including inactive)** | List *all* shapes — including `Inactive` ones — for a specific source org | `sf data query --target-org <alias> --query "SELECT Id, Name, Status, CreatedDate, LastModifiedDate FROM ShapeRepresentation" --json` | | **Delete** | Delete shapes for an org (with confirm prompt) | `sf org delete shape --target-org <alias> --json` | | **Delete** | Delete shapes without prompting (scripts/CI) | `sf org delete shape --target-org <alias> --no-prompt --json` |

After creating a shape, run `sf org list shape --json` to get its **org ID**.

Listing Inactive Shapes

`sf org list shape` has **no flag** to surface `Inactive` shapes and **no `--target-org`** flag (it always scans every locally authenticated org). To see a source org's full shape history — including shapes superseded by a later `sf org create shape` run — query `ShapeRepresentation` directly:

sf data query --target-org <alias> --query "SELECT Id, Name, Status, CreatedDate, LastModifiedDate FROM ShapeRepresentation" --json

Only use this query when the user explicitly asks for **inactive** or **all/historical** shapes for a named source org. For ordinary "list my org shapes" requests, keep using `sf org list shape` — it is the documented, cross-org command and matches the rest of this skill's behavior.

Notes:

• `ShapeRepresentation` has no `SourceOrgId`, `username`, or `alias` field — report the raw query fields (`Id`, `Name`, `Status`, `CreatedDate`, `LastModifiedDate`) as returned; do not invent an `orgId`/`username`/`alias` for these rows.
• Add `WHERE Status = 'Inactive'` to s