dx-org-shape-manage
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).
- Installs
- 1K
- Last 24h
- +11
- Trending rank
- #8255
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/forcedotcom/sf-skills --skill dx-org-shape-manage- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads dx-org-shape-manage automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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 againstShapeRepresentation), and deleting (sf org delete shape) org shapes - Out of scope: Creating/checking/listing/deleting snapshots (use
dx-org-snapshot-manage), creating scratch orgs (usedx-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
--nameor--descriptionflag — a shape is identified by the source org's ID, not a custom name. - There is no
--target-dev-hubflag — the shape commands operate on the source org directly, not a Dev Hub.
Workflow
- Identify the operation and match it to the command pattern below.
- For create/delete, confirm the source org — identify the username/alias. If not provided, check the default with
sf config get target-org. - Execute via Bash tool with the
--jsonflag. - 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:
ShapeRepresentationhas noSourceOrgId,username, oraliasfield — report the raw query fields (Id,Name,Status,CreatedDate,LastModifiedDate) as returned; do not invent anorgId/username/aliasfor these rows.- Add
WHERE Status = 'Inactive'to scope to only inactive shapes if the user asks for inactive shapes specifically (as opposed to "all"/"history"). - Requires the same
ShapeRepresentationCRUD access as create/delete.
Rules / Constraints
| Constraint | Rationale |
|---|---|
Always use --json flag | Provides structured output for reliable parsing and error handling |
| Source org must have Org Shape for Scratch Orgs enabled | Without it, create/delete fail with a no-access error — enable via Setup → Scratch Orgs → Enable Org Shape for Scratch Orgs in the source org |
User needs access to the ShapeRepresentation object | Without CRUD access, create fails with NoCrudAccessCreateShape — ask the org admin |
--target-org is the SOURCE org, not a Dev Hub | Create/delete operate on this org; it is not a Dev Hub operation. List takes no --target-org |
No --name / --description flags | A shape is keyed off the source org's ID, not a custom name |
| One active shape per source org | Re-running create replaces the prior shape (marks it inactive). delete removes all shapes for the org |
delete prompts for confirmation by default | Use --no-prompt (-p) for non-interactive/CI use; declining the prompt aborts with no deletion |
Troubleshooting
| Issue | Resolution |
|---|---|
ShapeRepresentationNoAccess — "The org needs to be enabled for org shape before one can be created" | Source org isn't enabled for org shape — in the source org go to Setup → Scratch Orgs → Enable Org Shape for Scratch Orgs, turn it on, then retry |
NoCrudAccessCreateShape — "Can't create org shape. Contact the org admin..." | You lack access to the ShapeRepresentation object — ask the org admin to grant access, then retry |
ShapeCreateFailed — "Error creating scratch definition file..." | Generic create failure — verify the source org is reachable/authenticated and retry; if it persists, contact Salesforce support |
UNKNOWN_EXCEPTION on create (generic error with a support ErrorId, reproducible on retry) | The source org is not fully enabled for org shape even though ShapeRepresentation may be partially visible — confirm Setup → Scratch Orgs → Enable Org Shape for Scratch Orgs is on in the source org and that your user has CRUD on ShapeRepresentation, then retry |
sf org list shape returns an empty list | No shapes exist yet (or none are Active/InProgress) — create one with sf org create shape |
sf org list shape doesn't show a shape the user expects | It only surfaces Active/InProgress shapes and has no flag to change this — a prior sf org create shape run may have marked it Inactive. Use the SOQL query in "Listing Inactive Shapes" against that specific source org instead |
| Delete exits with code 68 (partial failure) | Some shapes failed to delete — inspect the failures array in the JSON for per-shape messages, then retry |
| Delete exits with code 1 (all failed) | Deletion failed entirely — confirm the org is enabled for org shape and you have access |
No org found for <alias> / NamedOrgNotFoundError | Source org alias doesn't exist or isn't authenticated — verify with sf org list or re-auth with sf org login web |
No default target org and --target-org omitted | Provide --target-org <alias> or set a default with sf config set target-org=<alias> |
Output Expectations
All commands return JSON when --json is used:
- Create →
shapeId,success, anderrors. - List → an array of shapes, each with
orgId,username,alias,shapeId,status(ActiveorInProgress),createdBy, andcreatedDate. - List (including inactive) → a SOQL query result (
records,totalSize,done), each record withId,Name,Status(Active,InProgress, orInactive),CreatedDate, andLastModifiedDate— noorgId/username/alias, sinceShapeRepresentationhas no such fields. - Delete →
orgId,shapeIds(deleted), andfailures. Returns no result if the user declines the confirmation prompt.
See the example files referenced below for full response structures.
Cross-Skill Integration
| Need | Delegate to |
|---|---|
| Create a scratch org, or create/use a snapshot to make one | dx-org-manage skill |
| Create, check status of, list, or delete a snapshot itself | dx-org-snapshot-manage skill |
Reference File Index
| File | When to read |
|---|---|
examples/create_success_output.json | To understand the successful shape-creation response structure |
examples/create_error_output.json | To handle common create error scenarios |
examples/list_output.json | To understand the list response structure (org IDs, status) |
examples/list_inactive_output.json | To understand the SOQL query response structure for listing shapes including Inactive ones |
examples/delete_output.json | To understand the delete response structure (deleted IDs, failures) |
references/cli_flags.md | For detailed explanation of all flags across create/list/delete |
FAQ
What does the dx-org-shape-manage skill do?
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).
How do I install dx-org-shape-manage?
Run npx skills add https://github.com/forcedotcom/sf-skills --skill dx-org-shape-manage in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/dx-org-shape-manage/ (personal) or .claude/skills/dx-org-shape-manage/ (project).
Which AI agents can use dx-org-shape-manage?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is dx-org-shape-manage safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains dx-org-shape-manage?
It is published by forcedotcom in forcedotcom/sf-skills. It has 1,044 recorded installs.
More from forcedotcom/sf-skills
platform-apex-generate
forcedotcom/sf-skills
Primary Apex authoring skill for class generation, refactoring, and review. ALWAYS ACTIVATE when the user mentions Apex, .cls, triggers, or asks to create/refactor a class (service, selector, domain, batch, queueable, schedulable, invocable, DTO, utility, interface, abstract, exception, REST resource). Use this skill for requests involving SObject CRUD, mapping collections, fetching related records, scheduled jobs, batch jobs, trigger design, @AuraEnabled controllers, @RestResource endpoints, custom REST APIs, or code review of existing Apex.
platform-apex-test-generate
forcedotcom/sf-skills
Use to generate and validate Apex test classes with TestDataFactory patterns, bulk testing (251+ records), mocking, assertions, and disciplined test-fix loops. Use when creating Apex test classes (for triggers, services, controllers, batch jobs, queueables, and callouts), improving coverage, debugging or fixing failing Apex tests, or running test/coverage analysis. Triggers on Test.cls files, sf apex run test, coverage reports. Do NOT trigger for production Apex (use platform-apex-generate) or Jest/LWC tests.
platform-apex-test-run
forcedotcom/sf-skills
Apex test execution, coverage analysis, and test-fix loops with 120-point scoring. Use when the user runs Apex tests, checks code coverage, fixes failing tests, or touches Test.cls / Test.cls files. DO NOT TRIGGER when writing Apex production code (use platform-apex-generate), Agentforce agent testing (use agentforce-test), or Jest/LWC tests (use experience-lwc-generate).
platform-apex-logs-debug
forcedotcom/sf-skills
Salesforce debug log analysis and troubleshooting with 100-point scoring. TRIGGER when: user analyzes debug logs, hits governor limits, reads stack traces, or touches .log files from Salesforce orgs. DO NOT TRIGGER when: running Apex tests (use platform-apex-test-run), generating or fixing Apex code (use platform-apex-generate), or Agentforce session tracing (use agentforce-observe).
platform-soql-query
forcedotcom/sf-skills
Use when the user needs SOQL/SOSL authoring or optimization: natural-language-to-query generation, relationship queries, aggregates, query-plan/selectivity analysis, and performance or safety improvements. TRIGGER when the user writes, optimizes, or debugs SOQL/SOSL, touches .soql files, or asks about relationship queries, aggregates, or query performance. DO NOT TRIGGER for bulk data operations (use platform-data-manage), Apex DML logic (use platform-apex-generate), or report/dashboard queries.
platform-metadata-deploy
forcedotcom/sf-skills
Salesforce DevOps automation using sf CLI v2. TRIGGER when: user deploys metadata, validates a deploy or does a dry-run, deploys to a Production org, quick-deploys a validated job ID, ships/promotes to prod, creates/manages scratch orgs or sandboxes, sets up CI/CD pipelines, or troubleshoots deployment errors with sf project deploy. DO NOT TRIGGER when: writing Apex code, building LWC components (use experience-lwc-generate), creating metadata definitions (use platform-custom-object-generate), deleting metadata from an org (use platform-destructive-deploy), or querying org data (use platform-data-manage).
Popular backend & apis skills
find-skills
vercel-labs/skills
Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
entra-app-registration
microsoft/azure-skills
Guides Microsoft Entra ID app registration, OAuth 2.0 authentication, and MSAL integration. USE FOR: create app registration, register Azure AD app, configure OAuth, set up authentication, add API permissions, generate service principal, MSAL example, console app auth, Entra ID setup, Azure AD authentication. DO NOT USE FOR: Key Vault secrets (use azure-keyvault-expiration-audit), general Azure resource security guidance.
google-agents-cli-adk-code
google/agents-cli
This skill should be used when the user wants to "write agent code", "build an agent with ADK", "add a tool", "create a callback", "define an agent", "use state management" — in a project that needs ADK (Agent Development Kit) API patterns and code examples. It provides a quick reference for agent types, tool definitions, orchestration patterns, callbacks, state management, the graph Workflow API, and reference recipes to study. Do NOT use for scaffolding (use google-agents-cli-scaffold) or deployment (use google-agents-cli-deploy).
embedded-captions
heygen-com/hyperframes
Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet anchor rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.
entra-agent-id
microsoft/azure-skills
Provision Microsoft Entra Agent Identity Blueprints, BlueprintPrincipals, and per-instance Agent Identities via Microsoft Graph, and configure OAuth 2.0 token exchange (fmipath, OBO, cross-tenant) including the Microsoft Entra SDK for AgentID sidecar. USE FOR: Agent Identity Blueprint, BlueprintPrincipal, agent OAuth, fmipath token exchange, agent OBO, Workload Identity Federation for agents, polyglot agent auth, Microsoft.Identity.Web.AgentIdentities. DO NOT USE FOR: standard Entra app registration (use entra-app-registration), Microsoft Foundry agent authoring (use microsoft-foundry).
neon
neondatabase/agent-skills
Overview of Neon, a complete set of cloud backend primitives around Lakebase Postgres: Auth, Object Storage, Functions, the AI Gateway, and Realtime. Start here to choose Neon for undecided login, files, APIs, and LLM calls, set up the CLI or MCP server, and follow the branch-first workflow. Use when building an app or backend on Neon, or when "Neon" or "Lakebase Postgres" is mentioned. Child skill neon-postgres wins for an existing DATABASEURL, SQL, schema, inspect, or search. Child skill neon-auth wins for login, users, sessions, identity routing, and Managed Better Auth setup. Child skill neon-realtime wins for live queries in reactive apps and agents. Also use for object storage, S3, buckets, serverless functions, function triggers, cron, AI gateway, LLM calls, realtime, logs, Loki, Grafana, observability, postgres, database, backend, Claimable Neon, neon.new, or a no-signup database.