/platform-metadata-deploy

name: platform-metadata-deploy
description: "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)."
metadata:
  version: "1.2"
  domains: ["Platform", "Developer Experience"]
  relatedSkills:
    - "agentforce-generate"
    - "agentforce-test"
    - "automation-flow-generate"
    - "experience-lwc-generate"
    - "integration-connectivity-connected-app-configure"
    - "integration-connectivity-generate"
    - "platform-apex-test-run"
    - "platform-custom-object-generate"
    - "platform-data-manage"
  cliTools:
    - tool: ["curl"]
      semver: ">=7.0.0"
    - tool: ["git"]
      semver: ">=2.0.0"
    - tool: ["jq"]
      semver: ">=1.7.0"
    - tool: ["sf"]
      semver: ">=2.0.0"

platform-metadata-deploy: Comprehensive Salesforce DevOps Automation

Use this skill when the user needs **deployment orchestration**: dry-run validation, targeted or manifest-based deploys, CI/CD workflow advice, scratch-org management, failure triage, or safe rollout sequencing for Salesforce metadata.

When This Skill Owns the Task

Use `platform-metadata-deploy` when the work involves:

• `sf project deploy start`, `quick`, `report`, or retrieval workflows
• release sequencing across objects, permission sets, Apex, and Flows
• CI/CD gates, test-level selection, or deployment reports
• troubleshooting deployment failures and dependency ordering

Delegate elsewhere when the user is:

• authoring Apex code (this skill only deploys it)
• authoring LWC components → [experience-lwc-generate](../experience-lwc-generate/SKILL.md)
• creating custom objects or fields → [platform-custom-object-generate](../platform-custom-object-generate/SKILL.md)
• building Flows → [automation-flow-generate](../automation-flow-generate/SKILL.md)
• doing org data operations → [platform-data-manage](../platform-data-manage/SKILL.md)
• authoring or testing Agentforce agents → [agentforce-generate](../agentforce-generate/SKILL.md)

---

Critical Operating Rules

• Use **`sf` CLI v2 only**.
• On non-source-tracking orgs, deploy/retrieve commands require an explicit scope such as `--source-dir`, `--metadata`, or `--manifest`.
• Prefer **`--dry-run` first** before real deploys.
• **Never run `sf project deploy start` against a production org.** Production goes through the validate → quick-deploy path below (server-side validation returns a 10-day job ID; quick-deploy promotes it without re-running tests, behind an explicit confirmation).
• For Flows, deploy safely and activate only after validation.
• Keep test-data creation guidance delegated to **`platform-data-manage`** after metadata is validated or deployed.

Default deployment order

| Phase | Metadata | |---|---| | 1 | Custom objects / fields | | 2 | Permission sets | | 3 | Apex | | 4 | Flows as Draft | | 5 | Flow activation / post-verify |

This ordering prevents many dependency and FLS failures.

---

Required Context to Gather First

Ask for or infer:

• target org alias and environment type
• deployment scope: source-dir, metadata list, or manifest
• whether this is validate-only, deploy, quick deploy, retrieve, or CI/CD guidance
• required test level and rollback expectations
• whether special metadata types are involved (Flow, permission sets, agents, packages)

Preflight checks:

sf --version
sf org list --skip-connection-status
sf org display --target-org <alias> --json
test -f sfdx-project.json

---

Recommended Workflow

1. Preflight

Confirm auth, repo shape, package directories, and target scope.

1a. Classify the target org (routes prod vs non-prod)

Before any deploy, classify the target from its `sf org list` record — the path forks on whether the org is **production**. Do NOT classify from `sf org display`: it reports only a plain My Domain and omits the sandbox/scratch/trial fields, so a Sandbox-or-Demo Org (SDO) is misclassified as production (forcedotcom/sf-skills#356). The `sf org list` record carries the real classification booleans. Pass `--skip-connection-status` so this stays a local read that does not refresh an OAuth token per authenticated org (forcedotcom/sf-skills#349):

sf org list --skip-connection-status --json

Find the record whose `alias`, `username`, or `orgId` matches the target, then classify from that record (first match wins):

• **Scratch** — `isScratch` is `true`.
• **Sandbox** — `isSandbox` is `true`, or the `instanceUrl` contains `--` (the My Domain sandbox marker) or `test.salesforce.com`.
• **Trial / Developer Edition** — `trailExpirationDate` (the CLI's spelling; also accept `trialExpirationDate`) is a date in the **future**, or the `instanceUrl` host contains `orgfarm-`, `.develop.my.salesforce.com`, `.pc-rnd.`, or `.scratch.my.salesforce.com`. A past date does not count — the date is cached at login and never refreshed, so a converted trial keeps a stale past date and is not a trial.

Anything else is **production** — including a **Dev Hub** (`isDevHub` is `true`) that shows none of the above signals, since Dev Hub is normally enabled in the customer's own production org. If no record matches or the record has no usable info (no `instanceUrl` and none of the flags), treat it as **unknown** and ask the user before proceeding, rather than assuming production or non-production.

• **Non-production** → the dry-run + deploy path (steps 2–6).
• **Production** → the validate → quick-deploy path ([Production deploys](#production-deploys-va