@salesforce/afv-skills 1.24.0 → 1.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/afv-skills",
-  "version": "1.24.0",
+  "version": "1.25.0",
   "description": "Salesforce skills for Agentforce Vibes",
   "license": "CC-BY-NC-4.0",
   "files": [

package/skills/commerce-b2b-open-code-components-replace/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: commerce-b2b-open-code-components-replace
+description: "Replace OOTB (out-of-the-box) B2B Commerce components with open source equivalents in site metadata content.json files, or look up the equivalent open code `site:` component for OOTB definitions. Use when users mention \"replace OOTB components\", \"replace commerce components with open code\", \"swap OOTB for open source\", \"replace commerce_builder:\", \"replace OOTB in site\", \"replace component in site metadata\", \"replace component definition\", \"find open code equivalent\", \"equivalent open code component\", \"OOTB to open code mapping\", \"what is the site component for\", components \"in this view\" or \"for a given view\", or a specific list of component names — and want to update or only discover mappings in their store metadata."
+allowed-tools: Bash(grep:*) Bash(ls:*) Read Write
+metadata:
+  version: "1.0"
+---
+
+# Replacing OOTB B2B Commerce Components with Open Code
+
+This skill replaces OOTB (out-of-the-box) B2B Commerce component definitions in site metadata `content.json` files with their open source `site:` equivalents, or looks up the equivalent open code component for given OOTB definitions without making changes. It uses an authoritative mapping loaded from `assets/ootb-to-open-code-mapping.json`.
+
+## Scope
+
+**Modes:** **Full replace** runs the scan (Step 1), user selection if needed, then `content.json` updates (Step 2–3). **Lookup only** (user asks for equivalents but not to change files): apply the mapping-authority rule and report OOTB → `site:` for the named components or for definitions found in the scoped `content.json` — **do not** call Write unless the user confirms replacement. **View-scoped** work: limit file discovery and reads to `sfdc_cms__view/<ViewName>/` (or the path the user gives) instead of all views.
+
+---
+
+## Prerequisites
+
+### Resolve `<package-dir>`
+
+Read `sfdx-project.json` and pick the active package directory. Extract `packageDirectories[]` and use the entry with `"default": true`; if no entry is flagged default, use the first entry. Use this value as `<package-dir>` everywhere below. If `sfdx-project.json` is missing or has no `packageDirectories`, tell the user and abort.
+
+### Delegate setup
+
+Before replacing components, delegate to the **commerce-b2b-open-code-components-integrate** skill to ensure:
+
+1. Open source repository is cloned at `.tmp/b2b-commerce-open-source-components`
+2. Store is selected and site metadata is retrieved locally
+3. Open code components are copied to the store's site metadata
+
+The integrating skill owns the `.tmp/` clone lifecycle (it prompts the user to reuse or re-clone an existing checkout); this skill assumes the clone is already present.
+
+Send a plain-text chat reply to the user (per Rule 1): "Before replacing components, I need to verify that the open code components are set up in your store. Let me check..."
+
+If any prerequisite is not met, the integrating skill will handle it. Once all checks pass, proceed to the replacement workflow.
+
+**Required state** after prerequisites:
+- **Package dir** — the value resolved above (e.g., `force-app`)
+- **Store name** — e.g., `My_B2B_Store1`
+- **Site metadata path** — `<package-dir>/main/default/digitalExperiences/site/<store-name>/`
+
+---
+
+## Replacement Workflow
+
+### Step 1: Scan Site and Cross-Reference Mapping
+
+**This step is MANDATORY.** Always scan the site first before attempting any replacements.
+
+Send a plain-text chat reply to the user (per Rule 1): "I'm scanning your store's site metadata to find all OOTB commerce components currently in use and checking which have open code equivalents."
+
+**Step 1a — Find affected files** (one command, simple literal match):
+
+```bash
+grep -rl '"commerce' \
+  <package-dir>/main/default/digitalExperiences/site/<store-name>/sfdc_cms__view/ \
+  <package-dir>/main/default/digitalExperiences/site/<store-name>/sfdc_cms__themeLayout/ \
+  --include="content.json"
+```
+
+**Step 1b — Read the mapping and parse the matched files.** Read `assets/ootb-to-open-code-mapping.json` once into memory. Then, using the **Read** tool, parse each matched file and extract all `"definition"` values that start with `commerce` (e.g., `commerce_builder:cartBadge`). Collect a deduplicated list of OOTB components across all files.
+
+**Step 1c — List repo components** (one command):
+
+```bash
+ls .tmp/b2b-commerce-open-source-components/force-app/main/default/sfdc_cms__lwc/
+```
+
+Using the parsed definitions, the `ls` output, and the mapping table, categorize every discovered OOTB component into three groups:
+
+**Show the user a breakdown and a selectable list:**
+
+First, inform the user about skipped and unmapped components:
+```text
+Found X OOTB components in your site:
+
+In mapping table but NOT in repo (skipping):
+  - commerce_builder:quoteSummary → site:quoteSummary (not found in repo)
+
+No mapping available (not in mapping table):
+  - commerce_builder:actionButtons
+  - commerce_builder:layoutHeaderOne
+  - commerce_builder:searchInputContainer
+  - commerce_builder:myAccountMegaMenu
+```
+
+Then present the replaceable components as a **multi-select list** so the user can pick from checkboxes instead of typing. Include an "All of the above" option:
+
+```text
+Which components would you like to replace?
+
+☐ commerce_builder:heading → site:productHeading
+☐ commerce_builder:cartBadge → site:cartBadge
+☐ commerce_builder:searchInput → site:searchInput
+☐ All of the above
+```
+
+If user provided specific component name(s) in the original request, pre-filter to those and skip the selection prompt.
+
+### Step 2: Replace in content.json
+
+Send a plain-text chat reply to the user (per Rule 1): "I'm now replacing the selected OOTB component definitions with their open code equivalents in your site's content.json files."
+
+The affected files are already known from Step 1. For each file that contains selected components:
+1. Use the **Read** tool to read the file
+2. For each selected OOTB component, confirm again that the mapped **`site:`** target exists in the open code repo. Only proceed with replacements that pass this check.
+3. Replace all matching `"definition"` values with their mapped open code equivalents — **always** use the exact `site:<name>` string from the mapping table
+   - Example: `"definition": "commerce_builder:heading"` → `"definition": "site:productHeading"`
+4. Use the **Write** tool to save the updated file
+5. Preserve all other JSON properties — only `"definition"` values change
+
+**Batch efficiently:** if a file contains multiple OOTB components, apply ALL replacements in a single Read → modify → Write pass. Do NOT read and write the same file multiple times.
+
+### Step 3: Report
+
+```text
+✅ Replacement Complete!
+
+Replaced X components across Y files:
+- commerce_builder:heading → site:productHeading (3 files)
+- commerce_builder:cartBadge → site:cartBadge (2 files)
+- commerce_builder:searchInput → site:searchInput (4 files)
+
+Skipped (not in repo):
+- commerce_builder:quoteSummary
+
+No mapping available (left unchanged):
+- commerce_builder:actionButtons
+- commerce_builder:layoutHeaderOne
+- commerce_builder:searchInputContainer
+
+Modified files:
+- sfdc_cms__view/Home/content.json
+- sfdc_cms__view/Product_Detail/content.json
+- sfdc_cms__themeLayout/DefaultTheme/content.json
+
+Next Steps:
+1. Deploy: sf project deploy start -d <package-dir>/main/default/digitalExperiences/site/<store-name>
+2. Test the store thoroughly in Experience Builder
+3. Publish your site when ready
+```
+
+---
+
+## Example Interaction
+
+**User:** "Replace OOTB components with open code versions"
+
+**Agent:** "Before replacing components, I need to verify that the open code components are set up in your store. Let me check..."
+- ✓ Open source repo cloned
+- ✓ Store metadata available for My_B2B_Store1
+- ✓ Open code components are integrated
+
+**Agent:** "I'm scanning your store's site metadata to find all OOTB commerce components and checking which have open code equivalents."
+
+_(Runs grep -rl to find files with commerce definitions, Reads those files to extract component names, runs ls to list repo components, then cross-references with mapping table)_
+
+```text
+Found 8 OOTB components in your site:
+
+No mapping available (not in mapping table):
+  - commerce_builder:searchInputContainer
+  - commerce_builder:layoutHeaderOne
+  - commerce_builder:myAccountMegaMenu
+  - commerce_builder:actionButtons
+```
+
+**Agent** _(asks the user via a multi-select prompt):_
+```text
+Which components would you like to replace?
+
+☐ commerce_builder:heading → site:productHeading
+☐ commerce_builder:cartBadge → site:cartBadge
+☐ commerce_builder:searchInput → site:searchInput
+☐ commerce_builder:cartSummary → site:cartSummary
+☐ All of the above
+```
+
+**User:** _(selects heading and cartBadge)_
+
+**Agent:** "I'm now replacing the selected OOTB component definitions with their open code equivalents in your site's content.json files."
+
+_(Files already known from scan — one Read/Write pass per affected file, all replacements batched)_
+
+```text
+✅ Replacement Complete!
+
+Replaced 2 components across 5 files:
+- commerce_builder:heading → site:productHeading (3 files)
+- commerce_builder:cartBadge → site:cartBadge (2 files)
+
+No mapping available (left unchanged):
+- commerce_builder:searchInputContainer
+- commerce_builder:layoutHeaderOne
+- commerce_builder:myAccountMegaMenu
+- commerce_builder:actionButtons
+
+Modified files:
+- sfdc_cms__view/Home/content.json
+- sfdc_cms__view/Product_Detail/content.json
+- sfdc_cms__themeLayout/DefaultTheme/content.json
+
+Next Steps:
+1. Deploy: sf project deploy start -d force-app/main/default/digitalExperiences/site/My_B2B_Store1
+2. Test the store thoroughly in Experience Builder
+```
+
+---
+
+## Rules
+
+1. **Always explain in chat before executing.** Before every Bash or Write tool call, send a plain-text reply in the conversation that says what the command will do and why. The explanation MUST appear as a normal chat message preceding the tool call. Do NOT embed it inside the command itself (no `echo` lines, no `#` comments), do NOT prefix it to the command, and do NOT rely solely on the tool's `description` parameter — that field is not guaranteed to be visible to the user. After the explanation, issue the tool call and wait for the user to approve it before continuing.
+2. **`assets/ootb-to-open-code-mapping.json` is the only source of truth.** Every OOTB → open-code mapping comes from that file; never guess, infer, or hallucinate component names. Each replacement's new `"definition"` MUST be the exact mapped value from the file, which always uses the `site:` namespace (e.g. `site:productHeading`). Before writing, verify the mapped target exists in the cloned open code components repo (under `.tmp/b2b-commerce-open-source-components/force-app/main/default/sfdc_cms__lwc/`); if it is not present, skip the replacement and report it under "not in repo".
+3. **Use Read and Write tools for JSON files.** Use the Read tool to parse `content.json` files and the Write tool to update them. Do NOT use bash to parse or edit JSON — no sed, awk, perl, or regex on JSON content. Bash is only for **simple file discovery** (`grep -rl`, `find`, `ls`) — never for extracting or modifying JSON values.
+4. **Minimize commands.** Batch work into as few commands as possible. Use a single grep to scan all files, a single ls to verify the repo, and one Read/Write pass per file. Do NOT run a separate command for every component or every directory.
+
+---
+
+## Error Handling
+
+| Error | Message | Action |
+|-------|---------|--------|
+| Prerequisites not met | "Open code components are not integrated yet." | Run integrating skill first |
+| No mapping found | "No mapping found for '{component}'." | Show available mappings, report as unmapped |
+| Component not in repo | "Open code component '{name}' not found in cloned repo." | Skip and inform user |
+| No OOTB components in site | "No OOTB commerce components found in site metadata." | Inform user, nothing to replace |
+| No replaceable components | "All OOTB components found are unmapped — none can be replaced." | Show the unmapped list, suggest checking for updated mappings |
+| content.json parse error | "Failed to parse content.json: {file}" | Show error, skip file, continue with remaining files |
+
+---
+
+## Verification Checklist
+
+- [ ] Prerequisites verified via integrating skill (repo, store, components)
+- [ ] Site scanned + repo verified + mapping cross-referenced in minimal commands (Step 1)
+- [ ] Each replacement uses the exact mapped `site:` definition and was verified present in the open code repo before write
+- [ ] Breakdown shown to user with three categories before proceeding
+- [ ] User selected components to replace (or provided names)
+- [ ] Each `content.json` file updated in a single Read → modify → Write pass
+- [ ] JSON structure preserved, no syntax errors introduced
+- [ ] User informed of skipped and unmapped components
+- [ ] Deployment command provided

package/skills/commerce-b2b-open-code-components-replace/assets/ootb-to-open-code-mapping.json

@@ -0,0 +1,66 @@
+{
+  "commerce_builder:actionButton": "site:commonButton",
+  "commerce_builder:b2bCartContents": "site:cartB2bCartContents",
+  "commerce_builder:cartAppliedPromotion": "site:cartPromotionApplied",
+  "commerce_builder:cartApplyCoupon": "site:cartApplyCoupon",
+  "commerce_builder:cartBadge": "site:cartBadge",
+  "commerce_builder:cartPromotions": "site:cartPromotions",
+  "commerce_builder:cartSummary": "site:cartSummary",
+  "commerce_builder:checkoutButton": "site:checkoutButton",
+  "commerce_builder:checkoutDeliveryAddress": "site:checkoutDeliveryAddress",
+  "commerce_builder:checkoutDeliveryMethod": "site:checkoutDeliverymethod",
+  "commerce_builder:checkoutGiftOptions": "site:checkoutGiftOptions",
+  "commerce_builder:checkoutNotification": "site:checkoutNotification",
+  "commerce_builder:checkoutPurchaseOrder": "site:checkoutPurchaseOrder",
+  "commerce_builder:checkoutShippingInstructions": "site:checkoutShippingInstructions",
+  "commerce_builder:checkoutSubscriptionPolicyDisclaimer": "site:checkoutSubscriptionPolicyDisclaimer",
+  "commerce_builder:consentBlanket": "site:legalConsentBlanket",
+  "commerce_builder:countryPickerV2": "site:commonCountryPicker",
+  "commerce_builder:drilldownNavigation": "site:commonDrilldownNavigation",
+  "commerce_builder:formattedCurrency": "site:commonFormattedCurrency",
+  "commerce_builder:heading": "site:productHeading",
+  "commerce_builder:layoutFooter": "site:layoutFooter",
+  "commerce_builder:layoutHeaderSimple": "site:layoutHeaderSimple",
+  "commerce_builder:linkList": "site:commonLinksList",
+  "commerce_builder:myAccountAddressContainer": "site:myaccountAddress",
+  "commerce_builder:navigationMenuItemList": "site:myaccountNavigationMenuItems",
+  "commerce_builder:orderConfirmationBillingDetails": "site:orderConfirmationDetailsBilling",
+  "commerce_builder:orderConfirmationDeliveryGroup": "site:orderConfirmationDeliverygroup",
+  "commerce_builder:orderConfirmationErrorMessage": "site:orderConfirmationMessageError",
+  "commerce_builder:orderConfirmationSuccessMessage": "site:orderConfirmationMessageSuccess",
+  "commerce_builder:orderDetails": "site:orderDetails",
+  "commerce_builder:orderList": "site:orderList",
+  "commerce_builder:orderListDateFilter": "site:orderListDateFilter",
+  "commerce_builder:orderProductsInfo": "site:orderProducts",
+  "commerce_builder:orderPromotionsSummary": "site:orderPromotions",
+  "commerce_builder:orderShipmentTracker": "site:orderShipmentTracker",
+  "commerce_builder:paymentByExpress": "site:paymentByExpress",
+  "commerce_builder:productAttachments": "site:productAttachments",
+  "commerce_builder:productBundle": "site:productBundle",
+  "commerce_builder:productBundleItem": "site:productBundleItem",
+  "commerce_builder:productFieldsTable": "site:productFieldsTable",
+  "commerce_builder:productFrequentlyBoughtTogether": "site:productFrequentlyBoughtTogether",
+  "commerce_builder:productMediaGallery": "site:productMediaGallery",
+  "commerce_builder:productPricingDetails": "site:productPricingDetails",
+  "commerce_builder:productSellingModelSelector": "site:productSellingmodelSelector",
+  "commerce_builder:productSet": "site:productSet",
+  "commerce_builder:promotionDiscountsApproaching": "site:promotionDiscountsApproaching",
+  "commerce_builder:purchaseOptions": "site:productPurchaseOptions",
+  "commerce_builder:purchasedProducts": "site:productListPurchased",
+  "commerce_builder:quickOrder": "site:orderQuickOrder",
+  "commerce_builder:quoteSummary": "site:quoteSummary",
+  "commerce_builder:searchFilters": "site:searchFilters",
+  "commerce_builder:searchInput": "site:searchInput",
+  "commerce_builder:searchNoResultsLayout": "site:searchResultsLayoutEmpty",
+  "commerce_builder:searchResults": "site:searchResults",
+  "commerce_builder:searchResultsLayout": "site:searchResultsLayout",
+  "commerce_builder:searchSortMenu": "site:searchSortMenu",
+  "commerce_builder:socialLinks": "site:commonLinksSocial",
+  "commerce_builder:splitShipmentHeader": "site:cartSplitshipmentHeader",
+  "commerce_builder:stickyContainer": "site:commonContainerSticky",
+  "commerce_builder:subscriptions": "site:productSubscriptions",
+  "commerce_builder:userProfileMenu": "site:myAccountUserProfileMenu",
+  "commerce_builder:variantSelector": "site:productVariantSelector",
+  "commerce_builder:wishlist": "site:productWishlist",
+  "commerce_builder:wishlistShortcut": "site:productWishlistShortcut"
+}

package/skills/dx-org-manage/SKILL.md

@@ -0,0 +1,192 @@
+---
+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.0"
+  minApiVersion: "60.0"
+  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:** Write command output to JSON only when an output directory is available. After executing the command: (1) if the user specified an output path, write there; (2) otherwise run `[ -d force-app/main/adk-eval-output/ ] && echo 'force-app/main/adk-eval-output'` to detect the eval directory; (3) if the command printed a path, write the command's JSON response to `<printed-path>/<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. The eval framework needs the real command output to verify success.
+
+---
+
+## 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:**
+```bash
+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:**
+```bash
+sf org create scratch --definition-file <path> --target-dev-hub <alias> --alias <name> --json
+```
+
+**Edition only:**
+```bash
+sf org create scratch --edition developer --target-dev-hub <alias> --alias <name> --json
+```
+
+**From snapshot:**
+```bash
+sf org create scratch --snapshot <snapshot-name> --target-dev-hub <alias> --alias <name> --json
+```
+
+**From org shape:**
+```bash
+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:
+
+```bash
+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:
+```bash
+sf config get target-dev-hub --json
+```
+- If no default Dev Hub is set, advise: `sf org login web --set-default-dev-hub`
+
+**Step 3. Execute:**
+```bash
+sf org create snapshot --source-org <orgId-or-alias> --name <SnapshotName> --target-dev-hub <devHub> --json
+```
+
+With description:
+```bash
+sf org create snapshot --source-org <orgId-or-alias> --name <SnapshotName> --description "<desc>" --target-dev-hub <devHub> --json
+```
+
+**Step 4. Report result:** Returns JSON with SnapshotId and Status. If an output directory is available (per the output artifacts rule above), write the JSON response to `<output-dir>/snapshot-result.json`.
+
+**Error handling:**
+- "NOT_FOUND" → Dev Hub doesn't have snapshot feature enabled
+- "Snapshot name already exists" → use a different unique name
+
+**When you need more detail:**
+- For complete snapshot creation workflow and flag reference → load `references/creating-snapshot.md`
+- For CLI flag reference → load `references/cli_flags.md`
+
+---
+
+## Opening Orgs
+
+**REQUIRED steps — execute in order:**
+
+**Step 1. Match user request to command:**
+
+| User wants | Command |
+|-----------|---------|
+| Open default org | `sf org open --json` |
+| Open specific org | `sf org open --target-org <alias> --json` |
+| Specific browser | `sf org open --browser chrome --json` |
+| Incognito mode | `sf org open --private --json` |
+| Navigate to path | `sf org open --path '<path>' --json` |
+| URL only (don't open) | `sf org open --url-only --json` |
+| Open metadata file | `sf org open --source-file <file-path> --json` |
+
+**Step 2. Execute the matching command using the Bash tool.**
+
+**Step 3. Report result:** Returns URL or opens browser. If an output directory is available (per the output artifacts rule above), write the JSON response to `<output-dir>/org-url-result.json`.
+
+**Error handling:**
+- "no target org" → advise `sf config set target-org <alias>`
+- "auth error" → advise `sf org login web --alias <alias>`
+
+**When you need more detail:**
+- For complete opening org workflow and all available flags → load `references/opening-org.md`
+
+---
+
+## Reference File Index
+
+Load these reference files for detailed guidance:
+
+| File | When to read |
+|------|-------------|
+| `references/definition_file_options.md` | User needs to configure org features, settings, or advanced definition file options beyond basic org creation |
+| `references/edition_types.md` | User asks which edition to choose or needs to understand edition differences |
+| `references/snapshot_usage.md` | User wants to use snapshots in definition files or needs post-snapshot workflow guidance |
+| `references/creating-scratch-org.md` | Troubleshooting scratch org creation failures or need complete workflow with all options |
+| `references/cli_flags.md` | User needs complete snapshot CLI flag reference |
+| `references/creating-snapshot.md` | Troubleshooting snapshot creation failures or need detailed snapshot workflow |
+| `references/opening-org.md` | User needs to navigate to specific setup paths, open metadata files, or use advanced open flags |
+
+## Example Files
+
+Example command outputs for testing and troubleshooting:
+
+| File | Purpose |
+|------|---------|
+| `examples/scratch-orgs/success_definition_file.json` | Successful scratch org creation using `--definition-file` |
+| `examples/scratch-orgs/success_edition.json` | Successful scratch org creation using `--edition developer` |
+| `examples/scratch-orgs/success_snapshot.json` | Successful scratch org creation using `--snapshot` |
+| `examples/scratch-orgs/error_no_devhub.json` | Error when Dev Hub not authenticated |
+| `examples/scratch-orgs/error_timeout.json` | Timeout error during org creation (exit code 69) |
+| `examples/snapshots/success_output.json` | Successful snapshot creation |
+| `examples/snapshots/error_output.json` | Common snapshot error scenarios |

package/skills/dx-org-manage/examples/README.md

@@ -0,0 +1,45 @@
+# Examples Directory
+
+This directory contains example outputs for the three workflows supported by the `dx-org-manage` skill.
+
+## Structure
+
+```text
+examples/
+├── README.md                          # This file
+├── scratch-orgs/                      # Scratch org creation examples
+│   ├── success_definition_file.json
+│   ├── success_edition.json
+│   ├── error_no_devhub.json
+│   └── error_timeout.json
+└── snapshots/                         # Snapshot creation examples
+    ├── success_output.json
+    └── error_output.json
+```
+
+## scratch-orgs/
+
+Examples of `sf org create scratch` command outputs for all four creation methods.
+
+- **success_definition_file.json** - Successful creation using `--definition-file`
+- **success_edition.json** - Successful creation using `--edition developer`
+- **success_snapshot.json** - Successful creation using `--snapshot`
+- **error_no_devhub.json** - Error when Dev Hub not authenticated
+- **error_timeout.json** - Timeout error (exit code 69)
+
+## snapshots/
+
+Examples of `sf org create snapshot` command outputs.
+
+- **success_output.json** - Successful snapshot creation
+- **error_output.json** - Common error scenarios (NOT_FOUND, duplicate name, etc.)
+
+## Usage
+
+These examples help illustrate:
+1. Expected JSON/text response formats
+2. Common error patterns
+3. How to parse success indicators (`username`, `orgId`, etc.)
+4. Async operation handling (snapshot creation, timeout scenarios)
+
+Reference these when building eval datasets or troubleshooting command outputs.

package/skills/dx-org-manage/examples/scratch-orgs/error_no_devhub.json

@@ -0,0 +1,9 @@
+{
+  "status": 1,
+  "name": "NoDefaultEnvFound",
+  "message": "No default Dev Hub org found. Set a default Dev Hub org using 'sf config set target-dev-hub <username|alias>'.",
+  "exitCode": 1,
+  "context": "ScratchOrgCreateCommand",
+  "stack": "NoDefaultEnvFound: No default Dev Hub org found...",
+  "warnings": []
+}

package/skills/dx-org-manage/examples/scratch-orgs/error_timeout.json

@@ -0,0 +1,13 @@
+{
+  "status": 69,
+  "name": "ScratchOrgCreateTimeoutError",
+  "message": "The scratch org did not complete within your wait time (2 minutes).",
+  "exitCode": 69,
+  "context": "ScratchOrgCreateCommand",
+  "data": {
+    "requestId": "2SR5g000000BlYjGAK",
+    "resumeCommand": "sf org resume scratch --job-id 2SR5g000000BlYjGAK --json"
+  },
+  "stack": "ScratchOrgCreateTimeoutError: The scratch org did not complete...",
+  "warnings": []
+}

package/skills/dx-org-manage/examples/scratch-orgs/success_definition_file.json

@@ -0,0 +1,28 @@
+{
+  "status": 0,
+  "result": {
+    "username": "test-abcd1234@example.com",
+    "orgId": "00D5g000008xYZ1EAM",
+    "scratchOrgInfo": {
+      "Id": "2SR5g000000BlYjGAK",
+      "Edition": "Developer",
+      "Status": "Active",
+      "SignupUsername": "test-abcd1234@example.com",
+      "AdminEmail": "admin@example.com",
+      "Namespace": null,
+      "OrgName": "My Company",
+      "ConnectedAppConsumerKey": "3MVG9...",
+      "ScratchOrg": "00D5g000008xYZ1EAM",
+      "CreatedDate": "2026-06-12T15:10:00.000+0000",
+      "ExpirationDate": "2026-06-19"
+    },
+    "authFields": {
+      "accessToken": "00D5g...",
+      "instanceUrl": "https://...-dev-ed.develop.my.salesforce.com",
+      "username": "test-abcd1234@example.com",
+      "orgId": "00D5g000008xYZ1EAM",
+      "loginUrl": "https://test.salesforce.com"
+    },
+    "warnings": []
+  }
+}

package/skills/dx-org-manage/examples/scratch-orgs/success_edition.json

@@ -0,0 +1,26 @@
+{
+  "status": 0,
+  "result": {
+    "username": "test-xyz5678@example.com",
+    "orgId": "00D5g000009aBC2EAM",
+    "scratchOrgInfo": {
+      "Id": "2SR5g000000CdEfGHI",
+      "Edition": "Developer",
+      "Status": "Active",
+      "SignupUsername": "test-xyz5678@example.com",
+      "AdminEmail": "dev@example.com",
+      "Namespace": null,
+      "OrgName": "Company",
+      "ScratchOrg": "00D5g000009aBC2EAM",
+      "CreatedDate": "2026-06-12T15:15:00.000+0000",
+      "ExpirationDate": "2026-06-19"
+    },
+    "authFields": {
+      "accessToken": "00D5g...",
+      "instanceUrl": "https://...-dev-ed.develop.my.salesforce.com",
+      "username": "test-xyz5678@example.com",
+      "orgId": "00D5g000009aBC2EAM"
+    },
+    "warnings": []
+  }
+}